InvokeThingService - IoT Platform - Alibaba Cloud Documentation Center

Memanggil layanan suatu Perangkat.

Catatan penggunaan

Saat Anda mendefinisikan layanan dalam model Thing Specification Language (TSL), mode pemanggilan layanan tersebut telah ditentukan. Saat memanggil layanan menggunakan operasi ini, Platform IoT menggunakan mode panggilan berdasarkan nilai parameter Identifier.

Mode sinkron: Platform IoT mengirim permintaan reverse remote procedure call (RRPC) ke Perangkat, lalu Perangkat secara sinkron mengembalikan respons RRPC. Untuk informasi selengkapnya tentang cara menggunakan RRPC, lihat Apa itu RRPC?.
Mode asinkron: Platform IoT mengirim permintaan RRPC ke Perangkat, lalu Perangkat secara asinkron mengembalikan respons RRPC. Untuk informasi selengkapnya tentang topik, lihat Properti, event, dan layanan Perangkat.

Penting Jika Anda menetapkan parameter Checksum Type ke Verification-free saat membuat Produk, mode asinkron akan digunakan.

Saat Perangkat menerima panggilan layanan, Perangkat mengembalikan respons kepada pemanggil layanan. Saat mengonfigurasi Perangkat, Anda harus menentukan logika respons dan parameter respons. Format data parameter respons harus sesuai dengan Protokol Alink. Contoh:


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

Catatan

Parameter id menentukan pengenal unik dari permintaan. ID ini dihasilkan oleh Platform IoT. Perangkat dapat memperoleh ID dari parameter permintaan lalu mengembalikannya.
Parameter code menentukan hasil panggilan layanan. Nilai parameter ini berupa bilangan bulat.
Parameter data menentukan hasil panggilan layanan dan dikembalikan kepada pemanggil layanan. Anda dapat menentukan parameter yang ingin disertakan dalam hasil yang dikembalikan. Data harus dalam format JSON.
Parameter message dan localizedMsg bersifat opsional.
Link SDK untuk C dari Platform IoT menyediakan contoh penggunaan model TSL. Untuk informasi selengkapnya, lihat Panggil layanan Perangkat.

Batasan

Jika Anda melakukan panggilan layanan secara sinkron, periode timeout-nya adalah 8 detik. Jika server tidak menerima respons dalam waktu 8 detik, terjadi kesalahan timeout. Tidak ada batasan periode timeout untuk panggilan asinkron.

Batas QPS

Anda dapat memanggil operasi API ini hingga 500 kali per detik per akun.

Catatan Pengguna RAM dari Akun Alibaba Cloud berbagi Kuota akun tersebut.

Debugging

OpenAPI Explorer secara otomatis menghitung nilai signature. Untuk kenyamanan Anda, kami sarankan memanggil operasi ini di OpenAPI Explorer. OpenAPI Explorer secara dinamis menghasilkan contoh kode operasi ini untuk berbagai SDK.

Parameter permintaan

Parameter	Type	Wajib	Contoh	Deskripsi
Action	String	Ya	InvokeThingService	Operasi yang ingin Anda lakukan. Tetapkan nilainya ke InvokeThingService.
Args	String	Ya	{"param1":1}	Parameter input layanan. Nilainya berupa string JSON. Contoh: Args={"param1": 1}. Jika Anda tidak ingin mengonfigurasi parameter input untuk layanan, tetapkan nilainya ke Args={}. Penting Jika data TSL bertipe float atau double, nilai parameter yang sesuai dengan data TSL tersebut harus mengandung setidaknya satu tempat desimal. Contoh: 10.0 dan 11.1.
Identifier	String	Ya	Set	Pengenal layanan. Untuk melihat identifier layanan, Anda dapat menggunakan salah satu metode berikut: Masuk ke Konsol Platform IoT. Pada tab Define Feature Produk tempat Perangkat tersebut berada, lihat identifier-nya. Panggil operasi QueryThingModel dan lihat identifier dalam informasi TSL yang dikembalikan. Catatan Jika layanan bernama testService termasuk dalam modul kustom bernama testFb, Anda dapat menetapkan parameter ini ke testFb:testService. Modul kustom ini bukan modul default.
IotInstanceId	String	Tidak	iot_instc_pu***_c-v64********	ID Instans IoT. Di halaman Overview pada Konsol Platform IoT, Anda dapat melihat ID Instans tersebut. Penting Jika Instans Anda memiliki ID, Anda harus menentukan ID tersebut untuk parameter ini. Jika tidak, panggilan akan gagal. Jika halaman Overview atau ID tidak dibuat untuk Instans Anda, Anda tidak perlu mengonfigurasi parameter ini. Untuk informasi selengkapnya, lihat Ikhtisar Instans.
ProductKey	String	Tidak	a1BwAGV****	ProductKey Produk tempat Perangkat tersebut berada. Penting Jika Anda menentukan nilai untuk parameter ini, Anda harus mengonfigurasi parameter DeviceName.
DeviceName	String	Tidak	light	DeviceName Perangkat tempat layanan yang diminta berada. Penting Jika Anda menentukan nilai untuk parameter ini, Anda harus mengonfigurasi parameter ProductKey.
IotId	String	Tidak	Q7uOhVRdZRRlDnTLv****00100	ID Perangkat. ID ini merupakan pengenal unik yang dikeluarkan oleh Platform IoT untuk Perangkat tersebut. Penting Parameter IotId menentukan ID Unik Global (GUID) untuk Perangkat. Nilai parameter IotId setara dengan kombinasi nilai parameter ProductKey dan DeviceName. Jika Anda menentukan nilai untuk parameter IotId, Anda tidak perlu menentukan nilai untuk parameter ProductKey dan DeviceName. Jika Anda menentukan nilai untuk parameter IotId,ProductKey, dan DeviceName, nilai parameter IotId akan didahulukan.
Qos	Integer	Tidak	1	Tingkat quality of service (QoS) pesan. Nilai yang valid: 0 (default): Sistem mengirim pesan paling banyak sekali. 1: Sistem mengirim pesan setidaknya sekali. Jika respons PUBACK tidak dikembalikan setelah Anda memublikasikan pesan QoS 1, pesan tersebut akan dikirim ulang ke Perangkat saat Perangkat terhubung kembali ke Platform IoT.

Selain parameter permintaan khusus operasi di atas, Anda harus mengonfigurasi parameter permintaan umum saat memanggil operasi ini. Untuk informasi selengkapnya tentang parameter permintaan umum, lihat Parameter Umum.

Parameter respons

Parameter	Type	Contoh	Deskripsi
Code	String	iot.system.SystemException	Kode kesalahan yang dikembalikan jika panggilan gagal. Untuk informasi selengkapnya, lihat Kode kesalahan.
Data	Struct		Data yang dikembalikan jika panggilan berhasil.
MessageId	String	abcabcabc1234****	ID pesan. Platform IoT mengirim pesan ini ke Perangkat untuk memanggil layanan.
Result	String	{"param1":1}	Hasil panggilan sinkron. Jika Anda memanggil layanan secara asinkron, parameter ini tidak dikembalikan.
ErrorMessage	String	Terjadi kesalahan sistem.	Pesan kesalahan yang dikembalikan jika panggilan gagal.
RequestId	String	E55E50B7-40EE-4B6B-8BBE-D3ED55CCF565	ID permintaan.
Success	Boolean	true	Menunjukkan apakah panggilan berhasil. Nilai yang valid: true: Panggilan berhasil. Namun, nilai ini tidak menunjukkan bahwa layanan telah dieksekusi. Untuk memperoleh hasil eksekusi, lihat log Perangkat. false: Panggilan gagal.

Contoh

Permintaan contoh

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

Respons keberhasilan contoh

XML format

<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>

JSON format

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

Kode kesalahan

Untuk daftar kode kesalahan, lihat Kode Kesalahan Layanan.