Este documento descreve a estrutura da solicitação, os parâmetros comuns, a resposta e o método de assinatura de requisição para chamadas de API HTTP do Simple Message Queue (SMQ, anteriormente MNS).
Estrutura da solicitação
Endpoint
O Simple Message Queue (SMQ, anteriormente MNS) está disponível em várias regiões. Cada região fornece um endpoint público e um endpoint interno. Para obter mais informações, consulte Regiões e endpoints.
Método de solicitação
Envie solicitações ao Simple Message Queue (SMQ, anteriormente MNS) por http utilizando métodos como PUT, POST, GET e DELETE.
As solicitações devem incluir os parâmetros, cabeçalhos e corpo corretos. Tanto as solicitações quanto as respostas são codificadas em UTF-8.
Parâmetros comuns
Cabeçalhos de solicitação comuns
Parâmetro | Obrigatório | Descrição |
Authorization | Sim | A string de autenticação. Para obter mais informações, consulte Método de assinatura da solicitação. |
Content-Length | Sim | O tamanho do corpo da solicitação http. |
Content-Type | Sim | O tipo MIME do conteúdo da solicitação. Atualmente, apenas os formatos texto e XML são suportados. |
Content-MD5 | Não | O hash MD5 do corpo da solicitação http. Para obter mais informações, consulte The Content-MD5 Header Field. Nota O cabeçalho |
Date | Sim | O momento em que a solicitação foi criada. O horário deve estar no formato GMT. Se a diferença de tempo entre a solicitação e o horário do servidor SMQ exceder 15 minutos, a solicitação será considerada inválida. |
Host | Obrigatório para http/1.1. Opcional para http/1.0. | O endpoint da solicitação. O formato é |
x-mns-version | Sim | A versão da API do SMQ a ser utilizada. A versão atual é |
x-mns-date | Não | Uma alternativa ao cabeçalho |
Cabeçalhos de resposta comuns
|
Parâmetro |
Descrição |
|
Content-Length |
O tamanho do corpo da resposta http. |
|
Connection |
O status da conexão http. |
|
Date |
O horário em que a resposta foi gerada, no formato GMT. |
|
Server |
O nome do servidor SMQ que processou a solicitação. |
|
x-mns-request-id |
Um id exclusivo para a solicitação. |
|
x-mns-version |
A versão da API do SMQ. A versão atual é |
Resposta
As chamadas de API retornam dados em um formato padronizado. Um código de status http na faixa 2xx indica uma chamada bem-sucedida. Um código de status na faixa 4xx ou 5xx indica falha. As respostas bem-sucedidas estão no formato XML.
A resposta XML inclui informações de sucesso e dados específicos do negócio. O exemplo a seguir mostra a estrutura básica:
<?xml version="1.0" encoding="utf-8"?>
<!--Root node of the result-->
<RootNode xmlns="http://mns.aliyuncs.com/doc/v1/">
<!--Returned child node-->
</RootNode>Se uma chamada de API falhar, nenhum dado de resultado será retornado. Em vez disso, o serviço retorna um código de status http 4xx ou 5xx. O corpo da resposta contém um código de erro e uma mensagem específicos. Ele também inclui um id de solicitação globalmente exclusivo (RequestId) e o id do host (HostId) do servidor que processou sua solicitação.
Para obter informações detalhadas sobre erros, consulte Códigos de erro.
Método de assinatura da solicitação
Visão geral
O serviço Simple Message Queue (SMQ, anteriormente MNS) autentica todas as solicitações. Cada solicitação enviada ao SMQ deve incluir uma assinatura em seu cabeçalho. Os SDKs do SMQ concluem automaticamente o processo de assinatura. Recomendamos o uso de um SDK para enviar solicitações e evitar o processo manual de assinatura.
O processo de assinatura consiste nas seguintes etapas:
Etapa 1: Construir a string a ser assinada
Utilize o seguinte pseudocódigo para construir a string a ser assinada:
StringToSign = HttpMethod + "\n"
+ CONTENT-MD5 + "\n"
+ CONTENT-TYPE + "\n"
+ DATE + "\n"
+ CanonicalizedMNSHeaders
+ CanonicalizedResource;Parâmetro | Descrição |
HttpMethod | O método de solicitação http em letras maiúsculas. Exemplos: |
Content-Md5 | O hash MD5 do corpo da solicitação. Este campo é opcional. Se o cabeçalho |
CONTENT-TYPE | O tipo de conteúdo do corpo da solicitação. Se o cabeçalho |
DATE | A data e a hora da solicitação.
|
CanonicalizedMNSHeaders | A concatenação de todos os cabeçalhos http que começam com o prefixo
|
CanonicalizedResource | A URI do recurso solicitado via http corresponde à parte do endereço do endpoint http especificada na configuração da assinatura, excluindo o nome de domínio e a porta. Por exemplo, se o endereço do endpoint configurado for Importante Se o seu sistema incluir um gateway ou outro proxy, a URI no ponto de verificação poderá diferir daquela presente na configuração da assinatura. Nesse caso, utilize a URI da configuração da assinatura. |
Etapa 2: Calcular a assinatura
Signature = Base64( HMAC-SHA1( ${AccessSecret}, UTF-8-Encoding-Of(${StringToSign})) ) Os parâmetros são descritos da seguinte forma:
|
Parâmetro |
Descrição |
|
Base64 |
O método de codificação Base64. |
|
HMAC-SHA1 |
O algoritmo de assinatura. O SMQ utiliza o método |
|
AccessKey secret |
Seu AccessKey secret. Ele corresponde ao AccessKey ID utilizado na assinatura. |
|
UTF-8-Encoding-Of |
O formato de codificação UTF-8. |
|
StringToSign |
A string a ser assinada construída na Etapa 1: Construir a string a ser assinada. |
Etapa 3: Adicionar a assinatura à solicitação
addHeader("Authorization","MNS " + ${AccessKeyId}+ ":" + ${Signature})A chave é a string constante Authorization. O valor é uma string construída pela concatenação das variáveis AccessKeyId e Signature no formato MNS ${accessKeyId}:${Signature}. Neste formato, Signature representa a assinatura personalizada do Simple Message Queue (SMQ, anteriormente MNS), que corresponde ao valor gerado na Etapa 2: Calcular a assinatura (Signature).
Exemplos de assinatura
A seguir, um exemplo de solicitação:
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> A seguir, exemplos de respostas:
Exemplo 1
O serviço retorna um erro 403 Forbidden se o AccessKey ID fornecido não existir ou estiver inativo.
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> Exemplo 2
O serviço retorna um erro 403 Forbidden se o cabeçalho Date estiver ausente ou tiver um formato inválido.
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> Exemplo 3
As solicitações devem chegar ao servidor do Simple Message Queue (SMQ, anteriormente MNS) dentro de 15 minutos após o timestamp. Caso contrário, o serviço retorna um erro 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>