InvokeThingService - IoT Platform: Central de Documentação do Alibaba Cloud

Invoca um serviço de dispositivo.

Observações de uso

Ao definir um serviço em um modelo TSL (Thing Specification Language), você especifica o modo de invocação. Ao invocar um serviço com esta operação, o IoT Platform utiliza o modo de chamada conforme o valor do parâmetro Identifier.

Modo síncrono: o IoT Platform envia uma solicitação RRPC (revert-remote procedure call) ao dispositivo e recebe uma resposta RRPC sincronamente. Para mais informações sobre RRPC, consulte O que é RRPC?.
Modo assíncrono: o IoT Platform envia uma solicitação RRPC ao dispositivo e recebe uma resposta RRPC assincronamente. Para mais informações sobre tópicos, consulte Propriedades, eventos e serviços do dispositivo.

Importante

Se você definir o parâmetro Checksum Type como

Verification-free

ao criar um produto, o sistema usará o modo assíncrono.

Ao receber a invocação do serviço, o dispositivo retorna uma resposta ao chamador. Configure a lógica de resposta e os parâmetros de retorno durante a configuração do dispositivo. Os formatos de dados dos parâmetros de resposta devem obedecer ao protocolo Alink. Exemplo:


{
    "id": "58***89",
    "code": 200,
    "data": {},
    "message": "success",
    "localizedMsg": "localizedMsg"
}

Nota

O parâmetro id define o identificador exclusivo da solicitação. O IoT Platform gera esse ID. O dispositivo pode obtê-lo nos parâmetros da solicitação e devolvê-lo na resposta.
O parâmetro code indica o resultado da invocação do serviço. Seu valor é um número inteiro.
O parâmetro data contém o resultado da invocação do serviço e é retornado ao chamador. Especifique os parâmetros desejados no resultado retornado. Os dados devem estar no formato JSON.
Os parâmetros message e localizedMsg são opcionais.

O Link SDK for C do IoT Platform fornece um exemplo de uso de modelo TSL. Para mais informações, consulte Invocar serviços do dispositivo.

Limites

Em invocações síncronas, o tempo limite é de 8 segundos. Se o servidor não receber uma resposta nesse período, ocorrerá um erro de tempo limite. Chamadas assíncronas não possuem limite de tempo.

Limite de QPS

Você pode invocar esta API até 500 vezes por segundo por conta.

Nota

Usuários RAM de uma conta Alibaba Cloud compartilham a cota da conta.

Depuração

O OpenAPI Explorer calcula automaticamente o valor da assinatura. Recomendamos invocar esta operação no OpenAPI Explorer para maior conveniência. A ferramenta também gera dinamicamente códigos de exemplo da operação para diferentes SDKs.

Parâmetros da solicitação

Parameter	Type	Required	Example	Description
Action	String	Yes	InvokeThingService	Operação a ser executada. Defina o valor como InvokeThingService.
Args	String	Yes	{"param1":1}	Parâmetro de entrada do serviço. O valor é uma string JSON. Exemplo: Args={"param1": 1}. Se não desejar configurar um parâmetro de entrada para o serviço, defina o valor como Args={}. Importante Se os dados do TSL forem do tipo float ou double, os valores dos parâmetros correspondentes devem conter pelo menos uma casa decimal. Exemplos: 10,0 e 11,1.
Identifier	String	Yes	Set	Identificador do serviço. Para visualizar o identifier do serviço, use um dos métodos a seguir: Faça login no IoT Platform console. Na aba Define Feature do produto ao qual o dispositivo pertence, visualize o identificador. Invoque a operação QueryThingModel e visualize o identificador nas informações do TSL retornadas. Nota Se um serviço chamado testService pertencer a um módulo personalizado chamado testFb, defina este parâmetro como testFb:testService. O módulo personalizado difere do módulo padrão.
IotInstanceId	String	No	iot_instc_pu***_c-v64********	ID da instância IoT. Visualize o ID da instância na página Overview do IoT Platform console. Importante Se sua instância tiver um ID, especifique-o neste parâmetro. Caso contrário, a chamada falhará. Se nenhuma página Overview ou ID tiver sido gerada para sua instância, não configure este parâmetro. Para mais informações, consulte Visão geral da instância.
ProductKey	String	No	a1BwAGV****	ProductKey do produto ao qual o dispositivo pertence. Importante Ao especificar um valor para este parâmetro, configure também o parâmetro DeviceName.
DeviceName	String	No	light	DeviceName do dispositivo ao qual o serviço desejado pertence. Importante Ao especificar um valor para este parâmetro, configure também o parâmetro ProductKey.
IotId	String	No	Q7uOhVRdZRRlDnTLv****00100	ID do dispositivo. Trata-se de um identificador exclusivo emitido pelo IoT Platform. Importante O parâmetro IotId especifica um GUID para o dispositivo. O valor de IotId equivale à combinação dos valores dos parâmetros ProductKey e DeviceName. Se você especificar um valor para IotId, não será necessário informar os parâmetros ProductKey e DeviceName. Caso especifique valores para IotId, ProductKey e DeviceName simultaneamente, o valor de IotId terá precedência.
Qos	Integer	No	1	Nível de qualidade de serviço (QoS) da mensagem. Valores válidos: 0 (padrão): o sistema envia a mensagem no máximo uma vez. 1: o sistema envia a mensagem pelo menos uma vez. Se nenhuma resposta PUBACK for retornada após a publicação de uma mensagem QoS 1, a mensagem será reenviada ao dispositivo quando ele se reconectar ao IoT Platform.

Além dos parâmetros específicos listados acima, configure os parâmetros comuns de solicitação ao invocar esta operação. Para mais informações, consulte Parâmetros comuns.

Parâmetros de resposta

Parameter	Type	Example	Description
Code	String	iot.system.SystemException	Código de erro retornado se a chamada falhar. Para mais informações, consulte Códigos de erro.
Data	Struct		Dados retornados se a chamada for bem-sucedida.
MessageId	String	abcabcabc1234****	ID da mensagem enviada pelo IoT Platform ao dispositivo para invocar o serviço.
Result	String	{"param1":1}	Resultado da chamada síncrona. Este parâmetro não é retornado em chamadas assíncronas.
ErrorMessage	String	A system exception occurred.	Mensagem de erro retornada se a chamada falhar.
RequestId	String	E55E50B7-40EE-4B6B-8BBE-D3ED55CCF565	ID da solicitação.
Success	Boolean	true	Indica se a chamada foi bem-sucedida. Valores válidos: true: a chamada foi bem-sucedida. No entanto, esse valor não garante a execução do serviço. Para verificar o resultado da execução, consulte os logs do dispositivo. false: a chamada falhou.

Exemplos

Exemplos de solicitações

https://iot.cn-shanghai.aliyuncs.com/?Action=InvokeThingService
&ProductKey=a1BwAGV****
&DeviceName=device1
&Identifier=service1
&Args=%7B%22param1%22%3A1%7D
&<Common request parameters>

Exemplos de respostas de sucesso

Formato XML

<InvokeThingServiceResponse>
  <Data>
        <Result>{"code":200,"data":{},"id":"100686","message":"success","version":"1.0"}</Result>
        <MessageId>abcabc123</MessageId>
  </Data>
  <RequestId>A44C818E-FA7F-4765-B1E7-01D14AE01C6A</RequestId>
  <Success>true</Success>
</InvokeThingServiceResponse>

Formato JSON

{
  "Data": {
    "Result": "{\"code\":200,\"data\":{},\"id\":\"100686\",\"message\":\"success\",\"version\":\"1.0\"}", 
    "MessageId": "abcabc123"
  }, 
  "RequestId": "A44C818E-FA7F-4765-B1E7-01D14AE01C6A", 
  "Success": true
}

Códigos de erro

Para obter uma lista de códigos de erro, consulte Códigos de erro do serviço.