API de tareas programadas

Visión general

El nivel de la API admite la función de programación.

Se trata de un módulo de ejecución de tareas relativamente independiente que mantiene un objeto Schedule.

Aviso: Llamar a la función de la API para consultar/actualizar/eliminar la información de Schedule.

Validación de llamada

Para obtener más información, consulte el Método de autenticación

Descripción de parámetros de Schedule

Cada tarea programada incluye cuatro campos: name, enabled, trigger, push.

Palabra clave	Tipo	Opcional	Descripción
name	string	required	El nombre de la tarea programada, que no puede superar los 255 bytes y consta de caracteres chinos, letras, números y guiones bajos.
enabled	bool	required	El estado actual de la tarea. Debe ser true al crear una tarea.
trigger	JSON Object	required	Las condiciones de activación y la programación de la tarea programada. Actualmente admite tareas de una sola ejecución (`single`), tareas periódicas (`periodical`) y entrega inteligente (`intelligent`).
push	JSON Object	required	Información del contenido de push.

Descripción de single

Describe las condiciones de activación de la tarea programada, incluidos la hora de activación y el tipo de tarea programada.

Parámetro	Tipo	Opcional	Descripción
time	String	No	La hora de activación de la tarea programada, en el formato de hora estándar "yyyy-mm-dd hh:mm:ss", por ejemplo, "2014-02-15 13:16:59". No se aceptan formatos incompletos como "2014-2-15 13:16:59" o "2014-12-15 13:16". La hora más tardía de una tarea programada no puede superar un año.
zone_type	Int	No	Indica el tipo de tarea programada: 1 para activar según la zona horaria establecida por el sitio principal, 2 para activar según la zona horaria del terminal del usuario.

Descripción de periodical

Parámetro	Tipo	Opcional	Descripción
start	String	No	La hora de inicio efectiva de la tarea periódica, estrictamente en el formato "yyyy-MM-dd HH:mm:ss", y debe estar en formato de 24 horas.
end	String	No	La hora de caducidad de la tarea periódica, en el mismo formato que el anterior. El intervalo máximo de una tarea periódica no debe superar un año.
time	String	No	La hora específica en la que se activa la tarea periódica, estrictamente en el formato "HH:mm:ss", y debe estar en formato de 24 horas.
time_unit	String	No	La unidad de tiempo mínima para la ejecución de la tarea periódica, con tres opciones: "day", "week" y "month". No distingue entre mayúsculas y minúsculas.
point	String	No	Una lista correspondiente a time_unit: consulte la tabla siguiente.
zone_type	Int	No	Indica el tipo de tarea programada: 1 para activar según la zona horaria establecida por el sitio principal, 2 para activar según la zona horaria del terminal del usuario.

Información detallada sobre el parámetro point:

time_unit	point	Descripción
day	NULL	Cuando time_unit es day, point no aplica.
week	"MON","TUE","WED","THU","FRI","SAT","SUN"	Para week, point puede ser uno o varios días que indican cuándo activar; no distingue entre mayúsculas y minúsculas.
month	"01","02","03" ... "31"	Para month, point corresponde a fechas válidas del mes; no se activará en fechas no válidas, como el 31 o el 30 de febrero.

Descripción de intelligent

Parámetro	Tipo	Opcional	Significado
backup_time	String	Required	La entrega inteligente es una función exclusiva de EngageLab, diseñada para optimizar la tasa de clics de las notificaciones. Cada vez que un usuario accede a su servicio a través de un sitio web o una aplicación móvil con el SDK de EngageLab instalado, se realiza el seguimiento de la hora de actividad más reciente del usuario. El sistema registrará estos datos y, en función de los hábitos de uso anteriores del usuario, enviará notificaciones a cada usuario en un momento adecuado según la zona horaria del terminal de cada usuario. Para los usuarios sin datos históricos de actividad, es necesario elegir si enviarlo inmediatamente o especificar una hora de envío (según la zona horaria del usuario final). Para envío inmediato: now Para envío programado: el formato debe ser estrictamente: "yyyy-MM-dd HH:mm:ss", y la hora debe estar en formato de 24 horas.

Crear una tarea programada

API de solicitud de tarea

POST v4/schedules

Restricciones de llamada

El número total de tareas programadas válidas (actualmente no caducadas) es 1000 de forma predeterminada. Si se supera el total, la nueva tarea programada indicará un error.
El intervalo máximo de tiempo de la tarea no está limitado, pero se recomienda no superar 1 año.

Ejemplo de solicitud

Encabezado de solicitud

POST /v4/schedules Authorization: Basic (base64 auth string) Content-Type: application/json Accept: application/json

              
              POST /v4/schedules
 Authorization: Basic (base64 auth string)
 Content-Type: application/json
 Accept: application/json

Este bloque de código se muestra en una ventana flotante

Cuerpo de la solicitud

{ "name":"schedule push example", "enabled":true, "trigger":{ "single":{ "time":"2022-11-23 19:20:00", "zone_type":1 } }, "push":{ "from":"push", "to":{ "registration_id":[ "1a0018970ab49abda3e", "100d85590955c1d2793" ] }, "body":{ "platform":"web", "notification":{ "web": { "alert": "welcome to engagelab", "title": "welcome to engagelab", "url": "https://www.engagelab.com/", "extras": { "key1": "value1" } } }, "message":{ }, "options":{ "time_to_live":60 } }, "request_id":"12345", "custom_args":{ "Engagelab": "push to you" } } }

              
              {
    "name":"schedule push example",
    "enabled":true,
    "trigger":{
        "single":{
            "time":"2022-11-23 19:20:00",
            "zone_type":1
        }
    },
    "push":{
        "from":"push",
        "to":{
            "registration_id":[
                "1a0018970ab49abda3e",
                "100d85590955c1d2793"
            ]
        },
        "body":{
            "platform":"web",
            "notification":{
                "web": {
                    "alert": "welcome to engagelab",
                    "title": "welcome to engagelab",
                    "url": "https://www.engagelab.com/",
                    "extras": {
                        "key1": "value1"
                    }
                }
            },
            "message":{

            },
            "options":{
                "time_to_live":60
            }
        },
        "request_id":"12345",
        "custom_args":{
             "Engagelab": "push to you"
        }
    }
}

Este bloque de código se muestra en una ventana flotante

Descripción del cuerpo de la solicitud

zone_type es un campo obligatorio; su valor es 1 o 2. De lo contrario, se enviará según la zona horaria del servidor.
El campo enabled debe ser true cuando se crea por primera vez. No se puede crear una tarea con enabled: false; de lo contrario, la creación fallará.
push debe ser una acción de push válida y legal; de lo contrario, la creación falla.

Ejemplo de retorno:

Retorno correcto

< HTTP/1.1 200 OK < Server: fasthttp < Date: Thu, 01 Dec 2022 07:17:45 GMT < Content-Type: application/json < Content-Length: 85

              
              < HTTP/1.1 200 OK
< Server: fasthttp
< Date: Thu, 01 Dec 2022 07:17:45 GMT
< Content-Type: application/json
< Content-Length: 85

Este bloque de código se muestra en una ventana flotante

{ "schedule_id": "a9b85590-6cec-4f91-b277-2d82b0e20ef6", "name": "the schedule task name" }

              
              {
    "schedule_id": "a9b85590-6cec-4f91-b277-2d82b0e20ef6",
    "name": "the schedule task name"
}

Este bloque de código se muestra en una ventana flotante

Retorno de error

HTTP/1.1 400 BAD REQUEST Content-Type: application/json; charset=utf-8

              
              HTTP/1.1 400 BAD REQUEST
 Content-Type: application/json; charset=utf-8

Este bloque de código se muestra en una ventana flotante

{ "error": { "code": 28400, "message": "error message" } }

              
              {
    "error": {
        "code": 28400,
        "message": "error message"
    }
}

Este bloque de código se muestra en una ventana flotante

Ejemplo de solicitud de tarea programada repetida

{ "name":"Timed Push Example_periodical", "enabled":true, "trigger":{ "periodical": { "start": "2024-01-01 00:00:00", "end": "2024-02-10 00:00:00", "time": "12:00:00", "time_unit": "day", "point": [], "zone_type": 1 } }, "push":{ "from":"push", "to":{ "registration_id":[ "1a0018970ab49abda3e", "100d85590955c1d2793" ] }, "body":{ "platform":"web", "notification":{ "web": { "alert": "welcome to engagelab", "title": "welcome to engagelab", "url": "https://www.engagelab.com/", "extras": { "key1": "value1" } } }, "message":{ }, "options":{ "time_to_live":60 } }, "request_id":"67890", "custom_args":{ "Engagelab": "push to you" } } }

              
              {
    "name":"Timed Push Example_periodical",
    "enabled":true,
    "trigger":{
        "periodical": {
            "start": "2024-01-01 00:00:00",
            "end": "2024-02-10 00:00:00",
            "time": "12:00:00",
            "time_unit": "day",
            "point": [],
            "zone_type": 1
        }
    },
    "push":{
        "from":"push",
        "to":{
            "registration_id":[
                "1a0018970ab49abda3e",
                "100d85590955c1d2793"
            ]
        },
        "body":{
            "platform":"web",
            "notification":{
                "web": {
                    "alert": "welcome to engagelab",
                    "title": "welcome to engagelab",
                    "url": "https://www.engagelab.com/",
                    "extras": {
                        "key1": "value1"
                    }
                }
            },
            "message":{

            },
            "options":{
                "time_to_live":60
            }
        },
        "request_id":"67890",
        "custom_args":{
             "Engagelab": "push to you"
        }
    }
}

Este bloque de código se muestra en una ventana flotante

Obtener una lista de tareas programadas válidas

Obtiene la lista de schedules actualmente válidos (no caducados).

URL de la API de solicitud

GET v4/schedules?page=

Ejemplo de solicitud

Encabezado de solicitud

GET /v4/schedules?page= Authorization: Basic (base64 auth string) Content-Type: application/json Accept: application/json

              
              GET /v4/schedules?page=
 Authorization: Basic (base64 auth string) 
 Content-Type: application/json
 Accept: application/json

Este bloque de código se muestra en una ventana flotante

Devuelve la lista detallada de tareas programadas de la página solicitada. Si no se especifica ninguna página, la página es 1.
Regla de ordenación: hora de creación, completada por schedule-service.
Si el número de páginas solicitado es mayor que el número total de páginas, la página será el valor solicitado y schedules estará vacío.
Cada página puede devolver hasta 50 tareas. Si el número real de tareas en la página solicitada es inferior a 50, se devolverá el número real de tareas.

Ejemplo de retorno

Retorno correcto

HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8

              
              HTTP/1.1 200 OK 
 Content-Type: application/json; charset=utf-8

Este bloque de código se muestra en una ventana flotante

{ "total_count": 1000, "total_pages": 5, "page": 4, "schedules": [ { "schedule_id": "0eac1b80-c2ac-4b69-948b-c65b34b96512", "name": "", "enabled": true }, {} ] }

              
              {
    "total_count": 1000,
    "total_pages": 5,
    "page": 4,
    "schedules": [
        {
            "schedule_id": "0eac1b80-c2ac-4b69-948b-c65b34b96512",
            "name": "",
            "enabled": true
        },
        {}
    ]
}

Este bloque de código se muestra en una ventana flotante

1000 tareas programadas, 5 páginas en total; la página actual es 4 e incluye información de 50 tareas programadas.
El array schedules es la lista detallada de tareas programadas.

Obtener los detalles de una tarea programada

Obtiene los detalles de la tarea programada con el id de tarea programada del usuario actual {schedule_id}.

URL de la API de solicitud

GET v4/schedules/{schedule_id}

Ejemplo de solicitud

Encabezado de solicitud

GET /v4/schedules/{schedule_id} Authorization: Basic (base64 auth string) Content-Type: application/json Accept: application/json

              
              GET /v4/schedules/{schedule_id}
 Authorization: Basic (base64 auth string)
 Content-Type: application/json
 Accept: application/json

Este bloque de código se muestra en una ventana flotante

Ejemplo de retorno

Retorno correcto

HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8

              
              HTTP/1.1 200 OK 
 Content-Type: application/json; charset=utf-8

Este bloque de código se muestra en una ventana flotante

Datos de retorno

[{ "schedule_id": "0eac1b80-c2ac-4b69-948b-c65b34b96512", "name": "the scheduled task example", "enabled": true, "trigger": {...}, "push": {...} }]

              
              [{
    "schedule_id": "0eac1b80-c2ac-4b69-948b-c65b34b96512",
    "name": "the scheduled task example",
    "enabled": true,
    "trigger": {...},
    "push": {...}
}]

Este bloque de código se muestra en una ventana flotante

Si el schedule_id no existe, se devuelve 404; de lo contrario, se devuelven los detalles de la tarea programada.

Obtener todos los ID de mensajes de la tarea programada

Obtiene todos los ID de mensajes de la tarea programada del usuario actual cuyo id es {schedule_id}.

URL de la API de solicitud

GET v4/schedules/{schedule_id}/msg-ids

Ejemplo de solicitud

Encabezado de solicitud

GET /v4/schedules/{schedule_id}/msg-ids Authorization: Basic (base64 auth string) Content-Type: application/json Accept: application/json

              
              GET /v4/schedules/{schedule_id}/msg-ids
 Authorization: Basic (base64 auth string)
 Content-Type: application/json
 Accept: application/json

Este bloque de código se muestra en una ventana flotante

Ejemplo de respuesta

Respuesta correcta

HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8

              
              HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

Este bloque de código se muestra en una ventana flotante

Datos de respuesta

El formato de datos devuelto se actualizó después de que la funcionalidad de tarea programada repetida se publicara el 22 de febrero de 2024, añadiendo los datos MsgIds devueltos para sustituir a los msgids antiguos. Asegúrese de que su código sea compatible.
El campo ts indica la marca de tiempo cuando la tarea programada se ejecuta correctamente, con precisión de milisegundos.

{ "count": 1, "MsgIds": [ "{\"msg_id\":\"1088009\",\"error\":{\"code\":0,\"message\":\"\"},\"needRetry\":false,\"ts\":1707278411611}", "{\"msg_id\":\"0\",\"error\":{\"code\":1011,\"message\":\"Cannot find sending target\"},\"needRetry\":false,\"ts\":1707278411611}" ] }

              
              {
    "count": 1,
    "MsgIds": [
        "{\"msg_id\":\"1088009\",\"error\":{\"code\":0,\"message\":\"\"},\"needRetry\":false,\"ts\":1707278411611}",
        "{\"msg_id\":\"0\",\"error\":{\"code\":1011,\"message\":\"Cannot find sending target\"},\"needRetry\":false,\"ts\":1707278411611}"
    ]
}

Este bloque de código se muestra en una ventana flotante

Actualizar una tarea programada

Actualiza la tarea programada del id especificado.

URL de la API de solicitud

PUT v4/schedules/{schedule_id}

Ejemplo de solicitud

PUT /v4/schedules/{schedule_id} Authorization: Basic (base64 auth string) Content-Type: application/x-www-form-urlencoded Accept: application/json

              
              PUT /v4/schedules/{schedule_id}
 Authorization: Basic (base64 auth string) 
 Content-Type: application/x-www-form-urlencoded
 Accept: application/json

Este bloque de código se muestra en una ventana flotante

{ "name": "task", "enabled": true, "trigger": {...}, "push": {...} }

              
              {
  "name": "task", 
  "enabled": true, 
  "trigger": {...},
  "push": {...} 
}

Este bloque de código se muestra en una ventana flotante

No se puede actualizar una tarea programada que haya caducado.
Las tareas programadas enviadas por la zona horaria del terminal y las tareas programadas enviadas por la zona horaria principal no son intercambiables.
Se puede actualizar uno o varios campos del array ["name", "enabled", "trigger", "push"]. El cuerpo de actualización no puede ser parcial; debe ser un cuerpo completo.
Los siguientes son ejemplos de actualizaciones incorrectas y las correspondientes actualizaciones correctas:

## Incorrecto: actualizar solo el campo alert dentro de push: { "push": { "alert": "web scheduled task" } } ## Correcto: actualizar el campo alert dentro de push: { "push":{ "from":"push", "to":{ "registration_id":[ "1a0018970ab49abda3e", "100d85590955c1d2793" ] }, "body":{ "platform":"web scheduled task", "notification":{ "web": { "alert": "welcome to engagelab", "title": "welcome to engagelab", "url": "https://www.engagelab.com/", "extras": { "key1": "value1" } } }, "message":{ }, "options":{ "time_to_live":60 } }, "request_id":"12345", "custom_args":{ "Engagelab": "push to you" } } } ## El campo push debe ser válido; de lo contrario, la actualización fallará

              
              ## Incorrecto: actualizar solo el campo alert dentro de push:
{
    "push": {
        "alert": "web scheduled task"
    }
}

## Correcto: actualizar el campo alert dentro de push:
{
    "push":{
        "from":"push",
        "to":{
            "registration_id":[
                "1a0018970ab49abda3e",
                "100d85590955c1d2793"
            ]
        },
        "body":{
            "platform":"web scheduled task",
            "notification":{
                "web": {
                    "alert": "welcome to engagelab",
                    "title": "welcome to engagelab",
                    "url": "https://www.engagelab.com/",
                    "extras": {
                        "key1": "value1"
                    }
                }
            },
            "message":{

            },
            "options":{
                "time_to_live":60
            }
        },
        "request_id":"12345",
        "custom_args":{
             "Engagelab": "push to you"
        }
    }
}

## El campo push debe ser válido; de lo contrario, la actualización fallará

Este bloque de código se muestra en una ventana flotante

Ejemplo de retorno

Retorno correcto

HTTP/1.0 200 CREATED Content-Type: application/json

              
              HTTP/1.0 200 CREATED
 Content-Type: application/json

Este bloque de código se muestra en una ventana flotante

{ "name":"Timed push example", "enabled":true, "trigger":{ "single":{ "time":"2022-11-23 19:20:00", "zone_type":1 } }, "push":{ "from":"push", "to":{ "registration_id":[ "1a0018970ab49abda3e", "100d85590955c1d2793" ] }, "body":{ "platform":"web", "notification":{ "web": { "alert": "welcome to engagelab", "title": "welcome to engagelab", "url": "https://www.engagelab.com/", "extras": { "key1": "value1" } } }, "message":{ }, "options":{ "time_to_live":60 } }, "request_id":"12345", "custom_args":{ "Engagelab": "push to you" } } }

              
              {
    "name":"Timed push example",
    "enabled":true,
    "trigger":{
        "single":{
            "time":"2022-11-23 19:20:00",
            "zone_type":1
        }
    },
    "push":{
        "from":"push",
        "to":{
            "registration_id":[
                "1a0018970ab49abda3e",
                "100d85590955c1d2793"
            ]
        },
        "body":{
            "platform":"web",
            "notification":{
                "web": {
                    "alert": "welcome to engagelab",
                    "title": "welcome to engagelab",
                    "url": "https://www.engagelab.com/",
                    "extras": {
                        "key1": "value1"
                    }
                }
            },
            "message":{

            },
            "options":{
                "time_to_live":60
            }
        },
        "request_id":"12345",
        "custom_args":{
             "Engagelab": "push to you"
        }
    }
}

Este bloque de código se muestra en una ventana flotante

Retorno de error

schedule_id no es válido

HTTP/1.0 404 Not Found Content-Type: application/json

              
              HTTP/1.0 404 Not Found
 Content-Type: application/json

Este bloque de código se muestra en una ventana flotante

Operación de actualización no permitida

HTTP/1.0 400 BAD REQUEST Content-Type: application/json

              
              HTTP/1.0 400 BAD REQUEST
 Content-Type: application/json

Este bloque de código se muestra en una ventana flotante

Eliminar una tarea programada

URL de la API de solicitud

DELETE v4/schedules/{schedule_id}

schedule_id es el id de una tarea programada existente. Si schedule_id no es válido o no es un id válido, el resultado será un error 404.

Ejemplo de solicitud

DELETE /v4/schedules/{schedule_id} Authorization: Basic (base64 auth string) Content-Type: application/json Accept: application/json

              
              DELETE /v4/schedules/{schedule_id}
 Authorization: Basic (base64 auth string)
 Content-Type: application/json
 Accept: application/json

Este bloque de código se muestra en una ventana flotante

Ejemplo de retorno

Retorno correcto

HTTP/1.0 200 Content-Type: application/json Content-Length: 0

              
              HTTP/1.0 200 
 Content-Type: application/json
 Content-Length: 0

Este bloque de código se muestra en una ventana flotante

Retorno de error

HTTP/1.0 404 Not Found Content-Type: application/json Content-Length: 0

              
              HTTP/1.0 404 Not Found 
 Content-Type: application/json
 Content-Length: 0

Este bloque de código se muestra en una ventana flotante

{ "error":{ "code":28404, "message":"error message" } }

              
              {
  "error":{
    "code":28404,
    "message":"error message"
  }
}

Este bloque de código se muestra en una ventana flotante

Códigos de error

Código	HTTP	Descripción	Mensaje de error	Explicación detallada
28000	200	Retorno correcto	-	Código de estado correcto
28100	400	Parámetro no válido	La tarea programada no es válida: la sección no es válida; ha vencido; ha caducado; los datos de la solicitud no son JSON; actualizar la tarea de destino; eliminar la tarea de destino; la solicitud de tarea programada no existe	Los parámetros son ilegales o no válidos. Push supera el límite (p. ej., envío de difusión supera el límite, tareas programadas superan el límite, tareas con limitación de velocidad superan el límite). El cuerpo del parámetro es demasiado largo.
28101	401	Error de autenticación	La autenticación básica ha fallado.	appkey y masterscrect no coinciden.
28102	400	Parámetro push no válido	el parámetro push es nil o no válido	Parámetro push no válido; se devuelve información de error específica.
28103	400	Parámetro de hora de push no válido	error de formato de la hora de single o de la hora de trigger	Parámetro de hora de push no válido; se devuelve información de error específica.
28104	404	La tarea programada solicitada no existe	La operación de schedule solicitada no existe	La tarea correspondiente se ha enviado o el ID de schedule es incorrecto.
28105	404	No hay destino de push para la hora establecida	La tarea push no es válida. No hay destino de push para la hora programada	Error en el parámetro de hora de push.
28200	500	Error interno del servidor	Error interno del servidor.	Se produjo un error inesperado.
28203	503	Error interno del servidor; reintentar más tarde	Tiempo de espera al ejecutar la acción; inténtelo de nuevo más tarde	Error de comunicación con schedule-server.