As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
# MQTT
O [MQTT](http://mqtt.org/) (Message Queuing Telemetry Transport) é um protocolo de mensagens leve e amplamente adotado, projetado para dispositivos restritos. O suporte a AWS IoT Core para MQTT é baseado na [especificação MQTT v3.1.1](http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html) e na [especificação MQTT v5.0](http://docs.oasis-open.org/mqtt/mqtt/v5.0/mqtt-v5.0.html), com algumas diferenças, conforme documentado em [AWS IoT diferenças das especificações do MQTT](#mqtt-differences). Como a versão mais recente do padrão, o MQTT 5 apresenta vários recursos principais que tornam um sistema baseado em MQTT mais robusto, incluindo novos aprimoramentos de escalabilidade, relatório de erros aprimorado com respostas de código de motivo, temporizadores de expiração de mensagens e sessões e cabeçalhos de mensagens de usuário personalizados. Para obter mais informações sobre os recursos compatíveis com o MQTT 5, consulte Recursos [compatíveis com o MQTT 5](#mqtt5). AWS IoT Core AWS IoT Core também suporta comunicação entre versões MQTT (MQTT 3 e MQTT 5). Um publicador do MQTT 3 pode enviar uma mensagem do MQTT 3 para um assinante do MQTT 5 que receberá uma mensagem de publicação do MQTT 5 e vice-versa.
AWS IoT Core *suporta conexões de dispositivos que usam o protocolo MQTT e o protocolo MQTT over WSS e que são identificadas por um ID de cliente.* O [AWS IoT Dispositivo SDKs](iot-connect-devices.md#iot-connect-device-sdks) dá suporte a ambos os protocolos e são as formas recomendadas de conectar dispositivos a AWS IoT Core. O AWS IoT dispositivo SDKs suporta as funções necessárias para que dispositivos e clientes se conectem e acessem AWS IoT os serviços. O dispositivo SDKs suporta os protocolos de autenticação exigidos pelos AWS IoT serviços e os requisitos de ID de conexão exigidos pelos protocolos MQTT e MQTT over WSS. Para obter informações sobre como se conectar ao AWS IoT uso do AWS dispositivo SDKs e links para exemplos AWS IoT nos idiomas suportados, consulte[Conectando-se ao MQTT usando o dispositivo AWS IoT SDKs](#mqtt-sdk). Para obter mais informações sobre métodos de autenticação e os mapeamentos de porta para mensagens MQTT, consulte [Protocolos, mapeamentos de porta e autenticação](protocols.md#protocol-mapping).
Embora seja recomendável usar o AWS IoT dispositivo SDKs para se conectar AWS IoT, eles não são obrigatórios. No entanto SDKs, se você não usar o AWS IoT dispositivo, deverá fornecer a segurança necessária de conexão e comunicação. Os clientes devem enviar a [extensão TLS de Server Name Indication (SNI)](https://tools.ietf.org/html/rfc3546#section-3.1) na solicitação de conexão. As tentativas de conexão que não incluem o SNI são recusadas. Para obter mais informações, consulte [Segurança de transporte em AWS IoT](transport-security.html). Clientes que usam usuários e AWS credenciais do IAM para autenticar clientes devem fornecer a autenticação correta do [Signature versão 4](https://docs.aws.amazon.com//general/latest/gr/signature-version-4.html).
Depois que seus clientes estiverem conectados, você poderá monitorar e gerenciar suas conexões de clientes MQTT usando APIs. Para obter mais informações, consulte [Gerenciar conexões do MQTT](#mqtt-client-disconnect).
**Topics**
+ [Conectando-se ao MQTT usando o dispositivo AWS IoT SDKs](#mqtt-sdk)
+ [Opções de Qualidade de serviço (QoS) do MQTT](#mqtt-qos)
+ [Sessões persistentes do MQTT](#mqtt-persistent-sessions)
+ [Mensagens retidas do MQTT](#mqtt-retain)
+ [Mensagens de Último testamento e Testamento (LWT, Last Will and Testament) do MQTT](#mqtt-lwt)
+ [Uso do ConnectAttributes](#connect-attribute)
+ [Recursos compatíveis com o MQTT 5](#mqtt5)
+ [MQTT 5 propriedades](#mqtt5-properties)
+ [Códigos de motivo do MQTT](#mqtt5-reason-codes)
+ [AWS IoT diferenças das especificações do MQTT](#mqtt-differences)
+ [Gerenciar conexões do MQTT](#mqtt-client-disconnect)
## Conectando-se ao MQTT usando o dispositivo AWS IoT SDKs
Esta seção contém links para o AWS IoT dispositivo SDKs e para o código-fonte de programas de amostra que ilustram como conectar um dispositivo a. AWS IoT Os aplicativos de amostra vinculados aqui mostram como se conectar AWS IoT usando o protocolo MQTT e o MQTT pelo WSS.
**nota**
O AWS IoT dispositivo lançou SDKs um cliente MQTT 5.
------
#### [ C\$1\$1 ]
**Usando o SDK de dispositivos AWS IoT C\$1\$1 para conectar dispositivos**
+ [Código-fonte de um aplicativo de amostra que apresenta um exemplo de conexão MQTT em C\$1\$1](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/samples/mqtt/basic_connect/main.cpp)
+ [AWS IoT SDK de dispositivo para C\$1\$1 v2 ativado GitHub](https://github.com/aws/aws-iot-device-sdk-cpp-v2)
------
#### [ Python ]
**Usando o AWS IoT Device SDK para Python para conectar dispositivos**
+ [Código-fonte de um aplicativo de amostra que apresenta um exemplo de conexão MQTT em Python](https://github.com/aws/aws-iot-device-sdk-python-v2/blob/master/samples/pubsub.py)
+ [AWS IoT SDK de dispositivo v2 para Python em GitHub](https://github.com/aws/aws-iot-device-sdk-python-v2)
------
#### [ JavaScript ]
**Usando o AWS IoT Device SDK para JavaScript conectar dispositivos**
+ [Código-fonte de um aplicativo de amostra que mostra um exemplo de conexão MQTT em JavaScript](https://github.com/aws/aws-iot-device-sdk-js-v2/blob/master/samples/node/pub_sub/index.ts)
+ [AWS IoT SDK do dispositivo para JavaScript v2 ativado GitHub](https://github.com/aws/aws-iot-device-sdk-js-v2)
------
#### [ Java ]
**Usando o AWS IoT Device SDK for Java para conectar dispositivos**
**nota**
O AWS IoT Device SDK for Java v2 agora oferece suporte ao desenvolvimento para Android. Para obter mais informações, consulte [SDK de dispositivos AWS IoT para Android](https://github.com/aws/aws-iot-device-sdk-java-v2/blob/main/documents/ANDROID.md).
+ [Código-fonte de um aplicativo de amostra que apresenta um exemplo de conexão MQTT em Java](https://github.com/aws/aws-iot-device-sdk-java-v2/blob/master/samples/BasicPubSub/src/main/java/pubsub/PubSub.java)
+ [AWS IoT SDK de dispositivo para Java v2 ativado GitHub](https://github.com/aws/aws-iot-device-sdk-java-v2)
------
#### [ Embedded C ]
**Usando o AWS IoT Device SDK for Embedded C para conectar dispositivos**
**Importante**
Esse SDK é destinado ao uso por desenvolvedores experientes de software incorporado.
+ [Código-fonte de um aplicativo de amostra que apresenta um exemplo de conexão MQTT em Embedded C](https://github.com/aws/aws-iot-device-sdk-embedded-C/blob/master/demos/mqtt/mqtt_demo_basic_tls/mqtt_demo_basic_tls.c)
+ [AWS IoT SDK de dispositivo para C incorporado em GitHub](https://github.com/aws/aws-iot-device-sdk-embedded-C)
------
## Opções de Qualidade de serviço (QoS) do MQTT
AWS IoT e o AWS IoT dispositivo SDKs suporta os níveis de [Qualidade de Serviço (QoS) `0` do MQTT](http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html#_Toc385349263) e. `1` O protocolo MQTT define um terceiro nível de QoS, `2` nível, AWS IoT mas não o suporta. Apenas o protocolo MQTT dá suporte ao atributo de QoS. HTTPS dá suporte a QoS passando um parâmetro de string de consulta `?qos=qos` em que o valor pode ser 0 ou 1.
Essa tabela descreve como cada nível de QoS afeta as mensagens publicadas para e pelo agente de mensagens.
| Com um nível de QoS de... | A mensagem é… | Comentários |
| --- | --- | --- |
| QoS nível 0 | Enviado zero ou mais vezes | Esse nível deve ser usado para mensagens enviadas por links de comunicação confiáveis ou que podem ser perdidas sem problemas. |
| QoS nível 1 | Enviado pelo menos uma vez e, em seguida, de modo repetido até que uma resposta `PUBACK` seja recebida | A mensagem não é considerada completa até que o remetente receba uma resposta `PUBACK` indicando a entrega bem-sucedida. |
## Sessões persistentes do MQTT
As sessões persistentes armazenam as assinaturas e mensagens de um cliente, com uma Qualidade de Serviço (QoS) de 1, que não foram reconhecidas pelo cliente. Quando o dispositivo se reconecta a uma sessão persistente, a sessão é retomada, as assinaturas são restabelecidas e as mensagens assinadas não confirmadas que são recebidas e armazenadas antes da reconexão são enviadas ao cliente.
O processamento das mensagens armazenadas é registrado em CloudWatch métricas e CloudWatch registros. Para obter informações sobre as entradas gravadas em CloudWatch e CloudWatch Logs, consulte [Métricas do agente de mensagens](metrics_dimensions.md#message-broker-metrics) [Entrada de log em fila](cwl-format.md#log-mb-queued) e.
### Criar uma sessão persistente
No MQTT 3, você cria uma sessão persistente do MQTT enviando uma mensagem `CONNECT` e definindo o sinalizador `cleanSession` como `0`. Se nenhuma sessão existir para o cliente enviar a mensagem `CONNECT`, uma nova sessão persistente será criada. Se já existir uma sessão para o cliente, o cliente retomará a sessão existente. Para criar uma sessão limpa, você envia uma mensagem `CONNECT` e define o sinalizador `cleanSession` como `1`, e o broker não armazenará nenhum estado da sessão quando o cliente se desconectar.
No MQTT 5, você lida com sessões persistentes definindo o sinalizador `Clean Start` e `Session Expiry Interval`. O Clean Start controla o início da sessão de conexão e o final da sessão anterior. Quando você define `Clean Start` =`1`, uma nova sessão é criada e uma sessão anterior é encerrada, se existir. Quando você define `Clean Start` =`0`, a sessão de conexão retoma uma sessão anterior, se ela existir. O intervalo de expiração da sessão controla o final da sessão de conexão. O intervalo de expiração da sessão especifica o tempo, em segundos (número inteiro de 4 bytes), em que uma sessão persistirá após a desconexão. Configuração `Session Expiry interval` = `0` faz com que a sessão seja encerrada imediatamente após a desconexão. Se o intervalo de expiração da sessão não for especificado na mensagem CONNECT, o padrão será 0.
**Início limpo e expiração da sessão do MQTT 5**
| Valor da propriedade | Description |
| --- | --- |
| Clean Start= 1 | Cria uma sessão e encerra uma sessão anterior, se houver. |
| Clean Start= 0 | Retoma uma sessão se existir uma sessão anterior. |
| Session Expiry Interval> 0 | Persistir uma sessão. |
| Session Expiry interval= 0 | Não persistir uma sessão. |
No MQTT 5, se você define `Clean Start` = `1` e `Session Expiry Interval` =`0`, isso equivale a uma sessão limpa do MQTT 3. Se você define `Clean Start` = `0` e `Session Expiry Interval`> `0`, isso equivale a uma sessão persistente do MQTT 3.
**nota**
Não há suporte para as sessões persistentes da versão MQTT cruzada (MQTT 3 e MQTT 5). Uma sessão persistente do MQTT 3 não pode ser retomada como uma sessão do MQTT 5 e vice-versa.
### Operações durante uma sessão persistente
Os clientes usam o atributo `sessionPresent` na mensagem de conexão confirmada (`CONNACK`) para determinar se uma sessão persistente está presente. Se `sessionPresent` for `1`, uma sessão persistente estará presente e todas as mensagens armazenadas para o cliente serão entregues ao cliente após o cliente receber a `CONNACK`, conforme descrito em [Tráfego de mensagens após a reconexão com uma sessão persistente](#persistent-session-reconnect). Se `sessionPresent` for `1`, o cliente não precisará se inscrever novamente. Porém, se `sessionPresent` for `0`, nenhuma sessão persistente estará presente, e o cliente deverá se inscrever novamente nos filtros de tópico.
Depois que o cliente ingressa em uma sessão persistente, ele pode publicar mensagens e assinar filtros de tópico sem quaisquer sinalizadores adicionais em cada operação.
### Tráfego de mensagens após a reconexão com uma sessão persistente
Uma sessão persistente representa uma conexão contínua entre um cliente e um agente de mensagens MQTT. Quando um cliente se conecta ao agente de mensagens usando uma sessão persistente, o agente de mensagens salva todas as inscrições que o cliente faz durante a conexão. Quando o cliente se desconecta, o agente de mensagens armazena mensagens de QoS não confirmadas e novas mensagens de QoS 1 publicadas em tópicos nos quais o cliente está inscrito. As mensagens são armazenadas conforme o limite da conta. As mensagens que excedem o limite serão descartadas. Para obter mais informações sobre os limites de mensagem persistente, consulte [endpoints e cotas do AWS IoT Core](https://docs.aws.amazon.com//general/latest/gr/iot-core.html#message-broker-limits). Quando o cliente se conecta novamente à sua sessão persistente, todas as inscrições são restabelecidas e todas as mensagens armazenadas são enviadas para o cliente com uma taxa máxima de 10 mensagens por segundo. No MQTT 5, se uma QoS 1 de saída com o intervalo de expiração da mensagem expirar quando um cliente estiver offline, depois que a conexão for retomada, o cliente não receberá a mensagem expirada.
Após a reconexão, as mensagens armazenadas são enviadas ao cliente, a uma taxa limitada a 10 mensagens armazenadas por segundo, junto com qualquer tráfego de mensagens atual até que o limite [https://docs.aws.amazon.com//general/latest/gr/iot-core.html#message-broker-limits](https://docs.aws.amazon.com//general/latest/gr/iot-core.html#message-broker-limits) seja atingido. Como a taxa de entrega das mensagens armazenadas é limitada, serão necessários vários segundos para entregar todas as mensagens armazenadas se uma sessão tiver mais de 10 mensagens armazenadas para entregar após a reconexão.
Para assinantes compartilhados, as mensagens serão colocadas na fila se pelo menos um assinante de um grupo usar uma sessão persistente e nenhum assinante estiver on-line para receber a mensagem de QoS 1. A retirada de mensagens da fila é realizado em uma velocidade máxima de vinte mensagens por segundo por assinante ativo em um grupo. Para acessar mais informações, consulte [Enfileiramento de mensagens de assinaturas compartilhadas](https://docs.aws.amazon.com//iot/latest/developerguide/mqtt.html#mqtt5-shared-subscription-queuing).
### Encerrar uma sessão persistente
As sessões persistentes podem terminar das seguintes maneiras:
+ O tempo de expiração persistente da sessão expira. O cronômetro persistente de expiração da sessão começa quando o agente de mensagens detecta que um cliente se desconectou, seja pela desconexão do cliente ou pelo tempo limite da conexão.
+ O cliente envia uma mensagem `CONNECT` que define o sinalizador `cleanSession` como `1`.
+ Você desconecta manualmente o cliente e limpa a sessão usando a API `DeleteConnection`. Para obter mais informações, consulte [Gerenciar conexões do MQTT](#mqtt-client-disconnect).
No MQTT 3, o valor padrão do tempo de expiração das sessões persistentes é de uma hora, e isso se aplica a todas as sessões na conta.
No MQTT 5, você pode definir o intervalo de expiração da sessão para cada sessão nos pacotes CONNECT e DISCONNECT.
Para o intervalo de expiração da sessão no pacote DISCONNECT:
+ Se a sessão atual tiver um intervalo de expiração de sessão de 0, você não poderá definir o intervalo de expiração da sessão como maior que 0 no pacote DISCONNECT.
+ Se a sessão atual tiver um intervalo de expiração de sessão maior que 0 e você definir o intervalo de expiração da sessão como 0 no pacote DISCONNECT, a sessão será encerrada em DISCONNECT.
+ Caso contrário, o intervalo de expiração da sessão no pacote DISCONNECT atualizará o intervalo de expiração da sessão atual.
**nota**
As mensagens armazenadas que aguardam para serem enviadas ao cliente quando a sessão termina são descartadas; porém, elas ainda são cobradas conforme a taxa de mensagens padrão, mesmo que não tenham sido enviadas. Para obter mais informações sobre os preços das mensagens, consulte [Preços do AWS IoT Core](https://aws.amazon.com/iot-core/pricing). Você pode configurar o intervalo de tempo de expiração.
### Reconexão após a expiração de uma sessão persistente
Se um cliente não se reconectar à sessão persistente antes que ela expire, a sessão terminará e as mensagens armazenadas serão descartadas. Quando um cliente se reconecta depois que a sessão expira com um sinalizador `cleanSession` para `0`, o serviço cria uma nova sessão persistente. As assinaturas ou mensagens da sessão anterior não estão disponíveis para esta sessão porque foram descartadas quando a sessão anterior expirou.
### Cobranças persistentes de mensagens de sessão
As mensagens são cobradas de você Conta da AWS quando o agente de mensagens envia uma mensagem para um cliente ou para uma sessão persistente offline. Quando um dispositivo offline com uma sessão persistente se reconecta e retoma a sessão, as mensagens armazenadas são entregues ao dispositivo e cobradas novamente em sua conta. Para obter mais informações sobre a definição de preço de mensagem, consulte [Preços do AWS IoT Core – Mensagens](https://aws.amazon.com/iot-core/pricing/#Messaging).
O tempo de expiração padrão da sessão persistente de uma hora pode ser aumentado usando o processo padrão de aumento de limite. Observe que aumentar o tempo de expiração da sessão pode aumentar suas cobranças de mensagens, pois o tempo adicional pode permitir que mais mensagens sejam armazenadas no dispositivo off-line e essas mensagens adicionais seriam cobradas em sua conta conforme a taxa de mensagens padrão. O tempo de expiração da sessão é aproximado e uma sessão pode persistir por até 30 minutos a mais do que o limite da conta; porém, uma sessão não será menor que o limite da conta. Para obter mais informações sobre limites de sessão, consulte [AWS Service Quotas](https://docs.aws.amazon.com//general/latest/gr/iot-core.html#message-broker-limits).
## Mensagens retidas do MQTT
AWS IoT Core suporta a `RETAIN` bandeira descrita no protocolo MQTT. Quando um cliente define o `RETAIN` sinalizador em uma mensagem MQTT que ele publica, AWS IoT Core salva a mensagem. Em seguida, ele pode ser enviado para novos assinantes, recuperado chamando a operação [https://docs.aws.amazon.com//iot/latest/apireference/API_iotdata_GetRetainedMessage.html](https://docs.aws.amazon.com//iot/latest/apireference/API_iotdata_GetRetainedMessage.html) e visualizado no [console do AWS IoT](https://console.aws.amazon.com//iot/home#/retainedMessages).
**Exemplos de uso de mensagens retidas do MQTT**
+
**Como uma mensagem de configuração inicial**
As mensagens retidas do MQTT são enviadas a um cliente depois que o cliente se inscreve em um tópico. Se você quiser que todos os clientes que assinam um tópico recebam a mensagem retida do MQTT logo após a assinatura, publique uma mensagem de configuração com o sinalizador `RETAIN` definido. Os clientes assinantes também recebem atualizações dessa configuração sempre que uma nova mensagem de configuração é publicada.
+
**Como uma última mensagem de estado conhecida**
Os dispositivos podem definir o sinalizador `RETAIN` nas mensagens do estado atual para que o AWS IoT Core as salve. Quando os aplicativos se conectam ou se reconectam, eles podem se inscrever nesse tópico e obter o último estado relatado logo após se inscreverem no tópico da mensagem retida. Dessa forma, eles podem evitar ter que esperar até a próxima mensagem do dispositivo para ver o estado atual.
**Topics**
+ [Tarefas comuns com mensagens retidas pelo MQTT em AWS IoT Core](#mqtt-retain-using)
+ [Faturamento e mensagens retidas](#mqtt-retain-billing)
+ [Comparar mensagens retidas do MQTT e sessões persistentes do MQTT](#mqtt-retain-persist)
+ [O MQTT reteve mensagens e AWS IoT sombras do dispositivo](#mqtt-retain-shadow)
### Tarefas comuns com mensagens retidas pelo MQTT em AWS IoT Core
AWS IoT Core salva mensagens MQTT com o `RETAIN` sinalizador definido. Essas *mensagens retidas* são enviadas a todos os clientes que se inscreveram no tópico, como uma mensagem MQTT normal, e também são armazenadas para serem enviadas aos novos assinantes do tópico.
As mensagens retidas pelo MQTT exigem ações políticas específicas para autorizar os clientes a acessá-las. Para obter exemplos de uso de políticas de mensagens retidas, consulte [Exemplos de políticas de mensagens retidas](retained-message-policy-examples.md).
Esta seção descreve operações comuns que envolvem mensagens retidas.
+
**Criar uma mensagem retida**
O cliente determina se uma mensagem é retida quando publica uma mensagem MQTT. Os clientes podem definir o sinalizador `RETAIN` ao publicar uma mensagem usando um [SDK de dispositivo](iot-sdks.md). Aplicações e serviços podem definir o sinalizador `RETAIN` quando usam a [ação `Publish`](https://docs.aws.amazon.com//iot/latest/apireference/API_iotdata_Publish.html) para publicar uma mensagem do MQTT.
Apenas uma mensagem por nome de tópico é retida. Uma nova mensagem com o sinalizador RETAIN definido publicada em um tópico substitui qualquer mensagem retida que tenha sido enviada ao tópico antes.
**nota**
Você não pode publicar em um [tópico reservado](reserved-topics.md) com o sinalizador `RETAIN` definido.
+
**Assinar um tópico de mensagem retida**
Os clientes assinam os tópicos de mensagens retidos como fariam com qualquer outro tópico de mensagem do MQTT. As mensagens retidas recebidas ao assinar um tópico desse tipo têm o sinalizador `RETAIN` definido.
As mensagens retidas são excluídas AWS IoT Core quando um cliente publica uma mensagem retida com uma carga útil de mensagem de 0 bytes no tópico da mensagem retida. Os clientes que se inscreveram no tópico da mensagem retida também receberão a mensagem de 0 byte.
Inscrever-se em um filtro de tópico curinga que inclui um tópico de mensagem retida permite que o cliente receba mensagens subsequentes publicadas no tópico da mensagem retida, mas não entrega a mensagem retida após a assinatura.
**nota**
Para receber uma mensagem retida após a assinatura, o filtro de tópicos na solicitação de assinatura deve corresponder exatamente ao tópico da mensagem retida.
As mensagens retidas recebidas ao assinar um tópico desse tipo têm o sinalizador `RETAIN` definido. As mensagens retidas que são recebidas por um cliente assinante após a assinatura não têm.
+
**Recuperar uma mensagem retida**
As mensagens retidas são entregues de modo automático aos clientes quando eles se inscrevem no tópico com a mensagem retida. Para que um cliente receba a mensagem retida após a assinatura, ele deve assinar o nome exato do tópico da mensagem retida. Inscrever-se em um filtro de tópico curinga que inclui um tópico de mensagem retida permite que o cliente receba mensagens subsequentes publicadas no tópico da mensagem retida, mas não entrega a mensagem retida após a assinatura.
Serviços e aplicativos podem listar e recuperar mensagens retidas chamando [https://docs.aws.amazon.com//iot/latest/apireference/API_iotdata_ListRetainedMessages.html](https://docs.aws.amazon.com//iot/latest/apireference/API_iotdata_ListRetainedMessages.html) e [https://docs.aws.amazon.com//iot/latest/apireference/API_iotdata_GetRetainedMessage.html](https://docs.aws.amazon.com//iot/latest/apireference/API_iotdata_GetRetainedMessage.html).
Um cliente não é impedido de publicar mensagens em um tópico de mensagem retida *sem* definir o sinalizador `RETAIN`. Isso pode causar resultados inesperados, como a mensagem retida não corresponder à mensagem recebida ao se inscrever no tópico.
Com o MQTT 5, se uma mensagem retida tiver o intervalo de expiração da mensagem definido e a mensagem retida expirar, um novo assinante que assine esse tópico não receberá a mensagem retida após a assinatura bem-sucedida.
+
**Listando tópicos de mensagens retidas**
[Você pode listar as mensagens retidas chamando [https://docs.aws.amazon.com//iot/latest/apireference/API_iotdata_ListRetainedMessages.html](https://docs.aws.amazon.com//iot/latest/apireference/API_iotdata_ListRetainedMessages.html) e as mensagens retidas podem ser visualizadas no console do AWS IoT](https://console.aws.amazon.com//iot/home#/retainedMessages).
+
**Obter detalhes da mensagem retida**
Você pode obter detalhes das mensagens retidas chamando [https://docs.aws.amazon.com//iot/latest/apireference/API_iotdata_GetRetainedMessage.html](https://docs.aws.amazon.com//iot/latest/apireference/API_iotdata_GetRetainedMessage.html) e elas podem ser visualizadas no [console do AWS IoT](https://console.aws.amazon.com//iot/home#/retainedMessages).
+
**Reter de uma mensagem de Testamento**
As mensagens do MQTT de [http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/errata01/os/mqtt-v3.1.1-errata01-os-complete.html#_Will_Flag](http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/errata01/os/mqtt-v3.1.1-errata01-os-complete.html#_Will_Flag) criadas quando um dispositivo se conecta podem ser retidas definindo o sinalizador `Will Retain` no campo `Connect Flag bits`.
+
**Excluir uma mensagem retida**
Dispositivos, aplicações e serviços podem excluir uma mensagem retida publicando uma mensagem com o sinalizador `RETAIN` definido e uma carga útil vazia (0 byte) no nome do tópico da mensagem retida a ser excluída. Essas mensagens excluem a mensagem retida de AWS IoT Core, são enviadas aos clientes com uma assinatura do tópico, mas não são retidas por. AWS IoT Core
As mensagens retidas também podem ser excluídas interativamente acessando a mensagem retida no [console do AWS IoT](https://console.aws.amazon.com//iot/home#/retainedMessages). As mensagens retidas excluídas usando o [console do AWS IoT](https://console.aws.amazon.com//iot/home#/retainedMessages) também enviam uma mensagem de 0 byte aos clientes que se inscreveram no tópico da mensagem retida.
As mensagens retidas não podem ser restauradas após serem excluídas. Um cliente precisaria publicar uma nova mensagem retida para substituir a mensagem excluída.
+
**Depuração e solução de problemas de mensagens retidas**
O [console do AWS IoT](https://console.aws.amazon.com//iot/home#) fornece várias ferramentas para ajudá-lo a solucionar problemas de mensagens retidas:
+
**A página **[Mensagens retidas](https://console.aws.amazon.com//iot/home#/retainedMessages)****
A página **Mensagens retidas** no console do AWS IoT fornece uma lista paginada das mensagens retidas armazenadas pela sua Conta na região atual. Nesta página, você pode:
+ Veja os detalhes de cada mensagem retida, como a carga útil da mensagem, o QoS e a hora em que ela foi recebida.
+ Atualize o conteúdo de uma mensagem retida.
+ Exclua uma mensagem retida.
+
**O **[cliente de teste MQTT](https://console.aws.amazon.com//iot/home#/test)****
A página do **cliente de teste do MQTT** no console do AWS IoT pode se inscrever e publicar nos tópicos do MQTT. A opção de publicação permite que você defina o sinalizador RETAIN nas mensagens que você publica para simular como seus dispositivos podem se comportar. Também é possível usar o cliente de teste do MQTT para monitorar mensagens de clientes conectados gerenciados pela interface de conexões de clientes. Para acessar mais informações sobre o gerenciamento de configurações de clientes, consulte [Gerenciar conexões do MQTT](#mqtt-client-disconnect).
Alguns resultados inesperados podem ser o resultado desses aspectos de como as mensagens retidas são implementadas em AWS IoT Core.
+
**Limites de mensagens retidas**
Quando uma conta armazena o número máximo de mensagens retidas, AWS IoT Core retorna uma resposta limitada às mensagens publicadas com RETAIN definido e cargas superiores a 0 bytes até que algumas mensagens retidas sejam excluídas e a contagem de mensagens retidas fique abaixo do limite.
+
**Ordem de entrega de mensagens retidas**
A sequência da mensagem retida e da entrega da mensagem assinada não é garantida.
### Faturamento e mensagens retidas
A publicação de mensagens com o sinalizador `RETAIN` definido por um cliente, usando o console da AWS IoT ou chamando [https://docs.aws.amazon.com//iot/latest/apireference/API_iotdata_Publish.html](https://docs.aws.amazon.com//iot/latest/apireference/API_iotdata_Publish.html) gera cobranças adicionais de mensagens descritas em [Preços do AWS IoT Core : mensagens](https://aws.amazon.com//iot-core/pricing/#Messaging).
A recuperação de mensagens retidas por um cliente, usando o AWS IoT console ou ligando [https://docs.aws.amazon.com//iot/latest/apireference/API_iotdata_GetRetainedMessage.html](https://docs.aws.amazon.com//iot/latest/apireference/API_iotdata_GetRetainedMessage.html)gera cobranças de mensagens, além das cobranças normais de uso da API. As cobranças adicionais estão descritas em [AWS IoT Core Preços – Mensagens](https://aws.amazon.com//iot-core/pricing/#Messaging).
As mensagens de [http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/errata01/os/mqtt-v3.1.1-errata01-os-complete.html#_Will_Flag](http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/errata01/os/mqtt-v3.1.1-errata01-os-complete.html#_Will_Flag) do MQTT publicadas quando um dispositivo se desconecta inesperadamente geram cobranças de mensagens descritas em [AWS IoT Core Preços - Mensagens](https://aws.amazon.com//iot-core/pricing/#Messaging).
Para obter mais informações sobre custos de mensagens, consulte [Preços do AWS IoT Core – Mensagens](https://aws.amazon.com//iot-core/pricing/#Messaging).
### Comparar mensagens retidas do MQTT e sessões persistentes do MQTT
Mensagens retidas e sessões persistentes são recursos padrão do MQTT que possibilitam que os dispositivos recebam mensagens publicadas enquanto eles estavam off-line. As mensagens retidas podem ser publicadas de sessões persistentes. Esta seção descreve os principais aspectos desses recursos e como eles funcionam juntos.
| | Mensagens retidas | Sessões persistentes |
| --- | --- | --- |
| **Recursos principais** | As mensagens retidas podem ser usadas para configurar ou notificar grandes grupos de dispositivos após a conexão. As mensagens retidas também podem ser usadas quando você deseja que os dispositivos recebam apenas a última mensagem publicada em um tópico após uma reconexão. | As sessões persistentes são úteis para dispositivos que têm conectividade intermitente e podem perder várias mensagens importantes. Os dispositivos podem se conectar a uma sessão persistente para receber mensagens enviadas enquanto estão off-line. |
| **Exemplos** | As mensagens retidas podem fornecer aos dispositivos informações de configuração sobre seu ambiente quando eles ficam on-line. A configuração inicial pode incluir uma lista de outros tópicos de mensagens nos quais ele deve se inscrever ou informações sobre como ele deve configurar seu fuso horário local. | Dispositivos que se conectam por uma rede celular com conectividade intermitente podem usar sessões persistentes para evitar a perda de mensagens importantes enviadas enquanto um dispositivo está fora da cobertura da rede ou precisa desligar o rádio do celular. |
| **Mensagens recebidas na assinatura inicial de um tópico** | Depois de assinar um tópico com uma mensagem retida, a mensagem retida mais recente é recebida. | Depois de assinar um tópico sem uma mensagem retida, nenhuma mensagem é recebida até que uma seja publicada no tópico. |
| **Tópicos assinados após a reconexão** | Sem uma sessão persistente, o cliente deve se inscrever nos tópicos após a reconexão. | Os tópicos inscritos são restaurados após a reconexão. |
| **Mensagens recebidas após a reconexão** | Depois de assinar um tópico com uma mensagem retida, a mensagem retida mais recente é recebida. | Todas as mensagens publicadas com uma QOS = 1 e assinadas com uma QOS =1 enquanto o dispositivo estava desconectado são enviadas após a reconexão do dispositivo. |
| **Data/expiração da sessão** | No MQTT 3, as mensagens retidas não expiram. Elas são armazenados até serem substituídas ou excluídas. No MQTT 5, as mensagens retidas expiram após o intervalo de expiração da mensagem que você definiu. Para obter mais informações, consulte [Expiração da mensagem](#mqtt5). | As sessões persistentes expiram se o cliente não se reconectar dentro do tempo limite. Depois que uma sessão persistente expira, as assinaturas e mensagens salvas do cliente publicadas com uma QOS = 1 e assinadas com uma QOS = 1 enquanto o dispositivo estava desconectado são excluídas. As mensagens expiradas não serão entregues. Para obter mais informações sobre expirações de sessões persistentes, consulte [Sessões persistentes do MQTT](#mqtt-persistent-sessions). |
Para obter mais informações sobre sessões persistentes, consulte [Sessões persistentes do MQTT](#mqtt-persistent-sessions).
Com as mensagens retidas, o cliente de publicação determina se uma mensagem deve ser retida e entregue a um dispositivo após a conexão, independentemente de ter tido uma sessão anterior ou não. A escolha de armazenar uma mensagem é feita pelo publicador e a mensagem armazenada é entregue a todos os clientes atuais e futuros que usam assinaturas de QoS 0 ou QoS 1. As mensagens retidas mantêm apenas uma mensagem sobre um determinado tópico por vez.
Quando uma conta armazena o número máximo de mensagens retidas, AWS IoT Core retorna uma resposta limitada às mensagens publicadas com RETAIN definido e cargas superiores a 0 bytes até que algumas mensagens retidas sejam excluídas e a contagem de mensagens retidas fique abaixo do limite.
### O MQTT reteve mensagens e AWS IoT sombras do dispositivo
Tanto as mensagens retidas quanto as sombras do dispositivo retêm dados de um dispositivo, mas se comportam de maneira diferente e servem a propósitos diferentes. Esta seção descreve suas semelhanças e diferenças.
| | Mensagens retidas | Device Shadows |
| --- | --- | --- |
| **A carga útil da mensagem tem uma estrutura ou esquema predefinido** | Conforme definido pela implementação. O MQTT não especifica uma estrutura ou esquema para sua carga de mensagens. | AWS IoT suporta uma estrutura de dados específica. |
| **A atualização da carga útil da mensagem gera mensagens de eventos** | A publicação de uma mensagem retida envia a mensagem aos clientes inscritos, mas não gera mensagens de atualização adicionais. | A atualização de uma Sombra do dispositivo produz [mensagens de atualização que descrevem a alteração](https://docs.aws.amazon.com//iot/latest/developerguide/device-shadow-mqtt.html#update-delta-pub-sub-topic). |
| **As atualizações de mensagens são numeradas** | As mensagens retidas não são numeradas automaticamente. | Os documentos de Sombra do dispositivo têm números de versão e carimbos de data e hora automáticos. |
| **A carga útil da mensagem é anexada a um recurso** | As mensagens retidas não são anexadas a um recurso. | Sombras do dispositivo são anexadas a um recurso de objeto. |
| **Atualização de elementos individuais da carga útil da mensagem** | Elementos individuais da mensagem não podem ser alterados sem atualizar toda a carga útil da mensagem. | Elementos individuais de um documento de Sombra do dispositivo podem ser atualizados sem a necessidade de atualizar todo o documento de Sombra do dispositivo. |
| **O cliente recebe dados da mensagem no momento da assinatura** | O cliente recebe automaticamente uma mensagem retida depois de assinar um tópico com uma mensagem retida. | Os clientes podem assinar as atualizações de Sombra do dispositivo, mas devem solicitar o estado atual deliberadamente. |
| **Indexação e capacidade de pesquisa** | As mensagens retidas não são indexadas para pesquisa. | A indexação de frotas indexa dados de Sombra do dispositivo para pesquisa e agregação. |
## Mensagens de Último testamento e Testamento (LWT, Last Will and Testament) do MQTT
Último testamento e Testamento (LWT, Last Will and Testament) é um atributo do MQTT. Com o LWT, os clientes podem especificar uma mensagem que o corretor publicará em um tópico definido pelo cliente e enviará a todos os clientes que se inscreveram no tópico quando ocorrer uma desconexão não iniciada. A mensagem que os clientes especificam é chamada de mensagem LWT ou Mensagem de testamento, e o tópico que os clientes definem é chamado de Tópico de testamento. Você pode especificar uma mensagem LWT quando um dispositivo se conecta ao agente. Essas mensagens podem ser retidas definindo o sinalizador `Will Retain` no campo `Connect Flag bits` durante a conexão. Por exemplo, se o sinalizador `Will Retain` estiver definido como `1`, uma mensagem de testamento será armazenada no corretor no tópico de testamento associado. Para obter mais informações, consulte [Mensagens de Will](https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc479576982).
Ao gerenciar conexões de clientes, você pode controlar se as mensagens LWT são publicadas quando você desconecta um cliente. Para obter mais informações, consulte [Gerenciar conexões do MQTT](#mqtt-client-disconnect).
O corretor armazenará as mensagens de testamento até que ocorra uma desconexão não iniciada. Quando isso acontecer, o corretor publicará as mensagens para todos os clientes que se inscreveram no Tópico de testamento para notificar a desconexão. Se o cliente se desconectar do agente com uma desconexão iniciada pelo cliente usando a mensagem MQTT DISCONNECT, o broker não publicará as mensagens LWT armazenadas. Em todos os outros casos, as mensagens LWT serão enviadas. Devido à natureza assíncrona do processamento de desconexão, não é garantido que as mensagens LWT sejam enviadas em ordem durante a reconexão. Recomendamos que você use [eventos de ciclo](life-cycle-events.md) de vida para melhorar a precisão da detecção do estado de conectividade, pois esses eventos fornecem atributos como registros de data e hora e números de versão para gerenciar eventos. out-of-order Para obter uma lista completa dos cenários de desconexão em que o agente enviará as mensagens LWT, confira [Eventos de conexão/desconexão](https://docs.aws.amazon.com//iot/latest/developerguide/life-cycle-events.html#connect-disconnect).
## Uso do ConnectAttributes
O `ConnectAttributes` permite que você especifique quais atributos deseja usar na mensagem de conexão em suas políticas do IAM, como `PersistentConnect` e `LastWill`. Com o `ConnectAttributes`, você pode criar políticas que não dão aos dispositivos acesso a novos recursos por padrão, o que pode ser útil se um dispositivo for comprometido.
O `connectAttributes` oferece suporte aos seguintes recursos:
`PersistentConnect`
Use o atributo `PersistentConnect` para salvar todas as assinaturas que o cliente faz durante a conexão quando a conexão entre o cliente e o corretor é interrompida.
`LastWill`
Use o atributo `LastWill` para publicar uma mensagem no `LastWillTopic` quando um cliente se desconectar inesperadamente.
Por padrão, Sua política tem uma conexão não persistente e não há atributos passados para essa conexão. Você deve especificar uma conexão persistente em sua política do IAM se quiser ter uma.
Ao gerenciar conexões de clientes, você pode visualizar os atributos de conexão e a configuração da sessão para clientes conectados. Para obter mais informações, consulte [Gerenciar conexões do MQTT](#mqtt-client-disconnect).
Para exemplos de `ConnectAttributes`, consulte [Exemplos da política de conexão](connect-policy.md).
## Recursos compatíveis com o MQTT 5
AWS IoT Core o suporte para o MQTT 5 é baseado na [especificação MQTT v5.0](http://docs.oasis-open.org/mqtt/mqtt/v5.0/mqtt-v5.0.html), com algumas diferenças, conforme documentado em. [AWS IoT diferenças das especificações do MQTT](#mqtt-differences)
**Topics**
+ [Assinaturas compartilhadas](#mqtt5-shared-subscription)
+ [Início limpo e expiração da sessão](#mqtt5-clean-start)
+ [Código de motivo em todos ACKs](#mqtt5-reason-code)
+ [Aliases de tópicos](#mqtt5-topic-alias)
+ [Validade da mensagem](#mqtt5-message-expiry)
+ [Outros recursos do MQTT 5](#mqtt5-other-features)
### Assinaturas compartilhadas
AWS IoT Core suporta assinaturas compartilhadas para o MQTT 3.1.1 e o MQTT 5. As assinaturas compartilhadas permitem que vários clientes compartilhem uma assinatura de um tópico e somente um cliente receberá mensagens publicadas nesse tópico usando uma distribuição randomizada. As assinaturas compartilhadas podem efetivamente balancear a carga das mensagens do MQTT entre vários assinantes. Por exemplo, digamos que você tenha 1.000 dispositivos publicando no mesmo tópico e 10 aplicativos de backend processando essas mensagens. Nesse caso, as aplicações de backend podem assinar o mesmo tópico e cada um receberá mensagens publicadas aleatoriamente pelos dispositivos no tópico compartilhado. Isso é efetivamente “compartilhar” a carga dessas mensagens. As assinaturas compartilhadas também permitem uma melhor resiliência. Quando qualquer aplicativo de backend é desconectado, o agente distribui a carga para os assinantes restantes no grupo. Quando todos os assinantes se desconectam, as mensagens ficam na fila.
Os recursos de enfileiramento de mensagens estão disponíveis para assinaturas compartilhadas nas conexões MQTT 3.1.1 e MQTT 5 para melhorar a confiabilidade da entrega de mensagens.
Para usar assinaturas compartilhadas, os clientes assinam um [filtro de tópicos](https://docs.aws.amazon.com//iot/latest/developerguide/topics.html#topicfilters) de uma assinatura compartilhada da seguinte maneira:
```
$share/{ShareName}/{TopicFilter}
```
+ `$share` é uma string literal para indicar o filtro de tópicos de uma Assinatura Compartilhada, que deve começar com `$share`.
+ `{ShareName}` é uma cadeia de caracteres para especificar o nome compartilhado usado por um grupo de assinantes. O filtro de tópicos de uma assinatura compartilhada deve conter um `ShareName` e ser seguido pelo caractere `/`. O `{ShareName}` não deve incluir os seguintes caracteres:`/`, `+` ou `#`. O tamanho máximo de `{ShareName}` é de 128 caracteres UTF-8.
+ O `{TopicFilter}` segue a mesma sintaxe que o [filtro de tópicos](https://docs.aws.amazon.com//iot/latest/developerguide/topics.html#topicfilters) de uma assinatura não compartilhada. O tamanho máximo de `{TopicFilter}` é de 256 caracteres UTF-8.
+ As duas barras obrigatórias (`/`) para `$share/{ShareName}/{TopicFilter}` não estão incluídas no limite de [Número máximo de barras no tópico e filtro de tópicos](https://console.aws.amazon.com/servicequotas/home/services/iotcore/quotas/L-AD5A8D4F).
As assinaturas que têm o mesmo `{ShareName}/{TopicFilter}` pertencem ao mesmo grupo de assinaturas compartilhadas. Você pode criar vários grupos de assinaturas compartilhadas e não exceder o [limite de assinaturas compartilhadas por grupo](https://docs.aws.amazon.com//general/latest/gr/iot-core.html#message-broker-limits). Para obter mais informações, consulte [Endpoints e cotas do AWS IoT Core](https://docs.aws.amazon.com//general/latest/gr/iot-core.html) na *Referência geral da AWS *.
As tabelas a seguir comparam assinaturas não compartilhadas e as assinaturas compartilhadas:
****
| Assinatura | Description | Exemplos de filtro do tópico |
| --- | --- | --- |
| Assinaturas não compartilhadas | Cada cliente cria uma assinatura separada para receber as mensagens publicadas. Quando uma mensagem é publicada em um tópico, todos os assinantes desse tópico recebem uma cópia da mensagem. | sports/tennis
sports/#
|
| Assinaturas compartilhadas | Vários clientes podem compartilhar uma assinatura de um tópico e somente um cliente receberá mensagens publicadas nesse tópico em uma distribuição aleatória. | $share/consumer/sports/tennis
$share/consumer/sports/#
|
****
| Fluxo de assinaturas não compartilhadas | Fluxo de assinaturas compartilhadas |
| --- | --- |
| ![\[Assinaturas regulares para MQTT 3 e MQTT 5 in. AWS IoT Core\]](http://docs.aws.amazon.com/pt_br/iot/latest/developerguide/images/mqtt_regular_subscription.gif) | ![\[Assinaturas compartilhadas para MQTT 3 e MQTT 5 em. AWS IoT Core\]](http://docs.aws.amazon.com/pt_br/iot/latest/developerguide/images/mqtt_shared_subscription.gif) |
**Observações importantes sobre o uso de assinaturas compartilhadas**
+ Se o grupo de assinantes compartilhado consistir em qualquer assinante de sessão persistente, quando todos os assinantes do grupo compartilhado estiverem desconectados ou se algum assinante violar o limite de solicitações de publicação por segundo por conexão, todas as mensagens de QoS 1 não confirmadas e mensagens de QoS 1 não entregues publicadas em um grupo de assinatura compartilhado serão colocadas em fila. Para acessar mais informações, consulte [Enfileiramento de mensagens de assinaturas compartilhadas](#mqtt5-shared-subscription-message-queuing).
+ As mensagens de QoS 0 publicadas em um grupo de assinatura compartilhado serão descartadas em caso de falha.
+ As assinaturas compartilhadas não recebem [mensagens retidas](https://docs.aws.amazon.com//iot/latest/developerguide/mqtt.html#mqtt-retain) ao assinar padrões de tópicos como parte de um grupo compartilhado de assinantes. As mensagens publicadas em tópicos com assinantes compartilhados e com o sinalizador `RETAIN` definido são entregues aos assinantes compartilhados como qualquer outra mensagem publicada.
+ Quando as assinaturas compartilhadas contêm caracteres curinga (\$1 ou \$1), pode haver várias assinaturas compartilhadas correspondentes a um tópico. Se isso acontecer, o agente de mensagens copiará a mensagem de publicação e a enviará a um cliente aleatório em cada assinatura compartilhada correspondente. O comportamento curinga das assinaturas compartilhadas pode ser explicado no diagrama a seguir.
![\[Assinaturas compartilhadas com caracteres curinga em. AWS IoT Core\]](http://docs.aws.amazon.com/pt_br/iot/latest/developerguide/images/mqtt_shared_subscriptions_wildcard.gif)
Neste exemplo, há três assinaturas compartilhadas correspondentes ao tópico de publicação do MQTT `sports/tennis`. O agente de mensagens copia a mensagem publicada e a envia para um cliente aleatório em cada grupo correspondente.
O cliente 1 e o cliente 2 compartilham a assinatura: `$share/consumer1/sports/tennis`
O cliente 3 e o cliente 4 compartilham a assinatura: `$share/consumer1/sports/#`
O cliente 5 e o cliente 6 compartilham a assinatura: `$share/consumer2/sports/tennis`
Para acessar mais informações sobre limites de assinaturas compartilhadas, consulte [AWS IoT Core endpoints and quotas](https://docs.aws.amazon.com//general/latest/gr/iot-core.html) na *Referência geral da AWS *. Para testar assinaturas compartilhadas usando o cliente AWS IoT MQTT no [AWS IoT console](https://console.aws.amazon.com/iot/home), consulte. [Testar assinaturas compartilhadas no cliente MQTT](view-mqtt-messages.md#view-mqtt-shared-subscriptions) Você também pode ver em quais tópicos os clientes conectados assinaram, incluindo assinaturas compartilhadas, usando os recursos de gerenciamento de conexão do cliente. Para obter mais informações, consulte [Gerenciar conexões do MQTT](#mqtt-client-disconnect). Para obter mais informações sobre assinaturas compartilhadas, consulte [Assinaturas compartilhadas](https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901250) da especificação 4.0. MQTTv5
#### Enfileiramento de mensagens de assinaturas compartilhadas
Para aumentar a confiabilidade da entrega de mensagens, as assinaturas compartilhadas incluem recursos de enfileiramento de mensagens que armazenam mensagens quando não há assinantes on-line disponíveis. Quando um grupo de assinatura compartilhado contém pelo menos um membro com uma sessão persistente, o recurso de enfileiramento é habilitado para o grupo. Ao distribuir mensagens, os membros on-line são selecionados como destinatários. As mensagens de QoS 1 são colocadas na fila quando nenhum membro é encontrado on-line ou quando os assinantes excedem o limite [https://docs.aws.amazon.com//general/latest/gr/iot-core.html#message-broker-limits](https://docs.aws.amazon.com//general/latest/gr/iot-core.html#message-broker-limits). As mensagens em fila são entregues quando os membros existentes retomam suas sessões persistentes ou quando novos membros ingressam no grupo. As mensagens em fila são entregues em até vinte mensagens em fila por segundo por assinante do grupo ativo, junto com quaisquer outras mensagens entregues ao assinante de acordo com as assinaturas.
Por padrão, a retenção de mensagens em fila segue a cota [https://docs.aws.amazon.com//general/latest/gr/iot-core.html#message-broker-limits](https://docs.aws.amazon.com//general/latest/gr/iot-core.html#message-broker-limits). No entanto, se um intervalo de expiração de mensagens (MEI) for definido na mensagem de publicação de entrada, o MEI terá precedência. Quando o MEI está presente, ele determina o período de retenção da mensagem, independentemente do período de expiração da sessão persistente.
As taxas de fila de mensagens são limitadas de acordo com a cota [https://docs.aws.amazon.com//general/latest/gr/iot-core.html#message-broker-limits](https://docs.aws.amazon.com//general/latest/gr/iot-core.html#message-broker-limits), e o número de mensagens é limitado pela cota [https://docs.aws.amazon.com//general/latest/gr/iot-core.html#message-broker-limits](https://docs.aws.amazon.com//general/latest/gr/iot-core.html#message-broker-limits). Para visualizar e gerenciar suas cotas, acesse o console [Service Quotas](https://console.aws.amazon.com/servicequotas/home).
Você pode monitorar a fila CloudWatch pesquisando no `AWS/Usage` namespace ou pode usar o seguinte comando da CLI para `ApproximateQueueDepth` listar as métricas associadas à profundidade da fila de cada grupo de assinaturas compartilhadas.
```
aws cloudwatch list-metrics --namespace "AWS/Usage" --dimensions Name=Resource,Value='ApproximateQueueDepth'
```
Quando esses limites são excedidos, somente as mensagens que já estavam na fila antes de atingir o limite são retidas. Novas mensagens recebidas que excederiam os limites são descartadas. O sistema não substitui mensagens antigas em fila por mensagens mais novas.
O enfileiramento de mensagens é registrado em CloudWatch métricas e CloudWatch registros. Para obter informações sobre as entradas gravadas em CloudWatch e CloudWatch Logs, consulte [Métricas do agente de mensagens](metrics_dimensions.md#message-broker-metrics) [Entrada de log em fila](cwl-format.md#log-mb-queued) e. Ainda ocorre cobrança pelas mensagens em fila de acordo com a taxa de mensagens padrão. Para obter mais informações sobre os preços das mensagens, consulte [Preços do AWS IoT Core](https://aws.amazon.com/iot-core/pricing).
**Ciclo de vida da sessão em um grupo de assinatura compartilhado**
Quando uma sessão limpa assina um grupo, ela se torna um membro on-line do grupo. Quando cancela a assinatura ou se desconecta, a sessão limpa sai do grupo.
Quando uma sessão persistente assina um grupo, ela se torna um membro on-line do grupo. Quando ela se desconecta, ainda permanece no grupo, mas se torna um membro offline do grupo. Quando ela se reconecta, se torna um membro on-line novamente. A sessão persistente deixa o grupo quando ela cancela explicitamente a assinatura ou quando expira após a desconexão.
### Início limpo e expiração da sessão
Você pode usar o Clean Start e o Session Expiry para lidar com suas sessões persistentes com mais flexibilidade. Um sinalizador Clean Start indica se a sessão deve começar sem usar uma sessão existente. O intervalo de expiração da sessão indica por quanto tempo manter a sessão após uma desconexão. O intervalo de expiração da sessão pode ser modificado na desconexão. Para obter mais informações, consulte [Sessões persistentes do MQTT](#mqtt-persistent-sessions).
### Código de motivo em todos ACKs
Você pode depurar ou processar mensagens de erro com mais facilidade usando os códigos de motivo. Os códigos de motivo são retornados pelo agente de mensagens com base no tipo de interação com o corretor (Assinar, Publicar, Confirmar). Para obter mais informações, consulte [Códigos de motivo do MQTT](#mqtt5-reason-codes). Para obter uma lista completa dos códigos de motivo do MQTT, consulte a especificação do [MQTT v5](https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901031).
### Aliases de tópicos
Você pode substituir o nome de um tópico por um alias de tópico, que é um número inteiro de dois bytes. O uso de aliases de tópicos pode otimizar a transmissão de nomes de tópicos para reduzir potencialmente os custos de dados em serviços de dados medidos. AWS IoT Core tem um limite padrão de 8 aliases de tópicos. Para obter mais informações, consulte [Endpoints e cotas do AWS IoT Core](https://docs.aws.amazon.com//general/latest/gr/iot-core.html) na *Referência geral da AWS *.
### Validade da mensagem
Você pode adicionar valores de expiração de mensagens às mensagens publicadas. Esses valores representam o intervalo de expiração da mensagem (MEI) em segundos. Se as mensagens não tiverem sido enviadas aos assinantes dentro desse intervalo, a mensagem expirará e será removida. Se você não definir o valor de expiração da mensagem, ela não expirará.
Na saída, o assinante receberá uma mensagem com o tempo restante no intervalo de expiração. Por exemplo, se uma mensagem de publicação de entrada tiver uma expiração de 30 segundos e for encaminhada para o assinante após 20 segundos, o campo de expiração da mensagem será atualizado para 10. É possível que a mensagem recebida pelo assinante tenha um MEI atualizado de 0. Isso porque, assim que o tempo restante for de 999 ms ou menos, ele será atualizado para 0.
Em AWS IoT Core, o MEI mínimo é 1. Se o intervalo for definido como 0 do lado do cliente, ele será ajustado para 1. O intervalo máximo de expiração da mensagem é 604800 (7 dias). Qualquer valor maior que isso será ajustado para o valor máximo.
Na comunicação entre versões, o comportamento da expiração da mensagem é decidido pela versão MQTT da mensagem de publicação de entrada. Por exemplo, uma mensagem com expiração de mensagem enviada por uma sessão conectada via MQTT5 pode expirar para dispositivos inscritos com sessões. MQTT3 A tabela abaixo mostra como a expiração de mensagens oferece suporte aos seguintes tipos de mensagens publicadas:
****
| Publicar tipo de mensagem | Intervalo de expiração da mensagem |
| --- | --- |
| Publicação regular | Se um servidor não entregar a mensagem dentro do prazo especificado, a mensagem expirada será removida e o assinante não a receberá. Isso inclui situações como quando um dispositivo não está fazendo backup de suas mensagens do QoS 1. |
| Reter | Se uma mensagem retida expirar e um novo cliente se inscrever no tópico, o cliente não receberá a mensagem após a assinatura. |
| Último testamento | O intervalo para as mensagens de último testamento começa depois que o cliente se desconecta e o servidor tenta entregar a mensagem de último testamento aos assinantes. |
| Mensagens na fila | Se uma QoS 1 de saída com intervalo de expiração de mensagens expirar quando um cliente estiver offline, após a retomada da [sessão persistente](#mqtt-persistent-sessions), o cliente não receberá a mensagem expirada. |
### Outros recursos do MQTT 5
**Desconexão do servidor**
Quando ocorre uma desconexão, o servidor pode enviar proativamente ao cliente um DISCONNECT para notificar o encerramento da conexão com um código de motivo para a desconexão.
**Resposta/solicitação**
Os editores podem solicitar que uma resposta seja enviada pelo destinatário para um tópico especificado pelo publicador no momento do recebimento.
**Tamanho máximo do pacote**
O cliente e o servidor podem especificar de modo independente o tamanho máximo do pacote ao qual eles dão suporte.
**Formato de carga útil e tipo de conteúdo**
Você pode especificar o formato da carga útil (binário, texto) e o tipo de conteúdo quando uma mensagem é publicada. Eles são encaminhados para o destinatário da mensagem.
## MQTT 5 propriedades
As propriedades do MQTT 5 são adições importantes ao padrão MQTT para oferecer suporte aos novos recursos do MQTT 5, como a expiração da sessão e o padrão. Request/Response Em AWS IoT Core, você pode criar [regras](https://docs.aws.amazon.com//iot/latest/developerguide/republish-rule-action.html) que podem encaminhar as propriedades em mensagens de saída ou usar [HTTP Publish](https://docs.aws.amazon.com//iot/latest/apireference/API_iotdata_Publish.html) para publicar mensagens MQTT com algumas das novas propriedades.
A tabela a seguir lista todas as propriedades do MQTT 5 que AWS IoT Core suportam.
| Propriedade | Description | Tipo de entrada | Pacote |
| --- | --- | --- | --- |
| Indicador de formato da carga útil | Um valor booliano que indica se a carga útil está formatada como UTF-8. | Byte | PUBLICAR, CONECTAR |
| Tipo de conteúdo | Uma string UTF-8 que descreve o conteúdo da carga útil. | String UTF-8 | PUBLICAR, CONECTAR |
| Tópico de resposta | Uma string UTF-8 que descreve o tópico que o destinatário deve publicar como parte do fluxo solicitação-resposta. O tópico não deve conter caracteres curinga. | String UTF-8 | PUBLICAR, CONECTAR |
| Dados de correlação | Os dados binários usados pelo remetente da mensagem de solicitação para identificar para qual solicitação é a mensagem de resposta. | Binário | PUBLICAR, CONECTAR |
| Propriedades do usuário | Um par de strings UTF-8. Essa propriedade pode aparecer várias vezes em um pacote. Os destinatários receberão os pares de chave-valor na mesma ordem em que são enviados. | Par de strings UTF-8 | CONECTAR, PUBLICAR, Propriedades, ASSINAR, DESCONECTAR, REMOVER ASSINATURA |
| Intervalo de expiração da mensagem | Um valor inteiro de 4 bytes que representa o intervalo de expiração da mensagem em segundos. Se ausente, a mensagem não expira. | inteiro de 4 bytes | PUBLICAR, CONECTAR |
| Intervalo de expiração da sessão | Um número inteiro de 4 bytes que representa o intervalo de expiração da sessão em segundos. AWS IoT Core suporta no máximo 7 dias, com um máximo padrão de uma hora. Se o valor definido exceder o máximo da sua conta, AWS IoT Core retornará o valor ajustado no CONNACK. | inteiro de 4 bytes | CONECTAR, CONNACK, DESCONECTAR |
| Identificador de cliente atribuído | Um ID de cliente aleatório gerado AWS IoT Core quando um ID de cliente não é especificado pelos dispositivos. O ID aleatório do cliente deve ser um novo identificador de cliente que não seja usado por nenhuma outra sessão atualmente gerenciada pelo corretor. | String UTF-8 | CONNACK |
| Servidor Keep Alive | Um número inteiro de 2 bytes que representa o tempo de manutenção de atividade atribuído pelo servidor. O servidor desconectará o cliente se o cliente ficar inativo por mais do que o tempo de manutenção de atividade. | Inteiro de 2 bytes | CONNACK |
| Solicitar informações sobre o problema | Um valor booliano que indica se a string do motivo ou as propriedades do usuário são enviadas no caso de falhas. | Byte | CONECTAR |
| Máximo de recebimento | Um inteiro de 2 bytes que representa o número máximo de pacotes PUBLICAR QOS > 0 que podem ser enviados sem receber um PUBACK. | Inteiro de 2 bytes | CONNECT, CONNACK |
| Tópico: máximo do alias | Esse valor indica o valor mais alto que será aceito como um alias de tópico. O padrão é 0. | Inteiro de 2 bytes | CONNECT, CONNACK |
| QoS máximo | O valor máximo de QoS que AWS IoT Core suporta. O padrão é 1. O AWS IoT Core não comporta QoS 2. | Byte | CONNACK |
| Reter disponível | Um valor booleano que indica se o agente de AWS IoT Core mensagens suporta mensagens retidas. O padrão é um. | Byte | CONNACK |
| Tamanho máximo do pacote | O tamanho máximo do pacote que AWS IoT Core aceita e envia. Não pode exceder 128 KB. | inteiro de 4 bytes | CONNECT, CONNACK |
| Assinatura de curinga disponível | Um valor booleano que indica se o agente de AWS IoT Core mensagens oferece suporte à assinatura Wildcard Available. O padrão é um. | Byte | CONNACK |
| Identificador de assinatura disponível | Um valor booleano que indica se o agente de AWS IoT Core mensagens oferece suporte ao Identificador de Assinatura Disponível. O padrão é 0. | Byte | CONNACK |
## Códigos de motivo do MQTT
O MQTT 5 introduz relatórios de erros aprimorados com respostas de código de motivo. AWS IoT Core pode retornar códigos de motivo, incluindo, mas não se limitando aos seguintes, agrupados por pacotes. Para obter uma lista completa dos códigos de motivo com suporte no MQTT 5, confira [especificações do MQTT v5](https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901031).
**Códigos de motivo do CONNACK**
| Valor | Hex | Nome do código de motivo | Description |
| --- | --- | --- | --- |
| 0 | 0x00 | Bem-sucedida | A conexão é criptografada. |
| 128 | 0x80 | Erro não especificado | O servidor não deseja revelar o motivo da falha, ou nenhum dos outros códigos de motivo se aplica. |
| 133 | 0x85 | O identificador de cliente não é válido | O identificador do cliente é uma string válida, mas não é permitido pelo servidor. |
| 134 | 0x86 | Nome de usuário ou senha incorretos | O servidor não aceita o nome de usuário ou a senha especificados pelo cliente. |
| 135 | 0x87 | Não autorizado | O cliente não está autorizado a se conectar. |
| 144 | 0x90 | Nome do tópico inválido | O nome do tópico do testamento está formado corretamente, mas não é aceito pelo servidor. |
| 151 | 0x97 | Cota excedida | Um limite imposto administrativo ou de implementação foi excedido. |
| 155 | 0x9B | Não há suporte ao QoS | O servidor não dá suporte a QoS definida na QoS do Testamento. |
**Códigos de motivo PUBACK**
| Valor | Hex | Nome do código de motivo | Description |
| --- | --- | --- | --- |
| 0 | 0x00 | Bem-sucedida | A mensagem foi aceita. A publicação da mensagem de QoS 1 continua. |
| 128 | 0x80 | Erro não especificado | O destinatário não aceita a publicação, mas não quer revelar o motivo ou ele não corresponde a um dos outros valores. |
| 135 | 0x87 | Não autorizado | A ação PUBLICAR não é autorizada. |
| 144 | 0x90 | Nome do tópico inválido | O nome do tópico não está mal formado, mas não é aceito pelo cliente ou servidor. |
| 145 | 0x91 | Identificador de pacote em uso | O identificador do pacote já está em uso. Isso pode indicar uma incompatibilidade no estado da sessão entre o cliente e o servidor. |
| 151 | 0x97 | Cota excedida | Um limite imposto administrativo ou de implementação foi excedido. |
**Código do motivo da ação DESCONECTAR**
| Valor | Hex | Nome do código de motivo | Description |
| --- | --- | --- | --- |
| 129 | 0x81 | Pacote malformado | O pacote recebido não está em conformidade com essa especificação. |
| 130 | 0x82 | Erro de protocolo | Um pacote inesperado ou fora de ordem foi recebido. |
| 135 | 0x87 | Não autorizado | A solicitação não está autorizada. |
| 139 | 0x8B | Encerramento do servidor | O servidor está sendo desligado. |
| 141 | 0x8D | Tempo limite do Keep Alive | A conexão está fechada porque nenhum pacote foi recebido por 1,5 veze o tempo de Keep Alive. |
| 142 | 0x8E | Sessão retomada | Outra conexão usando o mesmo ClientID foi conectada, fazendo com que essa conexão seja fechada. |
| 143 | 0x8F | Filtro de tópicos inválido | O filtro de tópicos está formado corretamente, mas não é aceito pelo servidor. |
| 144 | 0x90 | Nome do tópico inválido | O nome do tópico está formado corretamente, mas não é aceito por esse cliente ou servidor. |
| 147 | 0x93 | Máximo de recebimento excedido | O cliente ou o servidor recebeu mais do que a publicação Máximo de recebimento para a qual não enviou PUBACK ou PUBCOMP. |
| 148 | 0x94 | Aliases do tópico inválido | O cliente ou servidor recebeu um pacote PUBLICAR contendo um alias de tópico maior que o alias de tópico máximo enviado no pacote CONECTAR ou CONNACK. |
| 151 | 0x97 | Cota excedida | Um limite imposto administrativo ou de implementação foi excedido. |
| 152 | 0x98 | Ação administrativa | A conexão foi encerrada devido a uma ação administrativa. |
| 155 | 0x9B | Não há suporte ao QoS | O cliente especificou uma QoS maior que a QoS especificada em uma QoS máxima no CONNACK. |
| 161 | 0xA1 | Identificadores de assinatura sem suporte | O servidor não tem suporte para identificadores de assinatura; a assinatura não é aceita. |
**Códigos de motivo SUBACK**
| Valor | Hex | Nome do código de motivo | Description |
| --- | --- | --- | --- |
| 0 | 0x00 | QoS concedida 0 | A assinatura é aceita e a QoS máxima enviada será QoS 0. Pode ser uma QoS menor do que a solicitada. |
| 1 | 0x01 | QoS concedida 1 | A assinatura é aceita e a QoS máxima enviada será QoS 1. Pode ser uma QoS menor do que a solicitada. |
| 128 | 0x80 | Erro não especificado | A assinatura não é aceita e o Servidor não deseja revelar o motivo ou nenhum dos outros Códigos de Motivo se aplica. |
| 135 | 0x87 | Não autorizado | O Cliente não está autorizado a fazer essa assinatura. |
| 143 | 0x8F | Filtro de tópicos inválido | O Filtro de tópicos está formado corretamente, mas não é permitido para este Cliente. |
| 145 | 0x91 | Identificador de pacote em uso | O identificador do pacote já está em uso. |
| 151 | 0x97 | Cota excedida | Um limite imposto administrativo ou de implementação foi excedido. |
**Códigos de motivo UNSUBACK**
| Valor | Hex | Nome do código de motivo | Description |
| --- | --- | --- | --- |
| 0 | 0x00 | Bem-sucedida | A assinatura é excluída. |
| 128 | 0x80 | Erro não especificado | Não foi possível concluir a assinatura e o Servidor não deseja revelar o motivo ou nenhum dos outros Códigos de Motivo se aplica. |
| 143 | 0x8F | Filtro de tópicos inválido | O Filtro de tópicos está formado corretamente, mas não é permitido para este Cliente. |
| 145 | 0x91 | Identificador de pacote em uso | O identificador do pacote já está em uso. |
## AWS IoT diferenças das especificações do MQTT
A implementação do agente de mensagens é baseada na [especificação MQTT v3.1.1](http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html) e na [Especificação MQTT v5.0](http://docs.oasis-open.org/mqtt/mqtt/v5.0/mqtt-v5.0.html), mas difere das especificações das seguintes maneiras:
+ AWS IoT não suporta os seguintes pacotes para o MQTT 3: PUBREC, PUBREL e PUBCOMP.
+ AWS IoT não suporta os seguintes pacotes para o MQTT 5: PUBREC, PUBREL, PUBCOMP e AUTH.
+ AWS IoT não suporta o redirecionamento do servidor MQTT 5.
+ AWS IoT suporta somente os níveis 0 e 1 de qualidade de serviço (QoS) do MQTT. AWS IoT não suporta publicação ou assinatura com QoS nível 2. Quando o nível 2 da QoS é solicitado, o agente de mensagens do não envia um PUBACK ou SUBACK.
+ Em AWS IoT, assinar um tópico com QoS nível 0 significa que uma mensagem é entregue zero ou mais vezes. Uma mensagem pode ser entregue mais de uma vez. As mensagens entregues mais de uma vez podem ser enviadas com outro ID de pacote. Nesses casos, o sinalizador DUP não é definido.
+ Ao responder a uma solicitação de conexão, o agente de mensagens envia uma mensagem CONNACK. Essa mensagem contém um sinalizador para indicar se a conexão está retomando uma sessão anterior.
+ Antes de enviar pacotes de controle adicionais ou uma solicitação de desconexão, o cliente deve esperar que a mensagem CONNACK seja recebida em seu dispositivo pelo agente de mensagens AWS IoT .
+ Quando um cliente se inscreve em um tópico, pode haver uma demora entre o momento em que o operador envia uma mensagem SUBACK e o momento em que o cliente começa a receber novas mensagens correspondentes.
+ Quando um cliente usa o caractere curinga `#` no filtro de tópicos para assinar um tópico, há correspondência de todas as sequências de caracteres em e abaixo de seu nível na hierarquia de tópicos. Porém, o tópico principal não corresponde. Por exemplo, uma assinatura do tópico `sensor/#` recebe mensagens publicadas para os tópicos `sensor/`, `sensor/temperature`, `sensor/temperature/room1`, mas não as mensagens publicadas para `sensor`. Para obter mais informações sobre curingas, consulte [Filtros de nomes de tópicos](topics.md#topicfilters).
+ O agente de mensagens usa o ID do cliente para identificar cada cliente. O ID do cliente é transmitido do cliente para o agente de mensagens como parte da carga útil do MQTT. Dois clientes com o mesmo ID de cliente não podem ser conectados simultaneamente ao agente de mensagens. Quando um cliente se conecta ao agente de mensagens usando um ID que outro cliente está usando, a nova conexão do cliente é aceita e o cliente conectado anteriormente é desconectado. Você também pode desconectar manualmente os clientes usando o. APIs Para obter mais informações, consulte [Gerenciar conexões do MQTT](#mqtt-client-disconnect).
+ Em raras ocasiões, o agente de mensagens pode reenviar a mesma mensagem lógica PUBLICAR com um ID de pacote diferente.
+ A assinatura de filtros de tópicos que contêm um caractere curinga não pode receber mensagens retidas. Para receber uma mensagem retida, a solicitação de assinatura deve conter um filtro de tópico que corresponda exatamente ao tópico da mensagem retida.
+ O agente de mensagens não garante a ordem em que as mensagens e o ACK são recebidos.
+ AWS IoT podem ter limites diferentes das especificações. Para obter mais informações, consulte [agente de mensagens AWS IoT Core e limites e cotas do protocolo](https://docs.aws.amazon.com//general/latest/gr/iot-core.html#message-broker-limits) no *Guia de referência do AWS IoT *.
+ Não há suporte para o sinalizador MQTT DUP.
## Gerenciar conexões do MQTT
AWS IoT Core fornece ajuda APIs para gerenciar conexões MQTT, incluindo a capacidade de desconectar clientes e gerenciar suas sessões. Esses recursos oferecem mais controle sobre sua frota de AWS IoT clientes e ajudam na solução de problemas de conexão.
### DeleteConnection API
Use a `DeleteConnection` API para desconectar dispositivos MQTT AWS IoT Core especificando seu cliente. IDs Quando você desconecta um cliente, AWS IoT Core desconecta o cliente do agente de mensagens e, opcionalmente, pode limpar o estado da sessão e suprimir a AWS IoT Core mensagem Last Will and Testament (LWT).
Quando você chama a `DeleteConnection` API, AWS IoT Core executa várias ações para garantir uma desconexão limpa. AWS IoT Core primeiro envia uma mensagem de desconexão do MQTT ao cliente para encerrar a sessão do MQTT. Em seguida, o serviço fecha o TCP/TLS soquete subjacente.
O agente de mensagens envia um pacote `DISCONNECT` ao dispositivo e publica um [evento de ciclo de vida](life-cycle-events.md) com o motivo da desconexão `API_INITIATED_DISCONNECT`. Isso ajuda a identificar quando uma desconexão foi iniciada por meio da API e não pelo cliente ou devido a problemas de rede. Você pode monitorar esses eventos para fins de visibilidade, solução de problemas e auditoria. Por exemplo, você pode usar AWS IoT regras para processar esses eventos para rastrear quando e por que os clientes foram desconectados.
Se você definir o `cleanSession` parâmetro como`true`, AWS IoT Core remove o estado da sessão do cliente, incluindo todas as assinaturas e mensagens em fila. Se você limpar uma sessão, a sessão persistente será encerrada. Se o cliente tiver uma sessão persistente e o parâmetro `preventWillMessage` estiver definido como `false`, o serviço enviará a mensagem LWT, se disponível, o que é útil durante as operações de manutenção planejadas.
Quando você chama a API `DeleteConnection`, o processo de desconexão começa imediatamente, mas o momento exato em que o cliente reconhece a desconexão pode variar com base nas condições da rede e na implementação do cliente. A maioria dos clientes detectará a desconexão em alguns segundos, mas, em alguns casos, com conectividade de rede inadequada, pode levar mais tempo para que o cliente reconheça que foi desconectado.
**nota**
Ao forçar a desconexão, o cliente precisa se autenticar e reautorizar com um novo estado de sessão. A chamada de API em si não impede a reconexão dos clientes. Se isso for desejado, além disso, a credencial ou a política do cliente deverão ser modificadas antes de emitir a chamada de API `DeleteConnection`.
Para obter mais informações sobre preços, consulte [Preços do AWS IoT Core](https://aws.amazon.com/iot-core/pricing/).
#### Casos de uso
A API `DeleteConnection` é útil para gerenciar clientes que apresentam comportamento problemático ou consomem recursos excessivos. Ao forçar a desconexão, você pode garantir que os clientes restabeleçam suas conexões com autenticação e autorização adequadas, o que pode ajudar a resolver problemas de consumo de recursos.
Os cenários de redirecionamento de clientes também se beneficiam dessa API. Quando você precisa redirecionar clientes para endpoints diferentes ou Regiões da AWS pode desconectá-los programaticamente e fazer com que eles se reconectem a um endpoint diferente AWS IoT Core alterando as configurações de DNS. Essa API pode ajudar a resolver conexões bloqueadas ou eliminar estados de sessão problemáticos que podem estar impedindo a operação normal.
#### Parâmetros de API
A API `DeleteConnection` aceita os seguintes parâmetros:
clientId (obrigatório)
O identificador exclusivo do cliente do MQTT a ser desconectado. Isso é especificado no caminho do URL. O ID do cliente não pode começar com cifrão (\$1).
O cliente MQTT IDs pode conter caracteres que não são válidos em solicitações HTTP. Ao usar a API `DeleteConnection`, você deve codificar em URL (codificação percentual) quaisquer caracteres no ID do cliente que sejam válidos no MQTT, mas não em HTTP. Isso inclui caracteres especiais, como espaços, barras (/) e caracteres UTF-8. Por exemplo, um espaço se torna %20, uma barra invertida se torna %2F e o caractere UTF-8 ü se torna %C3%BC. A codificação adequada garante que o cliente IDs MQTT seja transmitido corretamente na chamada de API baseada em HTTP.
cleanSession (opcional)
Especifica se o estado da sessão do cliente deve ser removido ao se desconectar. Defina como `true` para excluir todas as informações da sessão, incluindo assinaturas e mensagens em fila. Defina como `false` para preservar o estado da sessão. Por padrão, isso é definido como `false` (preserva o estado da sessão). Para sessões limpas, esse parâmetro será ignorado.
preventWillMessage (opcional)
Controla se a mensagem AWS IoT Core Last Will and Testament (LWT) é enviada se estiver disponível após a desconexão. Defina como `true` para evitar o envio da mensagem LWT. Defina como `false` para permitir o envio. Por padrão, isso é definido como `false` (envia o LWT, se disponível).
#### Sintaxe da API
A API `DeleteConnection` usa o seguinte formato de solicitação HTTP:
```
DELETE /connections/?cleanSession=&preventWillMessage= HTTP/1.1
```
Exemplo de solicitações:
```
// Basic disconnect (preserves session, allows LWT message)
DELETE /connections/myDevice123 HTTP/1.1
// Disconnect and clear session
DELETE /connections/myDevice123?cleanSession=TRUE HTTP/1.1
// Disconnect, clear session, and prevent LWT message
DELETE /connections/myDevice123?cleanSession=TRUE&preventWillMessage=TRUE HTTP/1.1
```
Solicitações bem-sucedidas exibem HTTP 200 OK sem corpo de resposta.
**nota**
O nome do serviço usado pelo [AWS Signature Version 4](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html) para assinar solicitações é: *iotdevicegateway*. Você pode encontrar o endpoint usando o comando `aws iot describe-endpoint --endpoint-type iot:Data-ATS`.
#### Permissões obrigatórias
Para usar a API `DeleteConnection`, é necessário ter a seguinte permissão do IAM:
```
iot:DeleteConnection
```
Você pode definir essa permissão para um cliente específico IDs usando políticas baseadas em recursos. Por exemplo:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iot:DeleteConnection",
"Resource": "arn:aws:iot:region:account:client/myDevice*"
}
]
}
```
#### Considerações importantes
Clientes desconectados podem tentar se reconectar imediatamente, a menos que você tenha implementado uma lógica adicional para evitar a reconexão. A operação de desconexão apenas encerra a conexão atual e não impede que uma conexão se estabeleça novamente. Se você precisar evitar a reconexão, pense em implementar a lógica do lado do cliente ou desabilitar a credencial de um dispositivo.
Os limites de taxa se aplicam à API como parte da limitação de taxa padrão da AWS IoT Core API. Ao planejar operações de desconexão em massa, leve em conta esses limites e implemente a lógica de nova tentativa e as estratégias de agrupamento em lote apropriadas para evitar o controle de utilização. Para saber mais, consulte [Endpoints e cotas do AWS IoT Core](https://docs.aws.amazon.com/general/latest/gr/iot-core.html#message-broker-limits).
#### Respostas de erro
A API `DeleteConnection` pode exibir as seguintes respostas de erro:
InvalidRequestException
A solicitação não é válida. Isso poderá ocorrer se o formato do ID do cliente for inválido, contiver um prefixo de cifrão (\$1) ou se os parâmetros necessários estiverem ausentes.
ResourceNotFoundException
O ID do cliente especificado não existe ou não está conectado no momento e não tem uma sessão persistente.
UnauthorizedException
Você não tem autorização para executar esta operação. Garanta que você tenha as permissões `iot:DeleteConnection` necessárias.
ForbiddenException
O chamador não está autorizado a fazer a solicitação. Isso pode ocorrer devido a permissões insuficientes do IAM ou restrições de políticas baseadas em recursos.
ThrottlingException
A taxa excede o limite. Reduza a frequência de suas chamadas de API e implemente a lógica de nova tentativa apropriada com recuo exponencial.
InternalFailureException
Ocorreu um erro inesperado. Tente fazer a solicitação novamente após um breve atraso.
ServiceUnavailableException
O serviço está temporariamente indisponível. Tente fazer a solicitação novamente após um breve atraso.