Tutorial: Assinar e fazer pedidos com o Postman
Neste tutorial, vamos configurar e utilizar o Postman para fazer um pedido contra Azure Communication Services através de HTTP. No final deste tutorial, terá enviado com êxito uma mensagem SMS através dos Serviços de Comunicação e do Postman. Em seguida, poderá utilizar o Postman para explorar outras APIs no Azure Communication Services.
Neste tutorial, vamos:
- A transferir o Postman
- Configurar o Postman para assinar Pedidos HTTP
- Fazer um pedido à API de SMS dos Serviços de Comunicação para enviar uma mensagem.
Pré-requisitos
- Uma conta do Azure com uma subscrição ativa. Para obter detalhes, consulte Criar uma conta gratuitamente. A conta gratuita dá-lhe 200 $ em créditos do Azure para experimentar qualquer combinação de serviços.
- Um recurso ativo do Communication Services e uma cadeia de ligação. Saiba como criar um recurso do Communication Services.
- Um Azure Communication Services Número de telefone que pode enviar mensagens SMS, consulte o nosso artigo Obter um número de telefone para obter um.
Transferir e instalar o Postman
O Postman é uma aplicação de ambiente de trabalho capaz de fazer pedidos de API em qualquer API HTTP. É frequentemente utilizado para testar e explorar APIs. Vamos transferir a versão mais recente do Ambiente de Trabalho a partir do site do Postman. O Postman tem versões para Windows, Mac e Linux, pelo que pode transferir a versão adequada para o seu sistema operativo. Depois de transferida, abra a aplicação. Será apresentado um ecrã inicial, que lhe pede para iniciar sessão ou para criar uma conta do Postman. A criação de uma conta é opcional e pode ser ignorada ao clicar na ligação "Ignorar e ir para a aplicação". A criação de uma conta irá guardar as definições de pedidos da API no Postman, o que lhe pode permitir recolher os seus pedidos noutros computadores.
Assim que tiver criado uma conta ou ignorado a criação de uma, deverá agora ver a janela principal do Postman.
Criar e configurar uma coleção do Postman
O Postman pode organizar os pedidos de várias formas. Para efeitos deste tutorial. Vamos criar uma Coleção do Postman. Para tal, selecione o botão coleções no lado esquerdo da aplicação:
Uma vez selecionado, clique em "Criar nova Coleção" para iniciar o processo de criação da coleção. Será aberto um novo separador na área central do Postman. Atribua o nome que quiser à coleção. Aqui, a coleção tem o nome "Azure Communication Services":
Assim que a coleção for criada e com o nome, estará pronto para a configurar.
Adicionar variáveis de coleção
Para processar a autenticação e facilitar os pedidos, vamos especificar duas variáveis de coleção na coleção dos Serviços de Comunicação recém-criada. Estas variáveis estão disponíveis para todos os pedidos na sua coleção dos Serviços de Comunicação. Para começar a criar variáveis, visite o Separador da Variável da Coleção.
Uma vez no separador coleção, crie duas variáveis:
- key - Esta variável deve ser uma das chaves da página chave do Azure Communication Services na portal do Azure. Por exemplo,
oW...A==. - ponto final – esta variável deve ser o ponto final do Azure Communication Services a partir da página chave.
Certifique-se de que remove a barra à direita. Por exemplo,
https://contoso.communication.azure.com.
Introduza estes valores na coluna "Valor Inicial" do ecrã de variáveis. Uma vez introduzido, prima o botão "Persistir Tudo" imediatamente acima da tabela à direita. Quando configurado corretamente, o ecrã do Postman deverá ter um aspeto semelhante ao seguinte:
Pode saber mais sobre variáveis ao ler a documentação do Postman sobre as mesmas.
Criar um script de pré-pedido
O próximo passo é criar um Script de pré-pedido no Postman. Um script de pré-pedido é um script que é executado antes de cada pedido no Postman e pode modificar ou alterar parâmetros de pedido em seu nome. Vamos utilizá-lo para assinar os nossos pedidos HTTP para que possam ser autorizados por Azure Communication Services. Para obter mais informações sobre os Requisitos de assinatura, pode ler o nosso guia sobre autenticação.
Vamos criar este script na Coleção para que seja executado em qualquer pedido dentro da coleção. Para tal, no separador coleção, clique no Sub-separador "Script de Pré-pedido".
Neste Sub-Separador, pode criar um script de pré-pedido ao introduzi-lo na área de texto abaixo. Pode ser mais fácil escrever isto num editor de código completo, como o Visual Studio Code , antes de o colar quando estiver concluído. Vamos analisar cada parte do script neste tutorial. Não hesite em saltar para o fim se quiser simplesmente copiá-lo para o Postman e começar. Vamos começar a escrever o script.
Escrever o script de pré-pedido
A primeira coisa que vamos fazer é criar uma cadeia de carateres de Hora Universal Coordenada (UTC) e adicioná-lo ao Cabeçalho HTTP "Data". Também armazenamos esta cadeia numa variável para utilizá-la mais tarde ao assinar:
// Set the Date header to our Date as a UTC String.
const dateStr = new Date().toUTCString();
pm.request.headers.upsert({key:'Date', value: dateStr});
Em seguida, vamos hash do corpo do pedido com SHA 256 e colocá-lo no x-ms-content-sha256 cabeçalho. O Postman inclui algumas bibliotecas padrão para hashing e assinatura global, pelo que não precisamos de as instalar ou exigir:
// Hash the request body using SHA256 and encode it as Base64
const hashedBodyStr = CryptoJS.SHA256(pm.request.body.raw).toString(CryptoJS.enc.Base64)
// And add that to the header x-ms-content-sha256
pm.request.headers.upsert({
key:'x-ms-content-sha256',
value: hashedBodyStr
});
Agora, vamos utilizar a nossa variável de ponto final especificada anteriormente para discernir o valor do cabeçalho do Anfitrião HTTP. Temos de o fazer, uma vez que o cabeçalho anfitrião só está definido depois de este script ser processado:
// Get our previously specified endpoint variable
const endpoint = pm.variables.get('endpoint')
// Remove the https, prefix to create a suitable "Host" value
const hostStr = endpoint.replace('https://','');
Com estas informações criadas, podemos agora criar a cadeia, que iremos assinar para o Pedido HTTP, que é composta por vários valores criados anteriormente:
// This gets the part of our URL that is after the endpoint, for example in https://contoso.communication.azure.com/sms, it will get '/sms'
const url = pm.request.url.toString().replace('{{endpoint}}','');
// Construct our string which we'll sign, using various previously created values.
const stringToSign = pm.request.method + '\n' + url + '\n' + dateStr + ';' + hostStr + ';' + hashedBodyStr;
Por fim, temos de assinar esta cadeia com a nossa chave dos Serviços de Comunicação e, em seguida, adicioná-lo ao nosso pedido no Authorization cabeçalho:
// Decode our access key from previously created variables, into bytes from base64.
const key = CryptoJS.enc.Base64.parse(pm.variables.get('key'));
// Sign our previously calculated string with HMAC 256 and our key. Convert it to Base64.
const signature = CryptoJS.HmacSHA256(stringToSign, key).toString(CryptoJS.enc.Base64);
// Add our final signature in Base64 to the authorization header of the request.
pm.request.headers.upsert({
key:'Authorization',
value: "HMAC-SHA256 SignedHeaders=date;host;x-ms-content-sha256&Signature=" + signature
});
O script de pré-pedido final
O script de pré-pedido final deve ter um aspeto semelhante ao seguinte:
// Set the Date header to our Date as a UTC String.
const dateStr = new Date().toUTCString();
pm.request.headers.upsert({key:'Date', value: dateStr});
// Hash the request body using SHA256 and encode it as Base64
const hashedBodyStr = CryptoJS.SHA256(pm.request.body.raw).toString(CryptoJS.enc.Base64)
// And add that to the header x-ms-content-sha256
pm.request.headers.upsert({
key:'x-ms-content-sha256',
value: hashedBodyStr
});
// Get our previously specified endpoint variable
const endpoint = pm.variables.get('endpoint')
// Remove the https, prefix to create a suitable "Host" value
const hostStr = endpoint.replace('https://','');
// This gets the part of our URL that is after the endpoint, for example in https://contoso.communication.azure.com/sms, it will get '/sms'
const url = pm.request.url.toString().replace('{{endpoint}}','');
// Construct our string which we'll sign, using various previously created values.
const stringToSign = pm.request.method + '\n' + url + '\n' + dateStr + ';' + hostStr + ';' + hashedBodyStr;
// Decode our access key from previously created variables, into bytes from base64.
const key = CryptoJS.enc.Base64.parse(pm.variables.get('key'));
// Sign our previously calculated string with HMAC 256 and our key. Convert it to Base64.
const signature = CryptoJS.HmacSHA256(stringToSign, key).toString(CryptoJS.enc.Base64);
// Add our final signature in Base64 to the authorization header of the request.
pm.request.headers.upsert({
key:'Authorization',
value: "HMAC-SHA256 SignedHeaders=date;host;x-ms-content-sha256&Signature=" + signature
});
Introduza ou cole este script final na área de texto no Separador Script de Pré-pedido:
Depois de introduzido, prima CTRL + S ou prima o botão Guardar, isto irá guardar o script na coleção.
Criar um pedido no Postman
Agora que está tudo configurado, estamos prontos para criar um pedido dos Serviços de Comunicação no Postman. Para começar, clique no ícone de adição(+) junto à Coleção de Serviços de Comunicação:
Esta ação irá criar um novo separador para o nosso pedido no Postman. Com a criação, temos de configurá-la. Iremos fazer um pedido relativamente à API de Envio de SMS, por isso certifique-se de que consulta a documentação para esta API para obter assistência. Vamos configurar o pedido do Postman.
Comece por definir o tipo de pedido para POST e introduza {{endpoint}}/sms?api-version=2021-03-07 no campo URL do pedido. Este URL utiliza a nossa variável criada endpoint anteriormente para enviá-la automaticamente para o recurso dos Serviços de Comunicação.
Agora, selecione o separador Corpo do pedido e, em seguida, altere o botão de opção abaixo para "raw". À direita, existe uma lista pendente que diz "Texto", altere-a para JSON:
Esta ação irá configurar o pedido para enviar e receber informações num formato JSON.
Na área de texto abaixo, terá de introduzir um corpo do pedido, deve estar no seguinte formato:
{
"from":"<Your Azure Communication Services Telephone Number>",
"message":"<The message you'd like to send>",
"smsRecipients": [
{
"to":"<The number you'd like to send the message to>"
}
]
}
Para o valor "de", terá de obter um número de telefone no Portal do Azure Communication Services, conforme mencionado anteriormente. Introduza-o sem espaços e com o prefixo do seu código de país. Por exemplo: +15555551234. A sua "mensagem" pode ser o que pretende enviar, mas Hello from Azure Communication Services é um bom exemplo. O valor "para" deve ser um telemóvel ao qual tenha acesso que possa receber mensagens SMS. Utilizar o seu próprio telemóvel é uma boa ideia.
Depois de introduzido, temos de guardar este pedido na Coleção de Serviços de Comunicação que criámos anteriormente. Isto irá garantir que recolhe as variáveis e o script de pré-pedido que criámos anteriormente. Para tal, clique no botão "guardar" no canto superior direito da área de pedido.
Isto fará com que seja apresentada uma janela de caixa de diálogo que lhe pergunta, o que pretende chamar ao pedido e onde pretende guardá-lo. Pode atribuir-lhe o nome que quiser, mas certifique-se de que seleciona a sua coleção dos Serviços de Comunicação na metade inferior da caixa de diálogo:
Enviar um pedido
Agora que está tudo configurado, deve conseguir enviar o pedido e receber uma mensagem SMS no telemóvel. Para tal, certifique-se de que o pedido criado está selecionado e, em seguida, prima o botão "Enviar" à direita:
Se tudo correu bem, deverá agora ver a resposta dos Serviços de Comunicação, que deverá ser o código de Estado 202:
O Telemóvel, que detém o número que forneceu no valor "para", também deveria ter recebido uma mensagem SMS. Tem agora uma configuração funcional do Postman que pode falar com Azure Communication Services e enviar mensagens SMS.
Passos seguintes
Também poderá querer: