Nota:
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
En este tutorial, configurará y usará Postman para realizar una solicitud en Azure Communication Services mediante HTTP. Al final de este tutorial, se envía correctamente un mensaje de Servicio de mensajes cortos (SMS) mediante Communication Services y Postman. Después, puede usar Postman para explorar otras API en Communication Services.
En este tutorial, aprenderá a:
- Descargue Postman.
- Configure Postman para firmar solicitudes HTTP.
- Realice una solicitud en la API de SMS de Communication Services para enviar un mensaje.
Prerequisites
- Una cuenta de Azure con una suscripción activa. Si no tiene una suscripción de Azure, puede crear una cuenta de forma gratuita. La cuenta gratuita le proporciona 200 $ en créditos de Azure para que pruebe cualquier combinación de servicios.
- Recurso activo de Communication Services y una cadena de conexión. Si no tiene un recurso, consulte Creación de un recurso de Communication Services.
- Número de teléfono de Communication Services que puede enviar mensajes SMS. Para obtener un número de teléfono, consulte Obtener un número de teléfono.
Descarga e instalación de Postman
Postman es una aplicación de escritorio capaz de realizar solicitudes de API en cualquier API HTTP. Postman se usa normalmente para probar y explorar las API. En este tutorial, descargará la versión de escritorio más reciente desde el sitio web de Postman. Postman tiene versiones para Windows, Mac y Linux, así que descargue la versión adecuada para su sistema operativo.
Una vez finalizada la descarga, abra la aplicación. La pantalla de inicio le pide que inicie sesión o cree una cuenta de Postman. La creación de una cuenta es opcional y puede omitirla seleccionando Omitir e ir a la aplicación. La creación de una cuenta guarda la configuración de la solicitud de API en Postman. A continuación, puede acceder a sus solicitudes en otros equipos.
Después de crear una cuenta u omitir el paso, verá la pantalla principal de Postman.
Creación y configuración de una colección de Postman
Postman puede organizar las solicitudes de muchas maneras. Para los fines de este tutorial, creará una colección de Postman. Para realizar esta tarea, en el lado izquierdo de la aplicación, seleccione Colecciones.
Seleccione Crear una nueva colección para iniciar el proceso de creación de una colección. Se abre una nueva pestaña en el área central de Postman donde se asigna el nombre a la colección. Aquí, la colección se denomina Azure Communication Services.
Después de crear y asignar un nombre a la colección, estará listo para configurarla.
Agregar variables de recopilación
Para controlar la autenticación y facilitar las solicitudes, especifique dos variables de recopilación dentro de la colección de Communication Services recién creada. Estas variables están disponibles para todas las solicitudes de la colección. Para empezar a crear variables, seleccione la pestaña Variables .
En la pestaña Colecciones , cree dos variables:
-
key: esta variable debe ser una de las claves de la página Clave de Communication Services en Azure Portal. Un ejemplo es
oW...A==. -
punto de conexión: esta variable debe ser el punto de conexión de Communication Services de la página Clave. Asegúrese de quitar la barra diagonal final. Un ejemplo es
https://contoso.communication.azure.com.
En la pestaña Variables , escriba estos valores en la columna Valor inicial . Seleccione Persist All en la esquina superior derecha. Cuando se configura correctamente, el panel postman debe tener un aspecto similar a la siguiente imagen.
Para más información sobre las variables, consulte la documentación de Postman.
Creación de un script de prerequest
El siguiente paso es crear un script de solicitud previa en Postman. Un script de solicitud previa se ejecuta antes de cada solicitud en Postman. Puede modificar o alterar los parámetros de solicitud por usted. Use este script para firmar las solicitudes HTTP para que Communication Services pueda autorizarlas. Para obtener más información sobre los requisitos de firma, consulte nuestra guía sobre la autenticación.
Creas este script en la colección para que se ejecute en cualquier solicitud de la colección. Para realizar este paso, en la pestaña Colecciones, seleccione Script previo a la solicitud.
Ahora puede crear un script de pre-solicitud escribiéndolo en el área de texto. Este paso puede ser más fácil si lo escribe en un editor de código completo como Visual Studio Code antes de pegarlo. Este tutorial le guía por cada parte del proceso de script. Vaya al final si desea copiar el script en Postman y empezar a trabajar. Comencemos a escribir el script.
Escribir el script de pre-solicitud
El primer paso es crear una cadena de hora universal coordinada (UTC) y agregarla al Date encabezado HTTP. Almacene esta cadena en una variable para usarla más adelante al firmar.
// Set the Date header to our Date as a UTC String.
const dateStr = new Date().toUTCString();
pm.request.headers.upsert({key:'Date', value: dateStr});
A continuación, aplica un hash al cuerpo de la solicitud mediante SHA 256 y colóquelo en el x-ms-content-sha256 encabezado. Postman incluye algunas bibliotecas estándar para el hash y la firma globalmente, por lo que no es necesario instalarlas ni requerirlas.
// 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 la variable de punto de conexión especificada anteriormente para distinguir el valor del encabezado host HTTP. El encabezado Host no se establece hasta después de procesar este script.
// 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://','');
Con esta información, ya podrá crear la cadena que firmará para la solicitud HTTP. La cadena se compone de varios valores creados 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 último, firme esta cadena mediante la clave de Communication Services. A continuación, agregue esa clave a la solicitud en el Authorization encabezado .
// 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
});
Script de prerequest final
El script de solicitud previa final debe tener un aspecto similar al de este ejemplo:
// 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
});
Escriba o pegue este script final en el área de texto de la pestaña Script de solicitud previa.
Después de escribirlo, seleccione Ctrl+S o seleccione Guardar para guardar el script en la colección.
Creación de una solicitud en Postman
Ahora que todo está configurado, está listo para crear una solicitud de Communication Services en Postman. Para empezar, seleccione el signo más (+) junto a la colección Servicios de Comunicación.
Ha creado una nueva pestaña para la solicitud en Postman y ahora debe configurarla. Realiza una solicitud a la API de envío de SMS, por lo que asegúrate de consultar la documentación de esta API para obtener ayuda. Vamos a configurar la solicitud de Postman.
Para empezar, establezca el tipo de solicitud en POST y escriba {{endpoint}}/sms?api-version=2021-03-07 en el campo de URL de la solicitud. Esta dirección URL usa la variable endpoint creada anteriormente para enviarlo automáticamente al recurso de Communication Services.
En la pestaña Cuerpo de la solicitud, seleccione raw. En la lista desplegable de la derecha, seleccione JSON.
Configuró la solicitud para enviar y recibir información en formato JSON.
En el área de texto, escriba un cuerpo de solicitud con el formato siguiente:
{
"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 el valor de from, deberá obtener un número de teléfono en el portal de Communication Services, tal y como se mencionó anteriormente. Escríbalo sin espacios y con el prefijo de tu código de país. Un ejemplo es +15555551234. Tu message puede ser lo que desees enviar, pero Hello from Azure Communication Services es un buen ejemplo. El to valor debe ser un teléfono al que tiene acceso para poder recibir mensajes SMS. Usar su propio teléfono móvil es una buena idea.
Guarde esta solicitud en la colección Servicios de Comunicación que creó anteriormente. Este paso garantiza que recoja las variables y el script de solicitud previa que creó anteriormente. Seleccione Guardar en la esquina superior derecha del área de solicitud.
El cuadro de diálogo que aparece le pregunta cómo quiere nombrar la solicitud y dónde desea guardarla. Puede asignarle el nombre que quiera, pero asegúrese de seleccionar la colección de Communication Services en la mitad inferior del cuadro de diálogo.
Enviar una solicitud
Ahora que todo está configurado, puede enviar la solicitud y obtener un mensaje SMS en su teléfono. Para realizar este paso, asegúrese de que la solicitud está seleccionada y, a continuación, seleccione Enviar.
Si todo salió bien, verá la respuesta de Communication Services, que es un código de estado 202.
El teléfono móvil que posee el número proporcionado en el to valor también recibió un mensaje SMS. Ahora tiene una configuración funcional de Postman que puede comunicarse con Communication Services y enviar mensajes SMS.