DescribeStream À utiliser pour obtenir des données de flux Obtenir des blocs de données à partir d'un fichier de flux Gestion des erreurs liées à la livraison de AWS IoT fichiers basée sur MQTT

Utilisation de AWS IoT la livraison de fichiers basée sur MQTT sur les appareils

Pour lancer le processus de transfert de données, un appareil doit recevoir un ensemble de données initial comprenant au minimum un identifiant de flux. Vous pouvez utiliser an Tâches pour planifier des tâches de transfert de données pour vos appareils en incluant l'ensemble de données initial dans le document de travail. Lorsqu'un appareil reçoit l'ensemble de données initial, il doit alors commencer à interagir avec la livraison de fichiers AWS IoT basée sur MQTT. Pour échanger des données avec la livraison de fichiers AWS IoT basée sur MQTT, un appareil doit :

Utilisez le protocole MQTT pour vous abonner au Rubriques de livraison de fichiers basées sur MQTT.
Envoyez des demandes, puis attendez de recevoir les réponses à l'aide de messages MQTT.

Vous pouvez éventuellement inclure un ID de fichier de flux et une version de flux dans l'ensemble de données initial. L'envoi d'un identifiant de fichier de flux à un appareil peut simplifier la programmation du microprogramme ou du logiciel de l'appareil, car il n'est plus nécessaire de faire une DescribeStream demande auprès de l'appareil pour obtenir cet identifiant. L'appareil peut spécifier la version du flux dans une GetStream demande afin d'appliquer un contrôle de cohérence au cas où le flux aurait été mis à jour de manière inattendue.

DescribeStream À utiliser pour obtenir des données de flux

AWS IoT La livraison de fichiers basée sur MQTT fournit l'DescribeStreamAPI permettant d'envoyer des données de flux à un appareil. Les données de flux renvoyées par cette API incluent l'ID du flux, la version du flux, la description du flux et une liste de fichiers de flux, chacun ayant un ID de fichier et une taille de fichier en octets. Grâce à ces informations, un appareil peut sélectionner des fichiers arbitraires pour lancer le processus de transfert de données.

Note

Vous n'avez pas besoin d'utiliser l'DescribeStreamAPI si votre appareil reçoit tous les identifiants de fichiers de flux requis dans l'ensemble de données initial.

Suivez ces étapes pour faire une DescribeStream requête.

Abonnez-vous au filtre de sujets « acceptés » $aws/things/ThingName/streams/StreamId/description/json.
Abonnez-vous au filtre de sujets « rejetés » $aws/things/ThingName/streams/StreamId/rejected/json.
Publiez une DescribeStream demande en envoyant un message à $aws/things/ThingName/streams/StreamId/describe/json.
Si la demande a été acceptée, votre appareil reçoit une DescribeStream réponse dans le filtre thématique « accepté ».
Si la demande a été rejetée, votre appareil reçoit une réponse d'erreur dans le filtre de rubrique « rejeté ».

Note

Si vous remplacez json par cbor dans les sujets et les filtres de sujets affichés, votre appareil reçoit les messages au format CBOR, qui est plus compact que le format JSON.

DescribeStream demande

Une DescribeStream demande au format JSON ressemble à l'exemple suivant.


{
    "c": "ec944cfb-1e3c-49ac-97de-9dc4aaad0039"
}

(Facultatif) « c » est le champ du jeton client.

La longueur du jeton client ne peut pas dépasser 64 octets. Un jeton client de plus de 64 octets provoque une réponse d'erreur et un message InvalidRequest d'erreur.

DescribeStream réponse

Une DescribeStream réponse dans JSON se présente comme suit.


{
    "c": "ec944cfb-1e3c-49ac-97de-9dc4aaad0039",
    "s": 1,
    "d": "This is the description of stream ABC.",
    "r": [
        {
            "f": 0,
            "z": 131072
        },
        {
            "f": 1,
            "z": 51200
        }
    ]
}

« c » est le champ du jeton client. Il est renvoyé s'il a été indiqué dans la DescribeStream demande. Utilisez le jeton client pour associer la réponse à sa demande.
« s » est la version du flux sous forme d'entier. Vous pouvez utiliser cette version pour vérifier la cohérence de vos GetStream demandes.
« r » contient la liste des fichiers du flux.
- « f » est l'ID du fichier de flux sous forme d'entier.
- « z » est la taille du fichier de flux en nombre d'octets.
« d » Contient la description du flux.

Obtenir des blocs de données à partir d'un fichier de flux

Vous pouvez utiliser l'GetStreamAPI pour qu'un appareil puisse recevoir des fichiers de flux sous forme de petits blocs de données, afin qu'elle puisse être utilisée par les appareils soumis à des contraintes de traitement de blocs de grande taille. Pour recevoir un fichier de données complet, un appareil peut avoir besoin d'envoyer ou de recevoir plusieurs demandes et réponses jusqu'à ce que tous les blocs de données soient reçus et traités.

GetStream demande

Suivez ces étapes pour faire une GetStream requête.

Abonnez-vous au filtre de sujets « acceptés » $aws/things/ThingName/streams/StreamId/data/json.
Abonnez-vous au filtre de sujets « rejetés » $aws/things/ThingName/streams/StreamId/rejected/json.
Publiez une GetStream demande dans le sujet $aws/things/ThingName/streams/StreamId/get/json.
Si la demande a été acceptée, votre appareil recevra une ou plusieurs GetStream réponses dans le filtre de sujets « accepté ». Chaque message de réponse contient des informations de base et une charge utile de données pour un seul bloc.
Répétez les étapes 3 et 4 pour recevoir tous les blocs de données. Vous devez répéter ces étapes si la quantité de données demandée est supérieure à 128 Ko. Vous devez programmer votre appareil pour qu'il utilise plusieurs GetStream requêtes afin de recevoir toutes les données demandées.
Si la demande a été rejetée, votre appareil recevra une réponse d'erreur dans le filtre de rubrique « rejeté ».

Note

Si vous remplacez « json » par « cbor » dans les rubriques et les filtres de rubriques affichés, votre appareil recevra des messages au format CBOR, qui est plus compact que le format JSON.
AWS IoT La livraison de fichiers basée sur MQTT limite la taille d'un bloc à 128 Ko. Si vous faites une demande pour un bloc de plus de 128 Ko, la demande échouera.
Vous pouvez faire une demande pour plusieurs blocs dont la taille totale est supérieure à 128 Ko (par exemple, si vous faites une demande pour 5 blocs de 32 Ko chacun pour un total de 160 Ko de données). Dans ce cas, la demande n'échoue pas, mais votre appareil doit effectuer plusieurs demandes pour recevoir toutes les données demandées. Le service enverra des blocs supplémentaires au fur et à mesure que votre appareil fera des demandes supplémentaires. Nous vous recommandons de continuer avec une nouvelle demande uniquement une fois que la réponse précédente a été correctement reçue et traitée.
Quelle que soit la taille totale des données demandées, vous devez programmer votre appareil pour qu'il lance de nouvelles tentatives lorsque les blocs ne sont pas reçus ou ne sont pas reçus correctement.

Une GetStream demande au format JSON ressemble à l'exemple suivant.


{
    "c": "1bb8aaa1-5c18-4d21-80c2-0b44fee10380",
    "s": 1,
    "f": 0,
    "l": 4096,
    "o": 2,
    "n": 100,
    "b": "..."
}

[facultatif] « c » est le champ du jeton client.

La longueur du jeton client ne peut pas dépasser 64 octets. Un jeton client de plus de 64 octets provoque une réponse d'erreur et un message InvalidRequest d'erreur.
[facultatif] « s » est le champ de version du flux (un entier).

La livraison de fichiers basée sur MQTT applique un contrôle de cohérence basé sur cette version demandée et sur la dernière version du flux dans le cloud. Si la version du flux envoyée depuis un appareil dans une GetStream demande ne correspond pas à la dernière version du flux dans le cloud, le service envoie une réponse d'erreur et un message VersionMismatch d'erreur. Généralement, un appareil reçoit la version de flux attendue (la plus récente) dans l'ensemble de données initial ou dans la réponse à DescribeStream.
« f » est l'ID du fichier de flux (un entier compris entre 0 et 255).

L'ID du fichier de flux est requis lorsque vous créez ou mettez à jour un flux à l'aide du SDK AWS CLI ou. Si un appareil demande un fichier de flux dont l'identifiant n'existe pas, le service envoie une réponse d'erreur et un message ResourceNotFound d'erreur.
« l » est la taille du bloc de données en octets (un entier compris entre 256 et 131 072).

Reportez-vous à Création d'un bitmap pour une requête GetStream pour obtenir des instructions sur l'utilisation des champs bitmap pour spécifier la partie du fichier de flux qui sera renvoyée dans la GetStream réponse. Si un appareil indique une taille de bloc hors de portée, le service envoie une réponse d'erreur et un message BlockSizeOutOfBounds d'erreur.
[facultatif] « o » est le décalage du bloc dans le fichier de flux (un entier compris entre 0 et 98 304).

Reportez-vous à Création d'un bitmap pour une requête GetStream pour obtenir des instructions sur l'utilisation des champs bitmap pour spécifier la partie du fichier de flux qui sera renvoyée dans la GetStream réponse. La valeur maximale de 98 304 est basée sur une limite de taille de fichier de flux de 24 Mo et sur une taille de bloc minimale de 256 octets. La valeur par défaut est 0 si elle n'est pas spécifiée.
[facultatif] « n » est le nombre de blocs demandés (un entier compris entre 0 et 98 304).

Le champ « n » indique soit (1) le nombre de blocs demandés, soit (2) lorsque le champ bitmap (« b ») est utilisé, une limite du nombre de blocs qui seront renvoyés par la demande bitmap. Cette seconde utilisation est facultative. S'il n'est pas défini, sa valeur par défaut est DataBlockSize131072/.
[facultatif] « b » est un bitmap qui représente les blocs demandés.

À l'aide d'un bitmap, votre appareil peut demander des blocs non consécutifs, ce qui facilite la gestion des nouvelles tentatives suite à une erreur. Reportez-vous à Création d'un bitmap pour une requête GetStream pour obtenir des instructions sur l'utilisation des champs bitmap pour spécifier la partie du fichier de flux qui sera renvoyée dans la GetStream réponse. Pour ce champ, convertissez le bitmap en une chaîne représentant la valeur du bitmap en notation hexadécimale. La bitmap doit être inférieure à 12 288 octets.

Important

Vous devez spécifier « b » ou « ». n Si aucune d'entre elles n'est spécifiée, la GetStream demande risque de ne pas être valide lorsque la taille du fichier est inférieure à 131072 octets (128 Ko).

GetStream réponse

Une GetStream réponse au format JSON ressemble à cet exemple pour chaque bloc de données demandé.


{
    "c": "1bb8aaa1-5c18-4d21-80c2-0b44fee10380",
    "f": 0,
    "l": 4096,
    "i": 2,
    "p": "..."
}

« c » est le champ du jeton client. Il est renvoyé s'il a été indiqué dans la GetStream demande. Utilisez le jeton client pour associer la réponse à sa demande.
« f » est l'ID du fichier de flux auquel appartient la charge utile du bloc de données actuel.
« l » est la taille de la charge utile du bloc de données en octets.
« i » est l'ID du bloc de données contenu dans la charge utile. Les blocs de données sont numérotés à partir de 0.
« p » contient la charge utile du bloc de données. Ce champ est une chaîne qui représente la valeur du bloc de données dans le codage Base64.

Création d'un bitmap pour une requête GetStream

Vous pouvez utiliser le champ bitmap (b) dans une GetStream demande pour obtenir des blocs non consécutifs à partir d'un fichier de flux. Cela permet aux appareils dont la capacité de RAM est limitée de faire face aux problèmes de distribution réseau. Un appareil ne peut demander que les blocs qui n'ont pas été reçus ou qui n'ont pas été reçus correctement. Le bitmap détermine les blocs du fichier de flux qui seront renvoyés. Pour chaque bit défini sur 1 dans le bitmap, un bloc correspondant du fichier de flux sera renvoyé.

Voici un exemple de spécification d'un bitmap et de ses champs d'appui dans une GetStream demande. Par exemple, vous souhaitez recevoir un fichier de flux en blocs de 256 octets (la taille du bloc). Imaginez que chaque bloc de 256 octets possède un numéro qui indique sa position dans le fichier, à partir de 0. Le bloc 0 est donc le premier bloc de 256 octets du fichier, le bloc 1 est le second, et ainsi de suite. Vous souhaitez demander les blocs 20, 21, 24 et 43 depuis le fichier.

Décalage de blocs

Le premier bloc étant le numéro 20, spécifiez le décalage (champo) sur 20 pour économiser de l'espace dans le bitmap.

Nombre total de verrous

Pour vous assurer que votre appareil ne reçoit pas plus de blocs qu'il ne peut en gérer avec des ressources de mémoire limitées, vous pouvez spécifier le nombre maximum de blocs qui doivent être renvoyés dans chaque message envoyé par livraison de fichiers basée sur MQTT. Notez que cette valeur n'est pas prise en compte si le bitmap lui-même indique un nombre inférieur à ce nombre de blocs, ou s'il est possible que la taille totale des messages de réponse envoyés par la distribution de fichiers basée sur MQTT soit supérieure à la limite de service de 128 Ko par GetStream requête.

Bloquer le bitmap

Le bitmap lui-même est un tableau d'octets non signés exprimés en notation hexadécimale et inclus dans la GetStream demande sous forme de chaîne représentant le nombre. Mais pour construire cette chaîne, commençons par considérer le bitmap comme une longue séquence de bits (un nombre binaire). Si un bit de cette séquence est défini sur 1, le bloc correspondant du fichier de flux sera renvoyé à l'appareil. Dans notre exemple, nous voulons recevoir les blocs 20, 21, 24 et 43. Nous devons donc définir les bits 20, 21, 24 et 43 dans notre bitmap. Nous pouvons utiliser le décalage de bloc pour économiser de l'espace. Ainsi, après avoir soustrait le décalage de chaque numéro de bloc, nous voulons définir les bits 0, 1, 4 et 23, comme dans l'exemple suivant.


 1 1 0 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1

Si l'on prend un octet (8 bits) à la fois, cela s'écrit classiquement comme suit : « 0b00010011 », « 0b00000000 » et « 0b10000000 ». Le bit 0 apparaît dans notre représentation binaire à la fin du premier octet, et le bit 23 au début du dernier. Cela peut être source de confusion à moins que vous ne connaissiez les conventions. Le premier octet contient les bits 7-0 (dans cet ordre), le deuxième octet contient les bits 15-8, le troisième octet contient les bits 23-16, etc. En notation hexadécimale, cela se convertit en « 0x130080 ».

Astuce

Vous pouvez convertir le binaire standard en notation hexadécimale. Prenez quatre chiffres binaires à la fois et convertissez-les en leur équivalent hexadécimal. Par exemple, « 0001 » devient « 1 », « 0011 » devient « 3 » et ainsi de suite.

Bloquez la décomposition des bitmaps pour créer une chaîne dans la GetStream requête.

En mettant tout cela ensemble, le JSON de notre GetStream requête ressemble à ce qui suit.


{
    "c" : "1",       
    "s" : 1,         
    "l" : 256,       
    "f" : 1,         
    "o" : 20,        
    "n" : 32,       
    "b" : "130080"
}

« c » est le champ du jeton client.
« s » est la version de diffusion attendue.
« l » est la taille de la charge utile du bloc de données en octets.
« f » est l'ID de l'index du fichier source.
« o » est le décalage du bloc.
« n » est le nombre de blocs.
« b » est le bitmap BlockID manquant à partir du décalage. La valeur doit être codée en base64.

Gestion des erreurs liées à la livraison de AWS IoT fichiers basée sur MQTT

Une réponse d'erreur envoyée à un appareil pour les deux DescribeStream et GetStream API contient un jeton client, un code d'erreur et un message d'erreur. Une réponse d'erreur typique ressemble à l'exemple suivant.


{
    "o": "BlockSizeOutOfBounds", 
    "m": "The block size is out of bounds", 
    "c": "1bb8aaa1-5c18-4d21-80c2-0b44fee10380" 
}

« o » est le code d'erreur qui indique la raison pour laquelle une erreur s'est produite. Reportez-vous aux codes d'erreur plus loin dans cette section pour plus de détails.
« m » est le message d'erreur qui contient les détails de l'erreur.
« c » est le champ du jeton client. Cela peut être retourné s'il a été indiqué dans la DescribeStream demande. Vous pouvez utiliser le jeton client pour associer la réponse à sa demande.

Le champ du jeton client n'est pas toujours inclus dans une réponse d'erreur. Lorsque le jeton client indiqué dans la demande n'est pas valide ou est mal formé, il n'est pas renvoyé dans la réponse d'erreur.

Note

Pour des raisons de rétrocompatibilité, les champs de la réponse d'erreur peuvent être sous une forme non abrégée. Par exemple, le code d'erreur peut être désigné par les champs « code » ou « o » et le champ du jeton client peut être désigné par les champs « ClientToken » ou « c ». Nous vous recommandons d'utiliser la forme d'abréviation présentée ci-dessus.

InvalidTopic: La rubrique MQTT du message de diffusion n'est pas valide.
InvalidJson: La demande Stream n'est pas un document JSON valide.
InvalidCbor: La demande Stream n'est pas un document CBOR valide.
InvalidRequest: La demande est généralement identifiée comme étant mal formée. Pour plus d'informations, voir le message d'erreur.
Non autorisé: La demande n'est pas autorisée à accéder aux fichiers de données de flux sur le support de stockage, tel qu'Amazon S3. Pour plus d'informations, voir le message d'erreur.
BlockSizeOutOfBounds: La taille du bloc est hors limites. Reportez-vous à la section « Livraison de fichiers basée sur MQTT » dans AWS IoT Core Service Quotas.
OffsetOutOfBounds: Le décalage est hors limites. Reportez-vous à la section « Livraison de fichiers basée sur MQTT » dans AWS IoT Core Service Quotas.
BlockCountLimitExceeded: Le nombre de blocs de requêtes est hors limites. Reportez-vous à la section « Livraison de fichiers basée sur MQTT » dans AWS IoT Core Service Quotas.
BlockBitmapLimitExceeded: La taille du bitmap de demande est hors limites. Reportez-vous à la section « Livraison de fichiers basée sur MQTT » dans AWS IoT Core Service Quotas.
ResourceNotFound: Le flux, les fichiers, les versions de fichiers ou les blocs demandés sont introuvables. Reportez-vous au message d'erreur pour plus de détails.
VersionMismatch: La version du flux dans la demande ne correspond pas à la version du flux dans la fonctionnalité de livraison de fichiers basée sur MQTT. Cela indique que les données du flux ont été modifiées depuis que la version du flux a été initialement reçue par l'appareil.
E TagMismatch: L'ETag S3 dans le flux ne correspond pas à l'ETag de la dernière version de l'objet S3.
InternalError: Une erreur interne s'est produite lors de la livraison de fichiers basée sur MQTT.

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

Gestion d'un flux dans le AWS cloud

Exemple de cas d'utilisation dans FreeRTOS OTA