Exemple - IoT Platform - Centre de documentation Alibaba Cloud

Cet article explique comment appeler les opérations d'API de Link SDK pour C afin de mettre en œuvre des tâches sur un appareil. Cet exemple s'appuie sur le fichier de code exemple ./demos/task_posix_demo.c.

Contexte

Pour plus d'informations sur les tâches des appareils, consultez la section Vue d'ensemble.
utilise des connexions MQTT. Pour des exemples de code associés, consultez la section Connexion MQTT.

Étape 1 : Initialisation

Ajoutez les fichiers d'en-tête.
```
...
...

#include "aiot_task_api.h"
```

Configurez les dépendances sous-jacentes et la sortie des journaux.

    aiot_sysdep_set_portfile(&g_aiot_sysdep_portfile);
    aiot_state_set_logcb(demo_state_logcb);

Appelez l'opération aiot_task_init() pour créer une instance client task et initialiser les paramètres par défaut.

    task_handle = aiot_task_init();
    if (task_handle == NULL) {
        demo_mqtt_stop(&mqtt_handle);
        printf("aiot_task_init failed\n");
        return -1;
    }

Étape 2 : Configuration des fonctionnalités

Appelez l'opération aiot_task_setopt() pour configurer les éléments suivants :

Associez un handle de connexion MQTT.

Important

Avant de définir les paramètres spécifiques aux tâches des appareils, vous devez configurer les paramètres tels que les identifiants de l'appareil. Pour plus d'informations, consultez la section Configuration des paramètres de connexion pour MQTT.

Exemple de code :

    aiot_task_setopt(task_handle, AIOT_TASKOPT_MQTT_HANDLE, mqtt_handle);

Paramètres :

Paramètre	Exemple	Description
AIOT_TASKOPT_MQTT_HANDLE	mqtt_handle	Cette connexion est utilisée pour les requêtes TSL.

Configurez un rappel de message.

Exemple de code

    aiot_task_setopt(task_handle, AIOT_TASKOPT_RECV_HANDLER, demo_task_recv_handler);

Paramètres :

Paramètre	Exemple	Description
AIOT_TASKOPT_RECV_HANDLER	demo_task_recv_handler	Cette fonction est appelée lors de la réception d'un message spécifique à une tâche d'appareil.

Étape 3 : Réception d'une notification de tâche descendante

Si IoT Platform envoie une notification de tâche lorsque l'appareil est en ligne, suivez les étapes ci-dessous pour traiter la notification :

Connectez-vous à la console IoT Platform et créez une tâche d'appareil.

Une fois la tâche d'appareil créée, IoT Platform envoie une notification à l'appareil. Lorsque l'appareil reçoit cette notification, le rappel demo_task_recv_handler est appelé.

Lorsque vous définissez la logique du rappel, tenez compte des points suivants :

aiot_task_recv_t est un paramètre d'entrée du rappel. Ce paramètre indique le format des données.
AIOT_TASKRECV_NOTIFY indique le type de message.

Le tableau suivant présente un exemple de notification et le format de données Alink correspondant.

Exemple

Format de données Alink

Description

{
    "task": {
        "taskId": "i5Ks6***pF010101",
        "status": "SENT",
        "jobDocument": {

        },
        "jobFile": {
            "signMethod": "Md5",
            "sign": "wssxff56dhdsd***",
            "fileUrl": "https://iotx-***.aliyuncs.com/***.zip"
        }
    }
}

{
  "id": "7542940",
  "version": "1.0",
    "params": {
        "task": {
            "taskId": "i5Ks6***pF010101",
            "status": "SENT",
            "jobDocument": {
              },
      "jobFile":{
         "signMethod":"Md5",
         "sign":"wssxff56dhdsd***",
         "fileUrl": "https://iotx-***.aliyuncs.com/***.zip"
      }
        }
    }
}

Le contenu du message est au format JSON. Il correspond à la valeur du paramètre params dans les données Alink.

L'appareil exécute les tâches liées à la tâche principale, puis soumet leurs statuts à IoT Platform. Pour savoir comment mettre à jour les tâches, consultez la section Étape 5 : Mise à jour des statuts des tâches liées à la tâche principale.

Dans cet exemple, la logique d'exécution des tâches n'est pas fournie. Vous devez spécifier la logique de traitement en fonction de vos besoins métier.

void demo_task_recv_handler(void *handle, const aiot_task_recv_t *packet, void *userdata)
{
    switch (packet->type) {
        case AIOT_TASKRECV_NOTIFY: {
            const task_desc_t *in_desc = &(packet->data.notify);

            printf("revice task notify, task_id:[%s],status:[%d],job_document[%s],document_file_url:[%s],\
            sign_method:[%s],sign[%s]\r\n",
                   in_desc->task_id, in_desc->status, in_desc->job_document,
                   in_desc->document_file_url, in_desc->sign_method, in_desc->sign);

            /* 1.If no job records exist in the handle, save the job that is sent by IoT Platform to the default_task_desc field in the handle. */
            if (NULL == g_local_task_desc) {
                demo_copy_task_to_local_task(&g_local_task_desc, in_desc);
                /* Start the job. In this example, the job information is printed. You can specify the logic based on your business needs. */
                int res = pthread_create(&g_task_thread, NULL, demo_task_thread, g_local_task_desc);
                if (res != 0) {
                    printf("pthread_create demo_task_thread failed: %d\r\n", res);
                } else {
                    /* Set the type of the downloading thread to detach. After the firmware is obtained, the downloading thread automatically exits. */
                    pthread_detach(g_task_thread);
                }
                /* Change the job status.TODO: The following code is for reference only. After the job is completed, you must set the status to AIOT_TASK_STATUS_SUCCEEDED. */
                g_local_task_desc->status = AIOT_TASK_STATUS_IN_PROGRESS;
                aiot_task_update(handle, g_local_task_desc);
                demo_free_local_task(&g_local_task_desc);
                break;
            }

            /* 2.If the job status is set to the final status by IoT Platform, the local job is cleared. */
            if (in_desc->status == AIOT_TASK_STATUS_CANCELLED || in_desc->status == AIOT_TASK_STATUS_REMOVED
                || in_desc->status == AIOT_TASK_STATUS_TIMED_OUT) {
                /* TODO: Clear the local job and stop the thread. */
                /* If the job is the default job recorded in the handle, clear the memory of the job. Otherwise, you must maintain the memory of the job. */
                if (NULL != g_local_task_desc && 0 == strcmp(in_desc->task_id, g_local_task_desc->task_id)) {
                    /* Release the memory of the local job. */
                    demo_free_local_task(&g_local_task_desc);
                }
                break;
            }

            /* 3.If a local job already exists, IoT Platform updates the description of the job. You must check the updated description. */
            if (in_desc->status == AIOT_TASK_STATUS_IN_PROGRESS) {
                if (NULL != g_local_task_desc && 0 == strcmp(in_desc->task_id, g_local_task_desc->task_id)) {
                    /* TODO: Update the description of the local job. You can suspend the current job based on your business needs. * /
                    break;
                }
            }

            /* 4.In other cases, the received job is determined as a new job. If a job is running and a new job is received, you can create a list in the main() function. */
            /* Pass in the list as the userdata parameter and record all jobs in this list for maintenance. */
            break;
        }
……
... 
}

Étape 4 : Demande d'une tâche d'appareil

Une fois l'appareil en ligne, vous pouvez demander une tâche d'appareil.

Appelez l'opération aiot_task_get_task_detail pour envoyer une requête à IoT Platform. Si vous définissez le paramètre sur NULL, vous obtiendrez les informations relatives à la première tâche non exécutée.
Remarque
Si IoT Platform pousse plusieurs tâches d'appareil vers l'appareil, vous pouvez appeler l'opération aiot_task_get_task_list pour interroger les tâches d'appareil avant de recevoir les notifications de tâche. Vous pourrez ensuite consulter les informations relatives à chaque tâche d'appareil.
```
    res = aiot_task_get_task_detail(task_handle, NULL);
    if (res < STATE_SUCCESS) {
        aiot_task_deinit(&task_handle);
        demo_mqtt_stop(&mqtt_handle);
        return -1;
    }
                        
```
Après réception de la requête, IoT Platform renvoie à l'appareil les informations relatives à la tâche d'appareil créée.

Lorsque l'appareil reçoit la notification de tâche, le rappel demo_task_recv_handler est appelé.

Lorsque vous définissez la logique du rappel, tenez compte des points suivants :

aiot_task_recv_t est un paramètre d'entrée du rappel. Ce paramètre indique le format des données.
AIOT_TASKRECV_GET_DETAIL_REPLY indique le type de message.

Le tableau suivant présente un exemple de notification et le format de données Alink correspondant.

Exemple

Format de données Alink

Description

{
          "taskId": "i5Ks***F010101",
          "status": "IN_PROGRESS",
          "jobDocument": {
       },
         "jobFile":{
              "signMethod":"Md5",
              "sign":"wssxff56dhdsd***",
              "fileUrl": "https://iotx-***.aliyuncs.com/***.zip"
      }
}

{
  "id": "1234",
  "code": 200,
  "data": {
    "taskId": "$next",
    "task":{
          "taskId": "i5Ks***F010101",
          "status": "IN_PROGRESS",
          "jobDocument": {
       },
         "jobFile":{
              "signMethod":"Md5",
              "sign":"wssxff56dhdsd***",
              "fileUrl": "https://iotx-***.aliyuncs.com/***.zip"
      }
     }
    }
}

Le contenu du message est au format JSON. Il correspond à la valeur du paramètre params dans les données Alink.

L'appareil exécute les tâches liées à la tâche principale, puis soumet leurs statuts à IoT Platform. Pour savoir comment mettre à jour les tâches, consultez la section Étape 5 : Mise à jour des statuts des tâches liées à la tâche principale.

Dans cet exemple, la logique d'exécution des tâches n'est pas fournie. Vous devez spécifier la logique de traitement en fonction de vos besoins métier.

void demo_task_recv_handler(void *handle, const aiot_task_recv_t *packet, void *userdata)
{
    switch (packet->type) {
...
... 
        case AIOT_TASKRECV_GET_DETAIL_REPLY: {
            const task_get_detail_reply_t *in_reply = &(packet->data.get_detail_reply);
            printf("revice task get detail, code:[%d]\r\n", in_reply->code);
            if (200 == in_reply->code) {
                printf("revice task get detail reply, task_id:[%s],status:[%d]\r\n",
                       in_reply->task.task_id, in_reply->task.status);
                if (in_reply->task.status != AIOT_TASK_STATUS_NOT_FOUND) {
                    printf("job_document[%s],document_file_url:[%s], sign_method:[%s],sign[%s]\r\n",
                           in_reply->task.job_document, in_reply->task.document_file_url,
                           in_reply->task.sign_method, in_reply->task.sign);
                    task_desc_t task;
                    memset(&task, 0, sizeof(task));
                    memcpy(&task, &(in_reply->task), sizeof(task));
                    /* TODO: Implement the job by starting a thread. */

                    /* Change the job status. TODO: The following code is for reference only. You can specify the logic based on your business needs. After the task is completed, set the status to AIOT_TASK_STATUS_SUCCEEDED. */
                    task.status = AIOT_TASK_STATUS_IN_PROGRESS;
                    task.progress = 88;
                    aiot_task_update(handle, &task);
                }
            }
            break;
        }
……
... 
}

Étape 5 : Mise à jour des statuts des tâches liées à la tâche principale

Une fois que l'appareil a obtenu les informations de la tâche et exécuté les tâches associées, il doit soumettre les statuts des tâches à IoT Platform.

Appelez l'opération aiot_task_update pour soumettre les statuts des tâches à IoT Platform.
Lors de la soumission des statuts des tâches, tenez compte des points suivants :
- task_desc_t indique le format des données.
- aiot_task_update désigne l'opération d'API.
- L'exemple suivant montre un message au format Alink.
  
  Remarque
  Le contenu du message est au format JSON. Il correspond à la valeur du paramètre params dans les données Alink.
```
{
    "id": "123",
    "version": "1.0",
    "params": {
        "taskId": "i5Ks***F010101",
        "status": "IN_PROGRESS",
        "statusDetails": {
            "key": "value"
        },
        "progress": 50
    }
}
```
  Le contenu du message est au format JSON. Il correspond à la valeur du paramètre params dans les données Alink.
- Dans cet exemple, le statut AIOT_TASK_STATUS_IN_PROGRESS est soumis. Vous devez obtenir les statuts réels des tâches dans vos scénarios métier et les soumettre.
  - Exemple de code pour l'étape 3
```
                g_local_task_desc->status = AIOT_TASK_STATUS_IN_PROGRESS;
                aiot_task_update(handle, g_local_task_desc);
                demo_free_local_task(&g_local_task_desc);
```
  - Exemple de code pour l'étape 4
```
                    task.status = AIOT_TASK_STATUS_IN_PROGRESS;
                    task.progress = 88;
                    aiot_task_update(handle, &task);
```

Une fois les statuts des tâches soumis, IoT Platform renvoie un message de réponse. Dans ce cas, le rappel demo_task_recv_handler est appelé.

Lorsque vous définissez la logique du rappel, tenez compte des points suivants :

aiot_task_recv_t est un paramètre d'entrée du rappel. Ce paramètre indique le format des données.
AIOT_TASKRECV_UPDATE_REPLY indique le type de message.

Dans cet exemple, la logique d'exécution des tâches n'est pas fournie. Vous devez spécifier la logique de traitement en fonction de vos besoins métier.

void demo_task_recv_handler(void *handle, const aiot_task_recv_t *packet, void *userdata)
{
    switch (packet->type) {
...
... 
        case AIOT_TASKRECV_UPDATE_REPLY: {
            const task_update_reply_t *update_reply = &(packet->data.update_reply);
            printf("revice task update reply, code:[%d]\r\n", update_reply->code);

            if (200 == update_reply->code) {
                printf("revice task update reply, task_id:[%s]\r\n", update_reply->task_id);
            }

            if (71012 == update_reply->code) {
                printf("aiot_task_update task's status_details value must be json format\r\n");
            }
            /* TODO */
            break;
        }
……
... 
}

Étape 6 : Quitter le programme

Appelez l'opération aiot_task_deinit() pour détruire l'instance client task et libérer les ressources.

    res = aiot_task_deinit(&task_handle);
    if (res < STATE_SUCCESS) {
        demo_mqtt_stop(&mqtt_handle);
        printf("aiot_task_deinit failed: -0x%04X\n", -res);
        return -1;
    }

Étape 7 : Mettre fin à la connexion

Remarque

MQTT est généralement utilisé pour les appareils nécessitant une connexion persistante. Par conséquent, le programme n'atteint généralement pas cette étape.

Dans l'exemple de programme, le thread principal est chargé de configurer les paramètres et d'établir la connexion. Une fois la connexion établie, le thread principal peut entrer en veille.

Vous pouvez appeler aiot_mqtt_disconnect pour envoyer un message de déconnexion à IoT Platform et vous déconnecter du réseau.

    res = aiot_mqtt_disconnect(mqtt_handle);
    if (res < STATE_SUCCESS) {
        aiot_mqtt_deinit(&mqtt_handle);
        printf("aiot_mqtt_disconnect failed: -0x%04X\n", -res);
        return -1;
    }

Étapes suivantes

Une fois le fichier de code exemple configuré, compilez-le pour générer un fichier exécutable. Dans cet exemple, le fichier exécutable ./output/task_posix_demo est généré.

Pour plus d'informations, consultez la section Compilation et exécution.
Pour plus d'informations sur les résultats d'exécution, consultez la section Journaux d'opération.