Cette rubrique décrit la structure des requêtes, les paramètres communs, les réponses ainsi que la méthode de signature pour les appels d'API HTTP vers Simple Message Queue (SMQ, anciennement MNS).
Structure de la requête
Endpoint
Simple Message Queue (SMQ, anciennement MNS) est disponible dans plusieurs régions. Chaque région propose un endpoint public et un endpoint interne. Pour en savoir plus, consultez la rubrique Régions et endpoints.
Méthode de requête
Envoyez des requêtes à Simple Message Queue (SMQ, anciennement MNS) via HTTP en utilisant des méthodes telles que PUT, POST, GET et DELETE.
Les requêtes doivent inclure les paramètres, les en-têtes et le corps appropriés. Les requêtes et les réponses sont encodées en UTF-8.
Paramètres communs
En-têtes de requête communs
Parameter | Required | Description |
Authorization | Oui | La chaîne d'authentification. Pour en savoir plus, consultez la rubrique Méthode de signature de requête. |
Content-Length | Oui | La longueur du corps de la requête HTTP. |
Content-Type | Oui | Le type MIME du contenu de la requête. Seuls les formats texte et XML sont pris en charge. |
Content-MD5 | Non | Le hachage MD5 du corps de la requête HTTP. Pour en savoir plus, consultez The Content-MD5 Header Field. Remarque L'en-tête |
Date | Oui | L'heure de création de la requête au format GMT. Si la différence de temps entre la requête et l'heure du serveur SMQ dépasse 15 minutes, la requête est considérée comme invalide. |
Host | Requis pour HTTP/1.1. Facultatif pour HTTP/1.0. | L'endpoint de la requête. Le format est |
x-mns-version | Oui | La version de l'API SMQ à utiliser. La version actuelle est |
x-mns-date | Non | Une alternative à l'en-tête |
En-têtes de réponse communs
|**Parameter**
|
**Description**
| | --- | --- | |
Content-Length
|
La longueur du corps de la réponse HTTP.
| |
Connection
|
L'état de la connexion HTTP.
| |
Date
|
L'heure de génération de la réponse au format GMT.
| |
Server
|
Le nom du serveur SMQ qui a traité la requête.
| |
x-mns-request-id
|
Un ID unique pour la requête.
| |
x-mns-version
|
La version de l'API SMQ. La version actuelle est `2015-06-06`.
|
Réponse
Les appels d'API renvoient des données dans un format standardisé. Un code d'état HTTP compris entre 200 et 299 indique un appel réussi. Un code d'état compris entre 400 et 599 indique un échec. Les réponses réussies sont au format XML.
La réponse XML inclut les informations de réussite et les données métier spécifiques. L'exemple suivant montre la structure de base :
<?xml version="1.0" encoding="utf-8"?>
<!--Root node of the result-->
<RootNode xmlns="http://mns.aliyuncs.com/doc/v1/">
<!--Returned child node-->
</RootNode>Si un appel d'API échoue, aucune donnée de résultat n'est renvoyée. Le service renvoie plutôt un code d'état HTTP 4xx ou 5xx. Le corps de la réponse contient un code d'erreur et un message spécifiques. Il inclut également un ID de requête globalement unique (RequestId) et l'ID d'hôte (HostId) du serveur qui a traité votre requête.
Pour obtenir des informations détaillées sur les erreurs, consultez la rubrique Codes d'erreur.
Méthode de signature de requête
Présentation
Le service Simple Message Queue (SMQ, anciennement MNS) authentifie chaque requête. Chaque requête envoyée à SMQ doit inclure une signature dans son en-tête. Les SDK SMQ effectuent automatiquement le processus de signature. Nous vous recommandons d'utiliser un SDK pour envoyer des requêtes afin d'éviter le processus de signature manuel.
Le processus de signature comprend les étapes suivantes :
Étape 1 : Construire la chaîne à signer
Utilisez le pseudo-code suivant pour construire la chaîne à signer :
StringToSign = HttpMethod + "\n"
+ CONTENT-MD5 + "\n"
+ CONTENT-TYPE + "\n"
+ DATE + "\n"
+ CanonicalizedMNSHeaders
+ CanonicalizedResource;Parameter | Description |
HttpMethod | La méthode de requête HTTP en majuscules. Exemples : |
Content-Md5 | Le hachage MD5 du corps de la requête. Ce paramètre est facultatif. Si l'en-tête |
CONTENT-TYPE | Le type de contenu du corps de la requête. Si l'en-tête |
DATE | La date et l'heure de la requête.
|
CanonicalizedMNSHeaders | La concaténation de tous les en-têtes HTTP commençant par le préfixe
|
CanonicalizedResource | L'URI de la ressource HTTP demandée correspond à la partie de l'adresse de l'endpoint HTTP spécifiée dans la configuration d'abonnement, à l'exclusion du nom de domaine et du port. Par exemple, si l'adresse de l'endpoint configurée est Important Si votre système inclut une passerelle ou un autre proxy, l'URI au point de vérification peut différer de celui de votre configuration d'abonnement. Dans ce cas, vous devez utiliser l'URI de la configuration d'abonnement. |
Étape 2 : Calculer la signature
Signature = Base64( HMAC-SHA1( ${AccessSecret}, UTF-8-Encoding-Of(${StringToSign})) ) Les paramètres sont décrits ci-dessous :
|**Parameter**
|
**Description**
| | --- | --- | |
Base64
|
La méthode d'encodage Base64.
| |
HMAC-SHA1
|
L'algorithme de signature. SMQ utilise la méthode `HMAC-SHA1` définie dans [RFC 2104](https://www.ietf.org/rfc/rfc2104.txt).
| |
Secret AccessKey
|
Votre secret AccessKey. Il correspond à l'AccessKey ID utilisé dans la signature.
| |
UTF-8-Encoding-Of
|
Le format d'encodage UTF-8.
| |
StringToSign
|
La chaîne à signer construite lors de l'Étape 1 : Construire la chaîne à signer.
|
Étape 3 : Ajouter la signature à la requête
addHeader("Authorization","MNS " + ${AccessKeyId}+ ":" + ${Signature})La clé est la chaîne constante Authorization. La valeur est une chaîne construite en concaténant les variables AccessKeyId et Signature au format MNS ${accessKeyId}:${Signature}. Dans ce format, Signature est la signature personnalisée créée par Simple Message Queue (SMQ, anciennement MNS), c'est-à-dire la valeur générée lors de l'Étape 2 : Calculer la signature (Signature).
Exemples de signature
Voici un exemple de requête :
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> Voici des exemples de réponses :
Exemple 1
Le service renvoie une erreur 403 Forbidden si l'AccessKey ID fourni n'existe pas ou est inactif.
Content-Type: text/xml
Content-Length: 314
Date: Wed, 18Mar 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 authentication fail, please check your AccessID and retry.
</Message>
<RequestId>512B2A634403E52B1956****</RequestId>
<HostId>mns.cn-hangzhou.aliyuncs.com</HostId>
</Error> Exemple 2
Le service renvoie une erreur 403 Forbidden si l'en-tête Date est manquant ou présente un format invalide.
Content-Type: text/xml
Content-Length: 274
Date: Wed, 18Mar 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 Header is invalid or missing.</Message>
<RequestId>7E1A5CF258F535884403****</RequestId>
<HostId>mns.cn-hangzhou.aliyuncs.com</HostId>
</Error> Exemple 3
Les requêtes doivent parvenir au serveur Simple Message Queue (SMQ, anciennement MNS) dans un délai de 15 minutes suivant leur horodatage. Sinon, le service renvoie une erreur 408 Request Timeout.
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>
The http request you sent is expired.
</Message>
<RequestId>512B2A634403E52B1956****</RequestId>
<HostId>mns.cn-hangzhou.aliyuncs.com</HostId>
</Error>