API de tâches programmées

Vue d'ensemble

Le niveau API prend en charge la fonction de planification.

Il s'agit d'un module d'exécution de tâches relativement indépendant qui maintient un objet Schedule.

Remarque : Appelez la fonction API pour interroger, mettre à jour ou supprimer les informations de Schedule.

Validation de l'appel

Pour plus d'informations, consultez la Méthode d'authentification

Description des paramètres de Schedule

Chaque tâche planifiée comprend les champs suivants : name, enabled, trigger, push.

Mot-clé	Type	Optionnel	Description
name	string	requis	Le nom de la tâche planifiée, ne peut pas dépasser 255 octets et doit être composé de caractères chinois, de lettres, de chiffres et de tirets bas.
enabled	bool	requis	Le statut actuel de la tâche. Doit être true lors de la création d'une tâche.
trigger	Objet JSON	requis	Les conditions de déclenchement et la planification de la tâche. Prend actuellement en charge les tâches uniques (`single`), périodiques (`periodical`) et la livraison intelligente (`intelligent`).
push	Objet JSON	requis	Informations sur le contenu push.

Description Single

Décrit les conditions de déclenchement de la tâche planifiée, y compris l'heure de déclenchement et le type de tâche.

Paramètre	Type	Optionnel	Description
time	String	Non	L'heure de déclenchement de la tâche, au format standard "yyyy-mm-dd hh:mm:ss", par exemple "2014-02-15 13:16:59". Les formats incomplets comme "2014-2-15 13:16:59" ou "2014-12-15 13:16" ne sont pas acceptés. L'heure la plus éloignée ne peut pas dépasser un an.
zone_type	Int	Non	Indique le type de tâche planifiée : 1 pour déclenchement selon le fuseau horaire du site principal, 2 pour déclenchement selon le fuseau horaire du terminal utilisateur.

Description Periodical

Paramètre	Type	Optionnel	Description
start	String	Non	Heure de début effective de la tâche périodique, strictement au format "yyyy-MM-dd HH:mm:ss", en 24h.
end	String	Non	Heure d'expiration de la tâche périodique, même format que ci-dessus. La durée maximale ne doit pas dépasser un an.
time	String	Non	Heure précise de déclenchement, format strict "HH:mm:ss", en 24h.
time_unit	String	Non	Plus petite unité de temps d'exécution de la tâche, trois options : "day", "week", "month". Insensible à la casse.
point	String	Non	Liste correspondant à time_unit : voir le tableau ci-dessous.
zone_type	Int	Non	Indique le type de tâche planifiée : 1 pour le fuseau du site principal, 2 pour le fuseau du terminal utilisateur.

Informations détaillées sur le paramètre point :

time_unit	point	Description
day	NULL	Quand time_unit est day, point n'est pas applicable.
week	"MON","TUE","WED","THU","FRI","SAT","SUN"	Pour week, point peut être un ou plusieurs jours, indique quand déclencher, insensible à la casse.
month	"01","02","03" ... "31"	Pour month, point correspond aux dates valides du mois, ne déclenche pas sur des dates invalides (ex : 31 ou 30 février).

Description Intelligent

Paramètre	Type	Obligatoire ou non	Signification
backup_time	String	Obligatoire	La livraison intelligente est une fonctionnalité unique d'EngageLab, conçue pour optimiser le taux de clics des notifications. À chaque accès d'un utilisateur à votre service via un site web ou une application mobile avec le SDK EngageLab installé, nous suivons le dernier moment d'activité de l'utilisateur. Le système enregistre ces données et, selon les habitudes d'utilisation passées, envoie des notifications à chaque utilisateur au moment opportun selon le fuseau horaire du terminal. Pour les utilisateurs sans historique actif, vous devez choisir d'envoyer immédiatement ou de spécifier une heure (basée sur le fuseau de l'utilisateur final). Pour envoi immédiat : now Pour envoi programmé : format strict "yyyy-MM-dd HH:mm:ss", en 24h.

Créer une tâche planifiée

Requête API task

POST v4/schedules

Restrictions d'appel

Le nombre total de tâches planifiées valides (non expirées) est de 1000 par défaut. Si ce nombre est dépassé, la création échoue.
La durée maximale d'une tâche est illimitée, mais il est recommandé de ne pas dépasser 1 an.

Exemple de requête

En-tête de la requête

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

Afficher ce bloc de code dans la fenêtre flottante

Corps de la requête

{ "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"
    }
    }
}

Afficher ce bloc de code dans la fenêtre flottante

Description du corps de la requête

zone_type est obligatoire, valeur 1 ou 2, sinon le push se fait selon le fuseau du serveur.
enabled doit être true à la création. Impossible de créer une tâche avec enabled: false, sinon échec de la création.
push doit être une action push valide, sinon la création échoue.

Exemple de retour

Retour succès

< 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

Afficher ce bloc de code dans la fenêtre flottante

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

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

Afficher ce bloc de code dans la fenêtre flottante

Retour erreur

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

Afficher ce bloc de code dans la fenêtre flottante

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

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

Afficher ce bloc de code dans la fenêtre flottante

Exemple de requête pour tâche planifiée répétée

{ "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"
    }
    }
}

Afficher ce bloc de code dans la fenêtre flottante

Obtenir la liste des tâches planifiées valides

Récupère la liste des schedules actuellement valides (non expirés).

URL de l'API de requête

GET v4/schedules?page=

Exemple de requête

En-tête de la requête

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

Afficher ce bloc de code dans la fenêtre flottante

Retourne la liste détaillée des tâches planifiées de la page demandée. Si aucune page n'est spécifiée, la page est 1.
Règle de tri : par date de création, gérée par le service de schedule.
Si le numéro de page demandé est supérieur au nombre total de pages, la page est la valeur demandée et la liste est vide.
Chaque page peut retourner jusqu'à 50 tâches. Si la page contient moins de 50 tâches, le nombre réel est retourné.

Exemple de retour

Retour succès

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

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

Afficher ce bloc de code dans la fenêtre flottante

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

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

Afficher ce bloc de code dans la fenêtre flottante

1000 tâches planifiées, 5 pages au total, la page actuelle est la 4, incluant 50 tâches planifiées.
Le tableau schedules est la liste détaillée des tâches planifiées.

Obtenir les détails d'une tâche planifiée

Obtenez les détails de la tâche planifiée avec l'id {schedule_id} de l'utilisateur actuel.

URL de l'API de requête

GET v4/schedules/{schedule_id}

Exemple de requête

En-tête de la requête

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

Afficher ce bloc de code dans la fenêtre flottante

Exemple de retour

Retour succès

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

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

Afficher ce bloc de code dans la fenêtre flottante

Données retournées

[{ "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": {...}
}]

Afficher ce bloc de code dans la fenêtre flottante

Si le schedule_id n'existe pas, retourne 404, sinon retourne le détail de la tâche planifiée.

Obtenir tous les ids de messages d'une tâche planifiée

Récupère tous les ids de messages de la tâche planifiée de l'utilisateur courant dont l'id est {schedule_id}

URL de l'API de requête

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

Exemple de requête

En-tête de la requête

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

Afficher ce bloc de code dans la fenêtre flottante

Exemple de réponse

Réponse réussie

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

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

Afficher ce bloc de code dans la fenêtre flottante

Données de la réponse

Le format des données retournées a été mis à jour après la mise en ligne de la fonctionnalité de tâches planifiées répétées le 22 février 2024, ajoutant le champ MsgIds pour remplacer l'ancien msgids. Veuillez vous assurer que votre code est compatible.
Le champ ts indique le timestamp d'exécution réussie de la tâche planifiée, en millisecondes.

{ "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}"
    ]
}

Afficher ce bloc de code dans la fenêtre flottante

Mettre à jour une tâche planifiée

Met à jour la tâche planifiée de l'id spécifié

URL de l'API de requête

PUT v4/schedules/{schedule_id}

Exemple de requête

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

Afficher ce bloc de code dans la fenêtre flottante

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

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

Afficher ce bloc de code dans la fenêtre flottante

Impossible de mettre à jour une tâche planifiée expirée.
Les tâches planifiées selon le fuseau du terminal et celles selon le fuseau du site principal ne peuvent pas être mises à jour l'une vers l'autre.
Vous pouvez mettre à jour un ou plusieurs champs du tableau ["name", "enabled", "trigger", "push"]. Le corps de la requête doit être complet, pas partiel. Exemples ci-dessous :

{ "name":"the scheduled task 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":"the scheduled task 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"
    }
    }
}

Afficher ce bloc de code dans la fenêtre flottante

Voici des exemples de mises à jour incorrectes et les mises à jour correctes correspondantes :

## Incorrect : mise à jour uniquement de alert dans le champ push : { "push": { "alert": "web scheduled task" } } ## Correct : mise à jour de alert dans le champ 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" } } } ## le champ push doit être valide, sinon la mise à jour échoue

              
              ## Incorrect : mise à jour uniquement de alert dans le champ push :
{
    "push": {
        "alert": "web scheduled task"
    }
}
## Correct : mise à jour de alert dans le champ 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"
    }
    }
}

## le champ push doit être valide, sinon la mise à jour échoue

Afficher ce bloc de code dans la fenêtre flottante

Exemple de retour

Retour succès

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

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

Afficher ce bloc de code dans la fenêtre flottante

{ "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"
    }
    }
}

Afficher ce bloc de code dans la fenêtre flottante

Retour erreur

schedule_id invalide

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

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

Afficher ce bloc de code dans la fenêtre flottante

Opération de mise à jour illégale

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

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

Afficher ce bloc de code dans la fenêtre flottante

Supprimer une tâche planifiée

URL de l'API de requête

DELETE v4/schedules/{schedule_id}

schedule_id est l'id d'une tâche planifiée existante. Si schedule_id est invalide ou non valide, le résultat sera une erreur 404.

Exemple de requête

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

Afficher ce bloc de code dans la fenêtre flottante

Exemple de retour

Retour succès

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

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

Afficher ce bloc de code dans la fenêtre flottante

Retour erreur

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

Afficher ce bloc de code dans la fenêtre flottante

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

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

Afficher ce bloc de code dans la fenêtre flottante

Codes d'erreur

Code	HTTP	Description	Message d'erreur	Explication détaillée
28000	200	Retour correct	-	Code de statut de succès
28100	400	Paramètre invalide	La tâche planifiée est invalide : section invalide ; a atteint son terme ; expirée ; les données de la requête ne sont pas en JSON ; mise à jour de la tâche cible ; suppression de la tâche cible ; la requête de schedule n'existe pas	Paramètres illégaux ou invalides. Push dépasse la limite (ex : push broadcast dépasse la limite, tâches planifiées dépassent la limite, tâches limitées par le taux dépassent la limite). Le corps du paramètre est trop long.
28101	401	Échec de l'authentification	Échec de l'authentification Basic.	appkey et masterSecret ne correspondent pas.
28102	400	Paramètre push invalide	push param est nul ou invalide	Paramètre push invalide, informations d'erreur spécifiques retournées.
28103	400	Paramètre d'heure push invalide	erreur de format single time ou trigger time	Paramètre d'heure push invalide, informations d'erreur spécifiques retournées.
28104	404	La tâche planifiée demandée n'existe pas	L'opération de schedule demandée n'existe pas	La tâche correspondante a été envoyée, ou l'id de schedule est incorrect.
28105	404	Aucun destinataire push pour l'heure définie	La tâche push est invalide. Aucun destinataire push pour l'heure planifiée	Erreur de paramètre d'heure push.
28200	500	Erreur interne du serveur	Erreur interne du serveur.	Une erreur inattendue est survenue.
28203	503	Erreur interne du serveur, veuillez réessayer plus tard	Délai d'action, veuillez réessayer plus tard	Erreur de communication avec le serveur de schedule.

API des tâches planifiées

Vue d'ensemble

Validation de l'appel

Description des paramètres de Schedule

Description Single

Description Periodical

Description Intelligent

Créer une tâche planifiée

Requête API task

Restrictions d'appel

Exemple de requête

Exemple de retour

Obtenir la liste des tâches planifiées valides

URL de l'API de requête

Exemple de requête

Exemple de retour

Obtenir les détails d'une tâche planifiée

URL de l'API de requête

Exemple de requête

Exemple de retour

Obtenir tous les ids de messages d'une tâche planifiée

URL de l'API de requête

Exemple de requête

Exemple de réponse

Mettre à jour une tâche planifiée

URL de l'API de requête

Exemple de requête

Exemple de retour

Supprimer une tâche planifiée

URL de l'API de requête

Exemple de requête

Exemple de retour

Codes d'erreur