Simple Message Queue (旧称:MNS)、略して SMQ は、HTTP ベースの API リクエストを使用します。このトピックでは、リクエスト構文、共通ヘッダー、応答フォーマット、およびリクエスト署名について説明します。
SMQ SDK はリクエスト署名を自動的に処理します。手動で生の HTTP リクエストを構築する必要がない限り、SDK を使用してください。
リクエスト構文
リージョンとエンドポイント
SMQ は複数のリージョンで利用可能です。各リージョンは、パブリックエンドポイントと内部エンドポイントを提供します。詳細については、「リージョンとエンドポイント」をご参照ください。
リクエストメソッド
SMQ は HTTP 経由で PUT、POST、GET、および DELETE をサポートしています。リクエストパラメーター、リクエストヘッダー、およびリクエストボディが有効であることを確認してください。すべてのリクエストと応答は UTF-8 エンコーディングを使用します。
共通パラメーター
共通リクエストヘッダー
| ヘッダー | 必須 | 説明 |
|---|---|---|
| Authorization | はい | 認証文字列。詳細については、「リクエストの署名」をご参照ください。 |
| Content-Length | はい | リクエストボディのバイトサイズ。 |
| Content-Type | はい | リクエストボディの MIME タイプ。有効な値: text および xml。 |
| Content-MD5 | いいえ | リクエストボディの MD5 ハッシュ。詳細については、「RFC 1864」をご参照ください。 |
| Date | はい | GMT でのリクエストタイムスタンプ。SMQ は 15 分以上前のリクエストを拒否します。 |
| Host | HTTP/1.1 では必須、HTTP/1.0 ではオプション | SMQ サーバー。形式: $AccountId.mns.cn-hangzhou.aliyuncs.com。 $AccountId をご利用の Alibaba Cloud アカウント ID に置き換えます。これは Alibaba Cloud コンソールで確認できます。 |
| x-mns-version | はい | API バージョン。現在のバージョン: 2015-06-06。 |
| x-mns-date | いいえ | クライアントが Date ヘッダーをサポートしていない場合に Date ヘッダーを置き換えます。 |
共通レスポンスヘッダー
| ヘッダー | 説明 |
|---|---|
| Content-Length | 応答ボディのバイトサイズ。 |
| Connection | HTTP 接続ステータス。 |
| Date | GMT でのレスポンスタイムスタンプ。 |
| Server | SMQ サーバー名。 |
| x-mns-request-id | 一意のリクエスト ID。サポートチケットを開く際にこの値を含めます。 |
| x-mns-version | API バージョン。現在のバージョン: 2015-06-06。 |
応答フォーマット
HTTP 2xx 状態コードは成功を示します。HTTP 4xx および 5xx 状態コードは失敗を示します。成功応答は XML を使用します。
<?xml version="1.0" encoding="utf-8"?>
<RootElement xmlns="http://mns.aliyuncs.com/doc/v1/">
<!-- 応答データ -->
</RootElement>エラー応答も XML を使用し、エラーコード、エラーメッセージ、リクエスト ID、およびホスト ID を含みます。リクエスト ID はグローバルに一意です。
<?xml version="1.0" encoding="utf-8"?>
<Error xmlns="http://mns.aliyuncs.com/doc/v1/">
<Code>ErrorCode</Code>
<Message>詳細なエラーメッセージ。</Message>
<RequestId>リクエスト ID</RequestId>
<HostId>ホスト ID</HostId>
</Error>エラーコードの完全なリストについては、「エラーコード」をご参照ください。
リクエスト署名メソッド
SMQ は、Authorization ヘッダー内の署名を通じてすべての API リクエストを認証します。署名プロセスには 3 つのステップがあります。
署名対象文字列の構築 -- HTTP メソッド、ヘッダー、およびリソースパスを正規文字列に組み立てます。
署名の計算 -- HMAC-SHA1 を使用して、ご利用の AccessKey Secret で署名対象文字列をハッシュ化し、結果を Base64 エンコードします。
リクエストへの署名追加 -- Authorization ヘッダーを
MNS <AccessKey ID>:<Signature>に設定します。
ステップ 1: 署名対象文字列の構築
以下の値を改行文字 (\n) で連結して StringToSign を構築します。
StringToSign = HttpMethod + "\n"
+ CONTENT-MD5 + "\n"
+ CONTENT-TYPE + "\n"
+ DATE + "\n"
+ CanonicalizedMNSHeaders
+ CanonicalizedResource| コンポーネント | 説明 |
|---|---|
| HttpMethod | 大文字の HTTP メソッド: PUT、GET、POST、または DELETE。 |
| CONTENT-MD5 | リクエストボディの MD5 ハッシュ。Content-MD5 ヘッダーが設定されていない場合は空白のままにします。 |
| CONTENT-TYPE | リクエストボディの MIME タイプ。Content-Type ヘッダーが設定されていない場合は空白のままにします。 |
| DATE | GMT でのリクエストタイムスタンプ。例: Thu, 07 Mar 2012 18:49:58 GMT。Date ヘッダーの代わりに x-mns-date ヘッダーを使用する場合は、その値をここに指定します。タイムスタンプが 15 分以上古い場合、SMQ はエラーコード 400 を返します。詳細については、「エラーコード」をご参照ください。 |
| CanonicalizedMNSHeaders | x-mns- で始まるすべての HTTP ヘッダーは、次のように処理されます: ヘッダー名を小文字に変換し、アルファベット順にソートし、各ヘッダーを <name>:<value>\n の形式で連結します。 |
| CanonicalizedResource | ドメインとポートが削除された、リクエストされたリソースの URI。例: http://123.123.XX.XX:8080/api/test?code=200 は /api/test?code=200 を生成し、http://www.aliyun.com/mns/help は /mns/help を生成します。 |
CanonicalizedMNSHeaders 構築例 (Java):
// すべてのリクエストヘッダーを取得
Map<String, String> httpHeaders = request.getHeaders();
// ヘッダーをソートして名前を小文字に変換
sortHeadersKeyAndToLowerCase(httpHeaders);
// 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");
}
}システムにゲートウェイまたはその他の中継プロキシが存在する場合、中間ゲートウェイによって認識される URI ではなく、CanonicalizedResource には元の HTTP リクエストの URI を使用してください。
ステップ 2: 署名の計算
UTF-8 エンコードされた StringToSign に HMAC-SHA1 (RFC 2104) を適用し、ご利用の AccessKey Secret をキーとして使用します。次に、結果を Base64 エンコードします。
Signature = Base64( HMAC-SHA1( AccessSecret, UTF-8-Encoding-Of(StringToSign) ) )| コンポーネント | 説明 |
|---|---|
| Base64 | Base64 エンコーディング。 |
| HMAC-SHA1 | RFC 2104 で定義されている HMAC-SHA1 アルゴリズム。 |
| AccessSecret | Authorization ヘッダー内の AccessKey ID に対応する AccessKey Secret。 |
| StringToSign | ステップ 1 で構築された文字列。 |
ステップ 3: リクエストへの署名追加
Authorization ヘッダーを設定します。
Authorization: MNS <AccessKey ID>:<Signature>例:
Authorization: MNS 15B4D3461F177624****:xQE0diMbL****f3YB+FIEXAMPLE=言語別の署名例
以下の例は、SMQ リクエストの Authorization ヘッダー値を生成する方法を示しています。
署名例
以下の例は、完全な署名済みリクエストと一般的なエラー応答を示しています。
リクエスト例
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>エラー応答
以下の表は、一般的な認証関連のエラーを要約しています。
| シナリオ | HTTP ステータス | エラーコード |
|---|---|---|
| AccessKey ID が存在しないか、無効になっています | 403 | AccessIDAuthError |
| Date ヘッダーが見つからないか、無効です | 403 | InvalidArgument |
| リクエストがタイムスタンプから 15 分以上経過して到着しました | 408 | TimeExpired |
例 1
403 AccessIDAuthError -- AccessKey ID が存在しないか、無効になっています。
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>
AccessID 認証に失敗しました。AccessID を確認して再試行してください。
</Message>
<RequestId>512B2A634403E52B1956****</RequestId>
<HostId>mns.cn-hangzhou.aliyuncs.com</HostId>
</Error>例 2
403 InvalidArgument -- Date ヘッダーが見つからないか、無効です。
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>Date ヘッダーが無効であるか、見つかりません。</Message>
<RequestId>7E1A5CF258F535884403****</RequestId>
<HostId>mns.cn-hangzhou.aliyuncs.com</HostId>
</Error>例 3
408 TimeExpired -- リクエストがタイムスタンプから 15 分以上経過して到着しました。
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>
送信した HTTP リクエストの有効期限が切れています。
</Message>
<RequestId>512B2A634403E52B1956****</RequestId>
<HostId>mns.cn-hangzhou.aliyuncs.com</HostId>
</Error>