Nota
O acesso a esta página requer autorização. Podes tentar iniciar sessão ou mudar de diretório.
O acesso a esta página requer autorização. Podes tentar mudar de diretório.
Neste tutorial, você configura e usa o Postman para fazer uma solicitação nos Serviços de Comunicação do Azure usando HTTP. No final deste tutorial, você envia com êxito uma mensagem SMS (Short Message Service) usando os Serviços de Comunicação e o Postman. Em seguida, você pode usar o Postman para explorar outras APIs nos Serviços de Comunicação.
Neste tutorial, você aprenderá a:
- Baixar Postman.
- Configure o Postman para assinar solicitações HTTP.
- Faça uma solicitação contra a API SMS dos Serviços de Comunicação para enviar uma mensagem.
Prerequisites
- Uma conta do Azure com uma subscrição ativa. Se não tiver uma subscrição do Azure, pode 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 dos Serviços de Comunicação e uma cadeia de conexão. Se 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 pode enviar mensagens SMS. Para obter um número de telefone, consulte Obter um número de telefone.
Baixe e instale o Postman
Postman é um aplicativo de desktop que é capaz de fazer solicitações de API contra qualquer API HTTP. O Postman é comumente usado para testar e explorar APIs. Neste tutorial, você baixa a versão mais recente para desktop do site do Postman. O Postman tem versões para Windows, Mac e Linux, portanto, transfira a versão apropriada para o seu sistema operativo.
Depois que o download for concluído, abra o aplicativo. O ecrã inicial pede-lhe para iniciar sessão ou criar uma conta Postman. Criar uma conta é opcional, e você pode ignorá-la selecionando Ignorar e ir para o aplicativo. Criar uma conta salva suas configurações de solicitação de API no Postman. Em seguida, você pode pegar suas solicitações em outros computadores.
Depois de criar uma conta ou pular a etapa, você verá a tela principal do Postman.
Criar e configurar uma coleção Postman
O carteiro pode organizar os pedidos de várias maneiras. Para os fins deste tutorial, você cria uma coleção 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 aba é aberta na área central do Postman onde você nomeia a coleção. Aqui, a coleção é denominada Serviços de Comunicação do Azure.
Depois de criar e nomear sua coleção, você estará pronto para configurá-la.
Adicionar variáveis de coleção
Para lidar com a autenticação e facilitar as solicitações, especifique duas variáveis de coleção na coleção dos Serviços de Comunicação recém-criada. 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:
-
key: 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==. -
endpoint: esta variável deve ser os seus pontos de extremidade dos Serviços de Comunicação na página Chave. Certifique-se de que remove 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 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
O próximo passo é 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 de 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.
Você cria esse script na coleção para que ele seja executado em qualquer solicitação na coleção. Para executar esta 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. Esta etapa pode ser mais fácil se você escrevê-lo em um editor de código completo como o Visual Studio Code antes de colá-lo. Este tutorial orienta você por cada parte do processo de script. Vá para o final se quiser copiar o script para o Postman e começar. Vamos começar a escrever o roteiro.
Escreva o script de pré-solicitação
O primeiro passo é criar uma cadeia de caracteres UTC (Tempo Universal Coordenado) e adicioná-la ao Date cabeçalho HTTP. Armazene essa cadeia de caracteres em uma variável para usá-la mais tarde quando você 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, hash o 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 a nível global, para que não seja necessário 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
});
Utilize a sua variável de endpoint especificada anteriormente para discernir o valor do cabeçalho HTTP Host. 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ê assina 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 ao seu 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é-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 selecione Salvar para salvar o script na coleção.
Criar um pedido no Postman
Agora que tudo está configurado, você está pronto para criar uma solicitação de Serviços de Comunicação no Postman. Para começar, selecione o sinal de adição (+) ao lado da coleção Serviços de Comunicação.
Você criou uma nova guia para sua solicitação no Postman, e agora você precisa configurá-la. Você faz uma solicitação contra a API de envio de SMS, portanto, consulte a documentação dessa API para obter assistência. Vamos configurar a solicitação do Postman.
Para começar, defina o tipo de solicitação como POST e insira {{endpoint}}/sms?api-version=2021-03-07 o campo URL da solicitação. Este URL usa a variável endpoint criada anteriormente para enviá-la automaticamente para o recurso de Serviços de Comunicação.
Na guia Corpo da solicitação, selecione raw. 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 de 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 from valor, você precisa obter um número de telefone no portal de Serviços de Comunicação, como mencionado anteriormente. Introduza-o sem espaços e sem um prefixo do código do seu país. Um exemplo é +15555551234. O seu message pode ser o que quiser enviar, mas Hello from Azure Communication Services é um bom exemplo. O to valor deve ser um telefone ao qual você tenha acesso para que você possa receber mensagens SMS. Usar o seu próprio telemóvel é 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 o que você deseja chamar a solicitação e onde deseja salvá-la. Você pode nomeá-lo como quiser, mas certifique-se de selecionar sua coleção de Serviços de Comunicação na metade inferior da caixa de diálogo.
Enviar um pedido
Agora que tudo está configurado, você pode enviar a solicitação e receber uma mensagem SMS no seu telefone. Para efetuar este passo, certifique-se de que o seu pedido está selecionado e, em seguida, selecione Enviar.
Se tudo correu bem, verá a resposta dos Serviços de Comunicação, que é um código de estado 202.
O telemóvel que possui o número que forneceu no to valor também recebeu uma mensagem SMS. Agora você tem uma configuração funcional do Postman que pode falar com os Serviços de Comunicação e enviar mensagens SMS.