Simple Message Queue (formerly MNS), atau SMQ, menggunakan permintaan API berbasis HTTP. Topik ini mencakup sintaksis permintaan, header umum, format respons, dan penandatanganan permintaan.
SDK SMQ menangani penandatanganan permintaan secara otomatis. Gunakan SDK kecuali Anda perlu membuat permintaan HTTP mentah secara manual.
Sintaksis permintaan
Wilayah dan titik akhir
SMQ tersedia di beberapa wilayah. Setiap wilayah menyediakan titik akhir publik dan titik akhir internal. Untuk detailnya, lihat Wilayah dan titik akhir.
Metode permintaan
SMQ mendukung metode HTTP PUT, POST, GET, dan DELETE. Pastikan parameter permintaan, header permintaan, dan badan permintaan valid. Semua permintaan dan respons menggunakan pengkodean UTF-8.
Parameter umum
Header permintaan umum
| Header | Wajib | Deskripsi |
|---|---|---|
| Authorization | Ya | String autentikasi. Lihat Tandatangani permintaan. |
| Content-Length | Ya | Ukuran badan permintaan dalam byte. |
| Content-Type | Ya | Jenis MIME dari badan permintaan. Nilai yang valid: text dan xml. |
| Content-MD5 | Tidak | Hash MD5 dari badan permintaan. Lihat RFC 1864. |
| Date | Ya | Stempel waktu permintaan dalam GMT. SMQ menolak permintaan yang lebih dari 15 menit lalu. |
| Host | Wajib untuk HTTP/1.1, opsional untuk HTTP/1.0 | Server SMQ. Format: $AccountId.mns.cn-hangzhou.aliyuncs.com. Ganti $AccountId dengan ID akun Alibaba Cloud Anda, yang tersedia di Alibaba Cloud console. |
| x-mns-version | Ya | Versi API. Versi saat ini: 2015-06-06. |
| x-mns-date | Tidak | Menggantikan header Date ketika client tidak mendukung Date. |
Header respons umum
| Header | Deskripsi |
|---|---|
| Content-Length | Ukuran badan respons dalam byte. |
| Connection | Status koneksi HTTP. |
| Date | Stempel waktu respons dalam GMT. |
| Server | Nama server SMQ. |
| x-mns-request-id | ID permintaan unik. Sertakan nilai ini saat Anda membuka tiket dukungan. |
| x-mns-version | Versi API. Versi saat ini: 2015-06-06. |
Format respons
Kode status HTTP 2xx menunjukkan keberhasilan, sedangkan kode status HTTP 4xx dan 5xx menunjukkan kegagalan. Respons sukses menggunakan format XML:
<?xml version="1.0" encoding="utf-8"?>
<RootElement xmlns="http://mns.aliyuncs.com/doc/v1/">
<!-- Data respons -->
</RootElement>Respons kesalahan juga menggunakan XML dan mencakup kode kesalahan, pesan kesalahan, ID permintaan, serta ID host. ID permintaan bersifat unik secara global.
<?xml version="1.0" encoding="utf-8"?>
<Error xmlns="http://mns.aliyuncs.com/doc/v1/">
<Code>ErrorCode</Code>
<Message>Pesan kesalahan deskriptif.</Message>
<RequestId>Request ID</RequestId>
<HostId>Host ID</HostId>
</Error>Untuk daftar lengkap kode kesalahan, lihat Kode kesalahan.
Metode penandatanganan permintaan
SMQ mengautentikasi setiap permintaan API melalui signature dalam header Authorization. Proses penandatanganan terdiri dari tiga langkah:
Buat string-to-sign — Susun metode HTTP, header, dan jalur resource menjadi string kanonikal.
Hitung signature — Hash string-to-sign dengan rahasia AccessKey Anda menggunakan HMAC-SHA1, lalu encode hasilnya dengan Base64.
Tambahkan signature ke permintaan — Atur header Authorization menjadi
MNS <AccessKey ID>:<Signature>.
Langkah 1: Buat string-to-sign
Buat StringToSign dengan menggabungkan nilai-nilai berikut, dipisahkan oleh karakter baris baru (\n):
StringToSign = HttpMethod + "\n"
+ CONTENT-MD5 + "\n"
+ CONTENT-TYPE + "\n"
+ DATE + "\n"
+ CanonicalizedMNSHeaders
+ CanonicalizedResource| Komponen | Deskripsi |
|---|---|
| HttpMethod | Metode HTTP dalam huruf kapital: PUT, GET, POST, atau DELETE. |
| CONTENT-MD5 | Hash MD5 dari badan permintaan. Biarkan kosong jika header Content-MD5 tidak diatur. |
| CONTENT-TYPE | Jenis MIME dari badan permintaan. Biarkan kosong jika header Content-Type tidak diatur. |
| DATE | Stempel waktu permintaan dalam GMT. Contoh: Thu, 07 Mar 2012 18:49:58 GMT. Jika Anda menggunakan header x-mns-date sebagai pengganti Date, gunakan nilai tersebut di sini. SMQ mengembalikan kode kesalahan 400 jika stempel waktu lebih dari 15 menit lalu. Lihat Kode kesalahan. |
| CanonicalizedMNSHeaders | Semua header HTTP yang diawali dengan x-mns-, diproses sebagai berikut: ubah nama header menjadi huruf kecil, urutkan secara alfabetis, lalu gabungkan setiap header sebagai <name>:<value>\n. |
| CanonicalizedResource | URI dari resource yang diminta, dengan domain dan port dihapus. Misalnya, http://123.123.XX.XX:8080/api/test?code=200 menghasilkan /api/test?code=200, dan http://www.aliyun.com/mns/help menghasilkan /mns/help. |
Contoh pembuatan CanonicalizedMNSHeaders (Java):
// Dapatkan semua header permintaan
Map<String, String> httpHeaders = request.getHeaders();
// Urutkan header dan ubah nama menjadi huruf kecil
sortHeadersKeyAndToLowerCase(httpHeaders);
// Gabungkan header x-mns-*
Set<String> keySet = httpHeaders.keySet();
for (String key : keySet) {
if (key.startsWith("x-mns-")) {
CanonicalizedMNSHeaders.append(key).append(":")
.append(httpHeaders.get(key)).append("\n");
}
}Jika terdapat gerbang atau proxy transit lain dalam sistem Anda, gunakan URI dari permintaan HTTP asli untuk CanonicalizedResource, bukan URI yang dilihat oleh gerbang perantara.
Langkah 2: Hitung signature
Terapkan HMAC-SHA1 (RFC 2104) pada StringToSign yang telah diencode UTF-8, menggunakan rahasia AccessKey Anda sebagai kunci. Kemudian encode hasilnya dengan Base64:
Signature = Base64( HMAC-SHA1( AccessSecret, UTF-8-Encoding-Of(StringToSign) ) )| Komponen | Deskripsi |
|---|---|
| Base64 | Pengkodean Base64. |
| HMAC-SHA1 | Algoritma HMAC-SHA1 yang didefinisikan dalam RFC 2104. |
| AccessSecret | Rahasia AccessKey yang sesuai dengan ID AccessKey dalam header Authorization. |
| StringToSign | String yang dibuat pada Langkah 1. |
Langkah 3: Tambahkan signature ke permintaan
Atur header Authorization:
Authorization: MNS <AccessKey ID>:<Signature>Contoh:
Authorization: MNS 15B4D3461F177624****:xQE0diMbL****f3YB+FIEXAMPLE=Contoh penandatanganan berdasarkan bahasa
Contoh berikut menunjukkan cara menghasilkan nilai header Authorization untuk permintaan SMQ.
Contoh penandatanganan
Contoh berikut menunjukkan permintaan bertanda tangan lengkap dan respons kesalahan umum.
Permintaan contoh
PUT /queues/$queueName?metaOverride=true HTTP/1.1
Host: $AccountId.mns.cn-hangzhou.aliyuncs.com
Date: Wed, 08 Mar 2012 12:00:00 GMT
Authorization: MNS 15B4D3461F177624****:xQE0diMbL****f3YB+FIEXAMPLE=
<?xml version="1.0" encoding="UTF-8"?>
<Queue xmlns="http://mns.aliyuncs.com/doc/v1/">
<VisibilityTimeout>60</VisibilityTimeout>
<MaximumMessageSize>1024</MaximumMessageSize>
<MessageRetentionPeriod>120</MessageRetentionPeriod>
<DelaySeconds>30</DelaySeconds>
</Queue>Respons kesalahan
Tabel berikut merangkum kesalahan umum terkait autentikasi.
| Skenario | Status HTTP | Kode kesalahan |
|---|---|---|
| ID AccessKey tidak ada atau dinonaktifkan | 403 | AccessIDAuthError |
| Header Date tidak ada atau tidak valid | 403 | InvalidArgument |
| Permintaan tiba lebih dari 15 menit setelah stempel waktu | 408 | TimeExpired |
Contoh 1
403 AccessIDAuthError — ID AccessKey tidak ada atau dinonaktifkan:
Content-Type: text/xml
Content-Length: 314
Date: Wed, 18 Mar 2012 08:04:06 GMT
x-mns-request-id: 512B2A634403E52B1956****
<?xml version="1.0" encoding="utf-8"?>
<Error xmlns="http://mns.aliyuncs.com/doc/v1/">
<Code>AccessIDAuthError</Code>
<Message>
Autentikasi AccessID gagal, harap periksa AccessID Anda dan coba lagi.
</Message>
<RequestId>512B2A634403E52B1956****</RequestId>
<HostId>mns.cn-hangzhou.aliyuncs.com</HostId>
</Error>Contoh 2
403 InvalidArgument — Header Date tidak ada atau tidak valid:
Content-Type: text/xml
Content-Length: 274
Date: Wed, 18 Mar 2012 08:04:06 GMT
x-mns-request-id: 512B2A634403E52B1956****
<?xml version="1.0" encoding="UTF-8"?>
<Error xmlns="http://mns.aliyuncs.com/doc/v1/">
<Code>InvalidArgument</Code>
<Message>Header Date tidak valid atau tidak ada.</Message>
<RequestId>7E1A5CF258F535884403****</RequestId>
<HostId>mns.cn-hangzhou.aliyuncs.com</HostId>
</Error>Contoh 3
408 TimeExpired — Permintaan tiba lebih dari 15 menit setelah stempel waktu:
Content-Type: text/xml
Content-Length: 283
Date: Wed, 11 May 2011 09:01:51 GMT
x-mns-request-id: 512B2A634403E52B1956****
<?xml version="1.0" encoding="UTF-8"?>
<Error xmlns="http://mns.aliyuncs.com/doc/v1/">
<Code>TimeExpired</Code>
<Message>
Permintaan HTTP yang Anda kirim telah kedaluwarsa.
</Message>
<RequestId>512B2A634403E52B1956****</RequestId>
<HostId>mns.cn-hangzhou.aliyuncs.com</HostId>
</Error>