Uso da entrega de arquivos AWS IoT baseada em MQTT em dispositivos - AWS IoT Core
Use DescribeStream para obter dados de streamObter blocos de dados de um arquivo de streamTratamento de erros da entrega de arquivos AWS IoT baseada em MQTT

Uso da entrega de arquivos AWS IoT baseada em MQTT em dispositivos

Para iniciar o processo de transferência de dados, um dispositivo deve receber um conjunto de dados inicial, que inclua, no mínimo, um ID de stream. Você pode usar um AWS IoT Jobs para agendar tarefas de transferência de dados para seus dispositivos incluindo o conjunto de dados inicial no documento da tarefa. Quando um dispositivo recebe o conjunto de dados inicial, ele deve iniciar a interação com a entrega de arquivos AWS IoT baseada em MQTT. Para trocar dados com a entrega de arquivos AWS IoT baseada em MQTT, um dispositivo deve:

Opcionalmente, você pode incluir um ID de arquivo de stream e uma versão de stream no conjunto de dados inicial. Enviar um ID de arquivo de stream para um dispositivo pode simplificar a programação do firmware/software do dispositivo, pois elimina a necessidade de fazer uma solicitação do dispositivo DescribeStream para obter esse ID. O dispositivo pode especificar a versão do stream em uma GetStream solicitação para impor uma verificação de consistência caso o stream tenha sido atualizado inesperadamente.

Use DescribeStream para obter dados de stream

A entrega de arquivos AWS IoT baseada em MQTT fornece a API DescribeStream para enviar dados de stream para um dispositivo. Os dados de stream retornados por essa API incluem o ID do stream, a versão do stream, a descrição do stream e uma lista de arquivos do stream, cada um com um ID de arquivo e o tamanho do arquivo em bytes. Com essas informações, um dispositivo pode selecionar arquivos arbitrários para iniciar o processo de transferência de dados.

nota

Você não precisa usar a API DescribeStream se seu dispositivo receber todos os IDs de arquivo de stream necessários no conjunto de dados inicial.

Siga estas etapas para fazer uma solicitação DescribeStream.

  1. Faça a assinatura no filtro de tópicos “aceitos” $aws/things/ThingName/streams/StreamId/description/json.

  2. Faça a assinatura no filtro de tópicos “rejeitados” $aws/things/ThingName/streams/StreamId/rejected/json.

  3. Publique uma DescribeStream solicitação enviando uma mensagem para $aws/things/ThingName/streams/StreamId/describe/json.

  4. Se a solicitação for aceita, seu dispositivo receberá uma DescribeStream resposta no filtro de tópicos “aceitos”.

  5. Se a solicitação for rejeitada, seu dispositivo receberá a resposta de erro no filtro de tópicos “rejeitado”.

nota

Se você json substituir por cbor nos tópicos e filtros de tópicos mostrados, seu dispositivo receberá mensagens no formato CBOR, que é mais compacto que o JSON.

Solicitação DescribeStream

Uma DescribeStream solicitação típica em JSON é semelhante ao exemplo a seguir.

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

  • (Opcional) "c" é o campo do token do cliente.

    O token do cliente não pode ter até 64 bytes. Um token de cliente com mais de 64 bytes causa uma resposta de erro e uma mensagem de erro InvalidRequest.

Resposta do DescribeStream

Uma resposta DescribeStream em JSON se parece com o seguinte exemplo.

{
    "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" é o campo do token do cliente. Isso é retornado se tiver sido fornecido na DescribeStream solicitação. Use o token do cliente para associar a resposta à solicitação.

  • "s" é a versão do stream como um número inteiro. Você pode usar essa versão para realizar uma verificação de consistência com as GetStream solicitações.

  • "r" contém uma lista dos arquivos no stream.

    • "f" é o ID do arquivo de stream como um número inteiro.

    • "z" é o tamanho do arquivo de stream em número de bytes.

  • "d" contém a descrição do stream.

Obter blocos de dados de um arquivo de stream

Você pode usar a API GetStream para que um dispositivo possa receber arquivos de stream em pequenos blocos de dados, para que ela possa ser usada por dispositivos que têm restrições no processamento de blocos grandes. Para receber um arquivo de dados inteiro, um dispositivo pode precisar enviar ou receber várias solicitações e respostas até que todos os blocos de dados sejam recebidos e processados.

Solicitação GetStream

Siga estas etapas para fazer uma solicitação GetStream.

  1. Faça a assinatura no filtro de tópicos “aceitos” $aws/things/ThingName/streams/StreamId/data/json.

  2. Faça a assinatura no filtro de tópicos “rejeitados” $aws/things/ThingName/streams/StreamId/rejected/json.

  3. Publique uma solicitação GetStream para o tópico $aws/things/ThingName/streams/StreamId/get/json.

  4. Se a solicitação for aceita, seu dispositivo receberá uma ou mais respostas GetStream no filtro de tópicos “aceitos”. Cada mensagem de resposta contém informações básicas e uma carga útil de dados para um único bloco.

  5. Repita as etapas 3 e 4 para receber todos os blocos de dados. Você deve repetir essas etapas se a quantidade de dados solicitada for maior que 128 KB. Você deve programar seu dispositivo para usar várias GetStream solicitações para receber todos os dados solicitados.

  6. Se a solicitação for rejeitada, seu dispositivo receberá a resposta de erro no filtro de tópicos “rejeitado”.

nota

  • Se você substituir “json” por “cbor” nos tópicos e filtros de tópicos mostrados, seu dispositivo receberá mensagens no formato CBOR, que é mais compacto que o JSON.

  • A entrega de arquivos AWS IoT baseada em MQTT limita o tamanho de um bloco a 128 KB. Se você fizer uma solicitação para um bloco com mais de 128 KB, a solicitação falhará.

  • Você pode fazer uma solicitação para vários blocos cujo tamanho total seja maior que 128 KB (por exemplo, se você fizer uma solicitação de cinco blocos de 32 KB cada, totalizando 160 KB de dados). Nesse caso, a solicitação não falha, mas seu dispositivo precisa fazer várias solicitações para receber todos os dados solicitados. O serviço enviará blocos adicionais à medida que seu dispositivo fizer solicitações adicionais. Recomendamos que você continue com uma nova solicitação somente após a resposta anterior ter sido recebida e processada corretamente.

  • Independentemente do tamanho total dos dados solicitados, você deve programar seu dispositivo para iniciar novas tentativas quando os blocos não forem recebidos ou não forem recebidos corretamente.

Uma GetStream solicitação típica em JSON é semelhante ao exemplo a seguir.

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

  • [opcional] "c" é o campo do token do cliente.

    O token do cliente pode ter até 64 bytes. Um token de cliente com mais de 64 bytes causa uma resposta de erro e uma mensagem de erro InvalidRequest.

  • [opcional] "s" é o campo da versão do stream (um número inteiro).

    A entrega de arquivos baseada em MQTT aplica uma verificação de consistência com base nessa versão solicitada e na versão mais recente do stream na nuvem. Se a versão do stream enviada de um dispositivo em uma solicitação GetStream não corresponder à versão mais recente do stream na nuvem, o serviço enviará uma resposta de erro e uma mensagem de erro VersionMismatch. Normalmente, um dispositivo recebe a versão esperada (mais recente) do stream no conjunto de dados inicial ou na resposta a DescribeStream.

  • "f" é o ID do arquivo de fluxo (um número inteiro no intervalo de 0 a 255).

    O ID do arquivo de stream é necessário quando você cria ou atualiza um stream usando o AWS CLI ou SDK. Se um dispositivo solicitar um arquivo de stream com uma ID que não existe, o serviço envia uma resposta de erro e uma mensagem de erro ResourceNotFound.

  • "l" é o tamanho do bloco de dados em bytes (um número inteiro no intervalo de 256 a 131.072).

    Consulte Crie um bitmap para uma solicitação GetStream para obter instruções sobre como usar os campos de bitmap para especificar qual parte do arquivo de stream será retornada na resposta GetStream. Se um dispositivo especificar um tamanho de bloco fora do alcance, o serviço enviará uma resposta de erro e uma mensagem de erro BlockSizeOutOfBounds.

  • [opcional] "o" é o deslocamento do bloco no arquivo de stream (um número inteiro no intervalo de 0 a 98.304).

    Consulte Crie um bitmap para uma solicitação GetStream para obter instruções sobre como usar os campos de bitmap para especificar qual parte do arquivo de stream será retornada na resposta GetStream. O valor máximo de 98.304 é baseado em um limite de tamanho de arquivo de stream de 24 MB e 256 bytes para o tamanho mínimo do bloco. Se não especificado, o padrão será 0.

  • [opcional] "n" é o número de blocos solicitados (um número inteiro no intervalo de 0 a 98.304).

    O campo “n” especifica (1) o número de blocos solicitados ou (2) quando o campo bitmap (“b”) é usado, um limite no número de blocos que serão retornados pela solicitação de bitmap. Esse segundo uso é opcional. Se não for definido, o padrão é 131072/DataBlockSize.

  • [opcional] "b" é um bitmap que representa os blocos que estão sendo solicitados.

    Usando um bitmap, seu dispositivo pode solicitar blocos não consecutivos, o que torna mais conveniente lidar com novas tentativas após um erro. Consulte Crie um bitmap para uma solicitação GetStream para obter instruções sobre como usar os campos de bitmap para especificar qual parte do arquivo de fluxo será retornada na resposta GetStream. Para esse campo, converta o bitmap em uma string representando o valor do bitmap em notação hexadecimal. O bitmap deve ser menor do que 12.288 bytes.

Importante

Tanto "n" quanto "b" devem ser especificados. Se nenhum deles for especificado, a solicitação GetStream poderá não ser válida quando o tamanho do arquivo for menor que 131.072 bytes (128 KB).

Resposta GetStream

Uma resposta GetStream em JSON se parece com este exemplo para cada bloco de dados solicitado.

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

  • "c" é o campo do token do cliente. Isso é retornado se tiver sido fornecido na GetStream solicitação. Use o token do cliente para associar a resposta à solicitação.

  • "f" é o ID do arquivo de stream ao qual a carga útil do bloco de dados atual pertence.

  • "l" é o tamanho da carga útil do bloco de dados em bytes.

  • "i" é o ID do bloco de dados contido na carga útil. Os blocos de dados são numerados a partir de 0.

  • "p" contém a carga útil do bloco de dados. Esse campo é uma string, que representa o valor do bloco de dados na codificação Base64.

Crie um bitmap para uma solicitação GetStream

Você pode usar o campo bitmap (b) em uma GetStream solicitação para obter blocos não consecutivos de um arquivo de stream. Isso ajuda dispositivos com capacidade limitada de RAM a lidar com problemas de entrega de rede. Um dispositivo pode solicitar somente os blocos que não foram recebidos ou não foram recebidos corretamente. O bitmap determina quais blocos do arquivo de fluxo serão retornados. Para cada bit, que é definido como 1 no bitmap, um bloco correspondente do arquivo de stream será retornado.

Veja a seguir um exemplo de como especificar um bitmap e seus campos de suporte em uma solicitação GetStream. Por exemplo, você deseja receber um arquivo de stream em partes de 256 bytes (o tamanho do bloco). Pense em cada bloco de 256 bytes como tendo um número que especifica sua posição no arquivo, começando em 0. Portanto, o bloco 0 é o primeiro bloco de 256 bytes no arquivo, o bloco 1 é o segundo e assim por diante. Você deseja solicitar os blocos 20, 21, 24 e 43 do arquivo.

Compensação de blocos

Como o primeiro bloco é o número 20, especifique o deslocamento (campo o) como 20 para economizar espaço no bitmap.

Número de blocos

Para garantir que seu dispositivo não receba mais blocos do que pode suportar com recursos de memória limitados, você pode especificar o número máximo de blocos que devem ser retornados em cada mensagem enviada pela entrega de arquivos baseada em MQTT. Observe que esse valor será ignorado se o próprio bitmap especificar menos do que esse número de blocos ou se isso fizer com que o tamanho total das mensagens de resposta enviadas pela entrega de arquivos com base em MQTT seja maior que o limite de serviço de 128 KB por solicitação GetStream.

Mapa de bits de blocos

O bitmap em si é uma matriz de bytes não assinados expressos em notação hexadecimal e incluídos na solicitação GetStream como uma representação em sequência do número. Mas, para estruturar essa string, vamos começar pensando no bitmap como uma longa sequência de bits (um número binário). Se um bit nessa sequência for definido como 1, o bloco correspondente do arquivo de stream será enviado de volta ao dispositivo. Para nosso exemplo, queremos receber os blocos 20, 21, 24 e 43, então devemos definir os bits 20, 21, 24 e 43 em nosso bitmap. Podemos usar o deslocamento do bloco para economizar espaço, então, depois de subtrairmos o deslocamento de cada número do bloco, queremos definir os bits 0, 1, 4 e 23, como no exemplo a seguir.

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

Com a consideração de um byte (8 bits) por vez, isso é convencionalmente escrito como: "0b00010011", "0b00000000" e "0b10000000". O bit 0 aparece em nossa representação binária no final do primeiro byte e o bit 23 no início do último. Isso pode ser confuso, a menos que você conheça as convenções. O primeiro byte contém os bits 7-0 (nessa ordem), o segundo byte contém os bits 15-8, o terceiro byte contém os bits 23-16 e assim por diante. Em notação hexadecimal, isso é convertido em "0x130080".

dica

Você pode converter o binário padrão em notação hexadecimal. Pegue quatro dígitos binários por vez e converta-os em seu equivalente hexadecimal. Por exemplo, “0001” se torna “1”, “0011” se torna “3” e assim por diante.

Detalhamento de bitmap em bloco para criar uma string na solicitação GetStream.

Juntando tudo isso, o JSON da nossa solicitação GetStream se parece com o seguinte.

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

  • "c" é o campo do token do cliente.

  • "s" é a versão esperada do stream.

  • "l" é o tamanho da carga útil do bloco de dados em bytes.

  • "f" é o ID do índice do arquivo de origem.

  • "o" é o deslocamento do bloco.

  • "n" é o número de blocos.

  • "b" é o bitmap BlockID ausente a partir do deslocamento. Esse valor deve ser codificado em based64.

Tratamento de erros da entrega de arquivos AWS IoT baseada em MQTT

Uma resposta de erro enviada a um dispositivo para ambas as APIs DescribeStream GetStream contém um token de cliente, um código de erro e uma mensagem de erro. Uma resposta de erro típica é semelhante ao exemplo a seguir.

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

  • "o" é o código de erro que indica o motivo de um erro ter ocorrido. Consulte os códigos de erro mais adiante nesta seção para obter mais detalhes.

  • "m" é a mensagem de erro que contém detalhes do erro.

  • "c" é o campo do token do cliente. Isso pode ser devolvido se tiver sido fornecido na solicitação DescribeStream. Você pode usar o token do cliente para associar a resposta à solicitação.

    O campo do token do cliente nem sempre é incluído em uma resposta de erro. Quando o token do cliente fornecido na solicitação não é válido ou está mal formado, ele não é retornado na resposta de erro.

nota

Para compatibilidade com versões anteriores, os campos na resposta de erro podem estar em formato não abreviado. Por exemplo, o código de erro pode ser designado pelos campos “código” ou “o” e o campo do token do cliente pode ser designado pelos campos “clientToken” ou “c”. Recomendamos que você use o formulário de abreviação mostrado acima.

InvalidTopic

O tópico MQTT da mensagem de stream é inválido.

InvalidJson

A solicitação Stream não é um documento JSON válido.

InvalidCbor

A solicitação Stream não é um documento CBOR válido.

InvalidRequest

A solicitação geralmente é identificada como mal formatada. Para ter mais informações, consulte a mensagem de erro.

Não autorizado

A solicitação não está autorizada a acessar os arquivos de dados de stream no meio de armazenamento, como o Amazon S3. Para ter mais informações, consulte a mensagem de erro.

BlockSizeOutOfBounds

O tamanho do bloco está fora dos limites. Consulte a seção “Entrega de arquivos baseada em MQTT” em AWS IoT Core Service Quotas.

OffsetOutOfBounds

O deslocamento está fora dos limites. Consulte a seção “Entrega de arquivos baseada em MQTT” em AWS IoT Core Service Quotas.

BlockCountLimitExceeded

O número de blocos de solicitação está fora dos limites. Consulte a seção “Entrega de arquivos baseada em MQTT” em AWS IoT Core Service Quotas.

BlockBitmapLimitExceeded

O tamanho do bitmap da solicitação está fora dos limites. Consulte a seção “Entrega de arquivos baseada em MQTT” em AWS IoT Core Service Quotas.

ResourceNotFound

O stream, os arquivos, as versões de arquivos ou os blocos solicitados não foram encontrados. Consulte a mensagem de erro para obter mais detalhes.

VersionMismatch

A versão do stream na solicitação não corresponde à versão do stream no atributo de entrega de arquivos baseado em MQTT. Isso indica que os dados do stream foram modificados desde que a versão do stream foi inicialmente recebida pelo dispositivo.

ETagMismatch

A ETag do S3 no stream não corresponde à ETag da versão mais recente do objeto do S3.

InternalError

Ocorreu um erro interno na entrega de arquivos com base em MQTT.