Tutorial: Assine e faça pedidos com o carteiro

Artigo
02/25/2025

Neste tutorial, vamos configurar e usar o Postman para fazer uma solicitação nos Serviços de Comunicação do Azure usando HTTP. No final deste tutorial, você terá enviado com sucesso uma mensagem SMS usando os Serviços de Comunicação e o Postman. Em seguida, você poderá usar o Postman para explorar outras APIs nos Serviços de Comunicação do Azure.

Neste tutorial seremos:

Baixando Postman
Configurando o Postman para assinar solicitações HTTP
Fazer uma solicitação contra a API 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 dos Serviços de Comunicação e uma cadeia de conexão. Saiba como criar um recurso de Serviços de Comunicação.
Um número de telefone dos Serviços de Comunicação do Azure que pode enviar mensagens SMS, consulte o nosso Obter um número de telefone para obter um.

Download e instalação do Postman

Postman, é um aplicativo de desktop que é capaz de fazer solicitações de API contra qualquer API HTTP. É comumente usado para testar e explorar APIs. Vamos fazer o download da versão mais recente para desktop do site do Postman. O Postman tem versões para Windows, Mac e Linux, portanto, faça o download da versão apropriada para o seu sistema operacional. Uma vez baixado, abra o aplicativo. Ser-lhe-á apresentado um ecrã inicial, que lhe pede para iniciar sessão ou para criar uma conta Postman. Criar uma conta é opcional e pode ser ignorado clicando no link "Pular e ir para o aplicativo". Criar uma conta salvará suas configurações de solicitação de API no Postman, que pode permitir que você retome suas solicitações em outros computadores.

Tela inicial do carteiro mostrando a capacidade de criar uma conta ou pular e ir para o aplicativo.

Depois de criar uma conta ou pular a criação de uma, você verá a janela principal do Postman.

Criando e configurando uma coleção Postman

Carteiro, pode organizar pedidos de muitas maneiras. Para os fins deste tutorial. Vamos criar uma Coleção de Carteiros. Para fazer isso, selecione o botão coleções no lado esquerdo do aplicativo:

Ecrã principal do carteiro com o separador Coleções realçado.

Uma vez selecionado, clique em "Criar nova coleção", para iniciar o processo de criação da coleção. Uma nova aba será aberta na área central do Postman. Nomeie a coleção como quiser. Aqui a coleção é chamada "Serviços de Comunicação do Azure":

Carteiro com Coleção de Serviços de Comunicação aberto e o nome da coleção em destaque.

Depois que sua coleção for criada e nomeada, você estará pronto para configurá-la.

Adicionando variáveis de coleta

Para lidar com a autenticação e facilitar as solicitações, especificaremos duas variáveis de coleta dentro da coleção de Serviços de Comunicação recém-criada. Essas variáveis estão disponíveis para todas as solicitações dentro de sua coleção de Serviços de Comunicação. Para começar a criar variáveis, visite a guia Variável da coleção.

Carteiro com uma guia Variáveis da Coleção de Serviços de Comunicação.

Uma vez na guia coleção, crie duas variáveis:

key - Esta variável deve ser uma das chaves da página de chaves dos Serviços de Comunicação do Azure no portal do Azure. Por exemplo, oW...A==.
endpoint - Esta variável deve ser o ponto de extremidade dos Serviços de Comunicação do Azure na página chave. Certifique-se de remover a barra à direita. Por exemplo, https://contoso.communication.azure.com.

Insira esses valores na coluna "Valor inicial" da tela de variáveis. Uma vez inserido, pressione o botão "Persistir tudo" logo acima da tabela à direita. Quando configurado corretamente, sua tela do Postman deve ter esta aparência:

Carteiro com as variáveis de uma Coleção de Serviços de Comunicação configuradas corretamente.

Você pode aprender mais sobre variáveis lendo a documentação do Postman sobre elas.

Criando um script de pré-solicitação

O próximo passo é criar um script de pré-solicitação dentro do Postman. Um script de pré-solicitação, é um script que é executado antes de cada solicitação no Postman e pode modificar ou alterar parâmetros de solicitação em seu nome. Usaremos isso para assinar nossas solicitações HTTP para que elas possam ser autorizadas pelos Serviços de Comunicação do Azure. Para obter mais informações sobre os requisitos de assinatura, leia nosso guia sobre autenticação.

Criaremos esse script dentro da Coleção para que ele seja executado em qualquer solicitação dentro da coleção. Para fazer isso, dentro da guia de coleção, clique na subguia "Script de pré-solicitação".

Carteiro com uma subguia de script de pré-solicitação da Coleção de Serviços de Comunicação selecionada.

Nesta Subguia, você pode criar um script de pré-solicitação inserindo-o na área de texto abaixo. Pode ser mais fácil escrever isso, dentro de um editor de código completo, como o Visual Studio Code , antes de colá-lo quando concluído. Vamos passar por cada parte do script neste tutorial. Sinta-se livre para pular para o final se você quiser apenas copiá-lo para o Postman e começar. Vamos começar a escrever o roteiro.

Escrevendo o script de pré-solicitação

A primeira coisa que faremos é criar uma cadeia de caracteres UTC (Tempo Universal Coordenado) e adicioná-la ao cabeçalho HTTP "Data". Também armazenamos essa cadeia de caracteres em uma variável para usá-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, colocaremos o hash do corpo da solicitação usando SHA 256 e o colocaremos no x-ms-content-sha256 cabeçalho. O Postman inclui algumas bibliotecas padrão para hashing e assinatura globalmente, portanto, não precisamos instalá-las ou exigi-las:

// 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, usaremos nossa variável de ponto de extremidade especificada anteriormente para discernir o valor para o cabeçalho HTTP Host. Precisamos fazer isso, pois o cabeçalho Host não é definido até que este 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 esta informação criada, podemos agora criar a string, que iremos assinar para o Pedido HTTP, esta é composta por vários valores previamente criados:

// 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, precisamos assinar essa cadeia de caracteres usando nossa chave de Serviços de Comunicação e, em seguida, adicioná-la à nossa solicitação 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 ter esta aparência:

// 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
});

Insira ou cole este script final na área de texto dentro da guia Script de pré-solicitação:

Carteiro com um script de Pré-solicitação da Coleção de Serviços de Comunicação do Azure inserido.

Uma vez inserido, pressione CTRL + S ou pressione o botão salvar isso salvará o script na coleção.

Botão de script Salvar pré-solicitação do carteiro.

Criando uma solicitação no Postman

Agora que tudo está configurado, estamos prontos para criar uma solicitação de Serviços de Comunicação no Postman. Para começar, clique no ícone mais(+) ao lado da Coleção de Serviços de Comunicação:

Botão mais do carteiro.

Isso criará uma nova guia para o nosso pedido dentro do Postman. Com ele criado, precisamos configurá-lo. Faremos uma solicitação contra a API de envio de SMS, portanto, consulte a documentação dessa API para obter assistência. Vamos configurar o pedido do Postman.

Comece pela configuração, o tipo de solicitação para POST e inserindo {{endpoint}}/sms?api-version=2021-03-07 no campo URL da solicitação. Este URL utiliza a nossa variável criada endpoint anteriormente para a enviar automaticamente para o seu recurso dos Serviços de Comunicação.

Uma solicitação do Postman, com o tipo definido como POST e o URL definido corretamente.

Agora selecione a guia Corpo da solicitação e, em seguida, altere o botão de opção abaixo para "cru". À direita, há uma lista suspensa que diz "Texto", altere-o para JSON:

Definindo o corpo da solicitação como raw e JSON

Isso configurará a solicitação para enviar e receber informações em um formato JSON.

Na área de texto abaixo você precisará inserir um corpo de solicitação, ele 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", você precisará obter um número de telefone no Portal de Serviços de Comunicação do Azure, conforme mencionado anteriormente. Introduza-o sem espaços e prefixado pelo código do seu país. Por exemplo: +15555551234. Sua "mensagem" pode ser o que você gostaria de enviar, mas Hello from Azure Communication Services é um bom exemplo. O valor "para" deve ser um telefone ao qual você tenha acesso e que possa receber mensagens SMS. Usar o seu próprio telemóvel é uma boa ideia.

Uma vez inserida, precisamos salvar essa solicitação na Coleção de Serviços de Comunicação que criamos anteriormente. Isso garantirá que ele pegue as variáveis e o script de pré-solicitação que criamos anteriormente. Para isso, clique no botão "salvar" no canto superior direito da área de solicitação.

O botão Guardar para um pedido de carteiro.

Isso fará com que apareça uma janela de diálogo que pergunta a você, o que você gostaria de chamar a solicitação e onde você gostaria de 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:

A caixa de diálogo Solicitação de salvamento do Postman com a coleção Serviços de Comunicação selecionada.

Enviar um pedido

Agora que tudo está configurado, você deve ser capaz de enviar a solicitação e receber uma mensagem SMS em seu telefone. Para fazer isso, certifique-se de que sua solicitação criada esteja selecionada e, em seguida, pressione o botão "Enviar" à direita:

Um pedido de carteiro, com o botão Enviar realçado.

Se tudo correu bem, deverá agora ver a resposta dos Serviços de Comunicação, que deverá ser o código de Estado 202:

Um pedido de carteiro, enviado com sucesso com um código de status 202.

O telemóvel, que possui o número que forneceu no valor "para", também deve ter recebido uma mensagem SMS. Agora você tem uma configuração funcional do Postman que pode falar com os Serviços de Comunicação do Azure e enviar mensagens SMS.

Próximos passos

Explore as APIs dos Serviços de Comunicação do Azure Leia mais sobre Autenticação Saiba mais sobre o Postman

Você também pode querer:

Partilhar via