Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
Neste tutorial, você irá configurar e usar o Postman para fazer uma solicitação nos Serviços de Comunicação do Azure usando HTTP. Ao final deste tutorial, você enviará com êxito uma mensagem SMS usando os Serviços de Comunicação e o Postman. Você pode então usar o Postman para explorar outras APIs nos Serviços de Comunicação.
Neste tutorial, você aprenderá como:
- Faça o download do Postman.
- Configure o Postman para assinar solicitações HTTP.
- Faça uma solicitação na API de SMS dos Serviços de Comunicação para enviar uma mensagem.
Pré-requisitos
- Uma conta do Azure com uma assinatura ativa. Se você não tiver uma assinatura do Azure, poderá criar gratuitamente uma conta. A conta gratuita oferece US$ 200 em créditos Azure para você experimentar qualquer combinação de serviços.
- Um recurso e uma cadeia de conexão ativos dos Serviços de Comunicação. Se você não tiver um recurso, consulte Criar um recurso dos Serviços de Comunicação.
- Um número de telefone dos Serviços de Comunicação que possa enviar mensagens SMS. Para obter um número de telefone, consulte Obter um número de telefone.
Baixar e instalar o Postman
O Postman é um aplicativo de área de trabalho que é capaz de fazer solicitações de API para qualquer API HTTP. O Postman costuma ser usado para testar e explorar APIs. Neste tutorial, você baixará a versão mais recente da área de trabalho do site do Postman. O Postman tem versões para Windows, Mac e Linux, sendo assim, baixe a versão apropriada para seu sistema operacional.
Depois que o download for concluído, abra o aplicativo. A tela inicial pede que você entre ou crie uma conta do Postman. A criação de uma conta é opcional e você pode ignorá-la selecionando Ignorar e ir para o aplicativo. A criação de uma conta salva as configurações de solicitação de API no Postman. Então você pode pegar suas solicitações em outros computadores.
Depois de criar uma conta ou ignorar a etapa, agora você verá a tela principal do Postman.
Criar e configurar uma coleção do Postman
O Postman pode organizar solicitações de várias maneiras. Para os fins deste tutorial, você irá criar uma coleção do Postman. Para fazer essa tarefa, no lado esquerdo do aplicativo, selecione Coleções.
Selecione Criar uma nova Coleção para iniciar o processo de criação de uma coleção. Uma nova guia é aberta na área central do Postman em que você nomeia a coleção. Aqui, a coleção é chamada Serviços de Comunicação do Azure.
Depois de criar e nomear sua coleção, você estará pronto para configurá-la.
Adicionar variáveis da coleção
Para processar a autenticação e facilitar as solicitações, você irá especificar duas variáveis de coleção dentro da coleção recém-criada dos Serviços de Comunicação. Essas variáveis estão disponíveis para todas as solicitações em sua coleção. Para começar a criar variáveis, selecione a guia Variáveis.
Na guia Coleções, crie duas variáveis:
- chave: essa variável deve ser uma das chaves da página Chave dos Serviços de Comunicação no portal do Azure. Um exemplo é
oW...A==. - ponto de extremidade: essa variável deve ser seus pontos de extremidade dos Serviços de Comunicação na página Chave. Certifique-se de remover a barra à direita. Um exemplo é
https://contoso.communication.azure.com.
Na guia Variáveis, insira esses valores na coluna Valor Inicial. Selecione Persistir Tudo no canto superior direito. Quando configurado corretamente, o painel do Postman deve ser semelhante à imagem a seguir.
Para saber mais sobre variáveis, consulte a documentação do Postman.
Criar um script de pré-solicitação
A próxima etapa é criar um script de pré-solicitação no Postman. Um script de pré-solicitação é executado antes de cada solicitação no Postman. Ele pode modificar ou alterar os parâmetros da solicitação para você. Use esse script para assinar suas solicitações HTTP para que os Serviços de Comunicação possam autorizá-las. Para obter mais informações sobre requisitos de assinatura, consulte nosso guia sobre autenticação.
Crie esse script na coleção para que ele seja executado em qualquer solicitação na coleção. Para fazer essa etapa, na guia Coleções, selecione Script de pré-solicitação.
Agora você cria um script de pré-solicitação inserindo-o na área de texto. Essa etapa poderá ser mais fácil se você escrevê-la em um editor de código completo, como o Visual Studio Code, antes de colá-la. Este tutorial explica cada parte do processo de script. Pule para o final se você quiser copiar o script para o Postman e já começar. Vamos começar a escrever o script.
Escrever o script de pré-solicitação
A primeira etapa é criar uma cadeia de caracteres UTC (Tempo Universal Coordenado) e adicioná-la ao cabeçalho HTTP Date. Armazene essa cadeia de caracteres em uma variável para usá-la posteriormente 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, faça o hash do corpo da solicitação usando SHA 256 e coloque-o no cabeçalho x-ms-content-sha256. O Postman inclui algumas bibliotecas padrão para hash e assinatura global, portanto, você não precisa instalá-las ou exigi-las.
// Hash the request body by 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
});
Use a variável de ponto de extremidade especificada anteriormente para diferenciar o valor do cabeçalho de host HTTP. O cabeçalho host não é definido até que esse script seja 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 essas informações, agora você pode criar a cadeia de caracteres, que você assinará para a solicitação HTTP. A cadeia de caracteres é 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, by using various previously created values.
const stringToSign = pm.request.method + '\n' + url + '\n' + dateStr + ';' + hostStr + ';' + hashedBodyStr;
Por fim, você assina essa cadeia de caracteres usando sua chave dos Serviços de Comunicação. Em seguida, adicione essa chave à sua solicitação no cabeçalho Authorization.
// 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é-solicitação final
O script de pré-solicitação final deve ser semelhante a este exemplo:
// 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 by 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, by 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
});
Insira ou cole este script final na área de texto na guia Script de pré-solicitação.
Depois de inseri-lo, selecione Ctrl+S ou Salvar para salvar o script na coleção.
Criar uma solicitação no Postman
Agora que tudo está configurado, você está pronto para criar uma solicitação dos Serviços de Comunicação no Postman. Para começar, selecione o sinal de adição (+) ao lado da coleção dos Serviços de Comunicação.
Você criou uma nova guia para sua solicitação no Postman e agora precisa configurá-la. Faça uma solicitação na API de Envio de SMS, então, consulte a documentação dessa API para obter assistência. Vamos configurar a solicitação do Postman.
Para iniciar, defina o tipo de solicitação como POST e insira {{endpoint}}/sms?api-version=2021-03-07 no campo URL da solicitação. Essa URL usa a variável endpoint criada anteriormente para enviá-la automaticamente para seu recurso dos Serviços de Comunicação.
Na guia Corpo da solicitação, selecione bruto. Na lista suspensa à direita, selecione JSON.
Você configurou a solicitação para enviar e receber informações em um formato JSON.
Na área de texto, insira um corpo da solicitação 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 from, você precisa obter um número de telefone no portal dos Serviços de Comunicação, conforme mencionado anteriormente. Insira-o sem espaços e o prefixo do código do seu país. Um exemplo é +15555551234. Seu message pode ser o que você quiser enviar, mas Hello from Azure Communication Services é um bom exemplo. O valor to deve ser um telefone ao qual você tem acesso para que você possa receber mensagens SMS. Usar o próprio celular é uma boa ideia.
Salve essa solicitação na coleção dos Serviços de Comunicação que você criou anteriormente. Esta etapa garante que ele pegue as variáveis e o script de pré-solicitação que você criou anteriormente. Selecione Salvar no canto superior direito da área de solicitação.
A caixa de diálogo exibida pergunta como você deseja chamar a solicitação e onde deseja salvá-la. Você pode dar a ela o nome que quiser, mas certifique-se de selecionar a coleção dos Serviços de Comunicação na metade inferior da caixa de diálogo.
Enviar uma solicitação
Agora que tudo está configurado, você pode enviar a solicitação e obter uma mensagem SMS em seu telefone. Para fazer essa etapa, verifique se sua solicitação está selecionada e selecione Enviar.
Se tudo tiver dado certo, agora você verá a resposta dos Serviços de Comunicação, que será o código de status 202.
O telefone celular que possui o número fornecido no valor to também recebeu uma mensagem SMS. Agora você tem uma configuração funcional do Postman que pode se comunicar com os Serviços de Comunicação e enviar mensagens SMS.