Todos os produtos
Search

Este produto

    IoT Platform:Pub

    Central de documentação

    IoT Platform:Pub

    Última atualização: Jun 26, 2026

    Publica uma mensagem em um dispositivo por meio de um tópico personalizado. Use esta operação para transmitir mensagens aos dispositivos online de um produto específico, desde que esses dispositivos estejam inscritos no tópico personalizado correspondente.

    Observações de uso

    Ao chamar esta operação para transmitir mensagens, observe os seguintes pontos:

    • Ao configurar o dispositivo, escreva código para definir o tópico. Não é necessário criar o tópico no console do IoT Platform.

    • Por padrão, a inscrição em um tópico suporta até 1.000 dispositivos. Para transmitir mensagens de broadcast de um tópico personalizado para mais de 1.000 dispositivos, use o protocolo Message Queuing Telemetry Transport (MQTT) 5.0, ative o recurso de broadcast para o tópico personalizado e defina as mensagens desse tópico como mensagens retidas. Para mais informações, consulte UpdateTopicConfig.

    Limites

    Esta operação não permite enviar comandos para configurar propriedades ou invocar serviços do dispositivo.

    Limites de QPS

    Você pode chamar esta API até 1.600 vezes por segundo por conta.

    Nota

    Usuários do Resource Access Management (RAM) vinculados a uma conta Alibaba Cloud compartilham a cota dessa conta.

    Depuração

    O OpenAPI Explorer calcula automaticamente o valor da assinatura. Recomendamos executar esta operação diretamente no OpenAPI Explorer, que também gera dinamicamente exemplos de código para diferentes SDKs.

    Parâmetros da solicitação

    Parameter

    Type

    Required

    Example

    Description

    Action

    String

    Yes

    Pub

    A operação a ser executada. Defina o valor como Pub.

    ProductKey

    String

    Yes

    a1Q5XoY****

    A ProductKey do produto ao qual pertence o dispositivo destinatário da mensagem.

    MessageContent

    String

    Yes

    eyJ0ZXN0IjoidGFzayBwdWIgYnJvYWRjYXN0In0=

    O corpo da mensagem a ser publicada.

    Para gerar o corpo da mensagem, converta o conteúdo original em dados binários e aplique a codificação Base64.

    Nota

    O IoT Platform decodifica os dados com o algoritmo Base64 antes de enviar a mensagem ao dispositivo. Dessa forma, o dispositivo recebe o conteúdo já decodificado.

    TopicFullName

    String

    Yes

    /a1Q5XoY****/device1/user/get

    O tópico personalizado do dispositivo que receberá a mensagem.

    • Para dispositivos gateway MQTT, usa-se o tópico personalizado original do dispositivo. Para mais informações, consulte Topics.

    • Para dispositivos gateway não MQTT, o tópico personalizado deve seguir um dos formatos abaixo:

      • /${productKey}/${deviceName}/user/${TopicShortName}: O sistema envia a mensagem para um dispositivo específico pertencente ao produto cuja ProductKey corresponde à variável ${productKey}.

      • /broadcast/${productKey}/${Custom field}: O sistema transmite a mensagem para todos os dispositivos online do produto identificado pela variável ${productKey}, desde que estejam inscritos no tópico personalizado. Substitua ${productKey} pela ProductKey do produto cujos dispositivos receberão a mensagem. A variável ${Custom field} representa um campo personalizado.

    Importante

    • O tópico precisa ter permissão de Subscribe ou Publish and Subscribe.

    • Antes de chamar a operação Pub, confirme se o dispositivo está inscrito no tópico. Caso contrário, ele não receberá a mensagem.

    Para consultar tópicos personalizados, use um dos métodos a seguir:

    • Chame a operação QueryProductTopic para listar os tópicos personalizados de um produto.

    • Na aba Topic Categories da página de detalhes do produto, visualize os tópicos personalizados disponíveis.

    • Na aba Topic List da página de detalhes do dispositivo, verifique os tópicos personalizados nos quais o dispositivo está inscrito.

    IotInstanceId

    String

    No

    iot-cn-0pp1n8t****

    O ID da instância. Visualize o ID da instância na página Overview do console do IoT Platform.

    Importante

    • Se a sua instância possuir um ID, especifique-o neste parâmetro. A ausência dessa informação causará falha na chamada.

    • Caso a página Overview não esteja visível ou a instância não tenha um ID, este parâmetro é opcional.

    Para mais detalhes, consulte o tópico Overview sobre instâncias do IoT.

    Qos

    Integer

    No

    0

    O nível de qualidade de serviço (QoS) da mensagem. Valores válidos:

    • 0: O sistema entrega a mensagem no máximo uma vez.

    • 1: O sistema garante pelo menos uma entrega. Se não houver resposta PUBACK após a publicação de uma mensagem QoS 1, ela será reenviada assim que o dispositivo se reconectar ao IoT Platform.

    Valor padrão: 0.

    Para saber mais sobre o envio de mensagens, leia a seção "Device connection" no tópico Limits.

    ResponseTopic

    String

    No

    /a1Q5XoY****/device1/user/update

    Tópico de resposta usado no modo de comunicação requisição/resposta com MQTT 5.0. Consulte MQTT 5.0 para mais informações.

    CorrelationData

    String

    No

    aGVsbG8****

    Dados de correlação para o modo de comunicação requisição/resposta via MQTT 5.0. Configure este parâmetro conforme a necessidade do seu negócio.

    O destinatário da mensagem pode usar esses dados para processar a requisição adequadamente.

    Nota

    É obrigatório converter os dados de correlação em formato binário e aplicar codificação Base64 para gerar uma string válida.

    UserProp.N.Key

    String

    No

    key1

    Chave da propriedade personalizada definida para comunicação via MQTT 5.0.

    Use este parâmetro em conjunto com UserProp.N.Value.

    UserProp.N.Value

    String

    No

    value1

    Valor da propriedade personalizada definida para comunicação via MQTT 5.0.

    Use este parâmetro juntamente com UserProp.N.Key.

    DeviceName

    String

    No

    device1

    Nome do gateway cloud MQTT.

    Importante

    Este parâmetro é necessário apenas ao enviar mensagens para um gateway cloud MQTT.

    ContentType

    String

    No

    text

    Tipo de conteúdo da mensagem quando se usa MQTT 5.0.

    Define o tipo MIME do arquivo, como text ou plain.

    PayloadFormatIndicator

    Integer

    No

    1

    Identificador de formato do payload para mensagens em MQTT 5.0. Valores válidos:

    • 0: A mensagem contém dados binários desconhecidos.

    • 1: O payload da mensagem consiste em caracteres codificados em UTF-8.

    Retained

    Boolean

    No

    true

    Indica se a mensagem deve ser marcada como retida durante a comunicação via MQTT 5.0.

    • true

    • false

    MessageExpiryInterval

    Long

    No

    2

    Período de validade da mensagem em comunicações MQTT 5.0. Unidade: segundos.

    • Mensagens QoS 0 aceitam valores entre 0 e 86.400 segundos.

    • Mensagens QoS 1 permitem valores de 0 a 604.800 segundos.

    TopicAlias

    Integer

    No

    123

    Alias do tópico disponível para comunicação MQTT 5.0. Esse recurso ajuda a reduzir o tráfego de dados entre os dispositivos e o IoT Platform.

    Importante

    • Os aliases funcionam através de mapeamentos entre nomes de tópicos e seus respectivos aliases, mantidos tanto pelos dispositivos quanto pelo IoT Platform. Um mapeamento surge na primeira vez que o dispositivo usa um alias para enviar mensagens e é removido ao desconectar. Sempre que o dispositivo reconecta e utiliza o tópico correspondente, um novo mapeamento é estabelecido.

    • Cada alias deve ser único e corresponder a apenas um nome de tópico.

    • Evite publicar mensagens simultaneamente ao usar aliases de tópico. Devido à arquitetura distribuída do IoT Platform, publicações concorrentes podem resultar em perda de mensagens.

    • Ao usar um alias de tópico, informe o parâmetro TopicAlias em todas as chamadas à operação Pub.

    • O IoT Platform suporta no máximo 20 aliases de tópico. Portanto, as mensagens downstream de um dispositivo podem usar até 20 aliases distintos.

    Saiba mais sobre aliases de tópico na documentação Topic aliases in MQTT 5.0 features.

    Além dos parâmetros específicos descritos acima, esta operação exige a configuração dos parâmetros comuns de solicitação. Consulte Common parameters para obter detalhes sobre esses parâmetros.

    Parâmetros de resposta

    Parameter

    Type

    Example

    Description

    Code

    String

    iot.system.SystemException

    Código de erro retornado em caso de falha na chamada. Consulte Error codes para a lista completa.

    ErrorMessage

    String

    A system exception occurred.

    Mensagem de erro exibida quando a chamada falha.

    MessageId

    String

    889455942124347329

    ID da mensagem gerado pelo IoT Platform no momento do envio.

    RequestId

    String

    BB71E443-4447-4024-A000-EDE09922891E

    ID da solicitação.

    Success

    Boolean

    true

    Indica se a chamada foi bem-sucedida. Valores válidos:

    • true

    • false

    Exemplos

    Exemplo de solicitação

    https://iot.cn-shanghai.aliyuncs.com/?Action=Pub
&ProductKey=a1Q5XoY****
&TopicFullName=/a1Q5XoY****/device1/user/get
&MessageContent=eyJ0ZXN0IjoidGFzayBwdWIgYnJvYWRjYXN0In0=
&Qos=0
&ResponseTopic=/a1Q5XoY****/device1/user/update
&CorrelationData=aGVsbG8%3D****
&UserProp.1.Key=k1&UserProp.1.Value=v1
&<Common request parameters>

    Exemplo de resposta de sucesso

    XML format

    <PubResponse>
    <RequestId>BB71E443-4447-4024-A000-EDE09922891E</RequestId>
    <Success>true</Success>
    <MessageId>889455942124347329</MessageId>
</PubResponse>

    JSON format

    {
      "RequestId":"BB71E443-4447-4024-A000-EDE09922891E",
      "Success":true,
      "MessageId":889455942124347329
  }

    Códigos de erro

    Para obter a lista completa de códigos de erro, consulte Service error codes.