Поделиться через

Руководство: Подписание и выполнение запросов с помощью Postman

В этом руководстве описано, как настроить и использовать Postman для запроса к Службам коммуникации Azure с помощью ПРОТОКОЛА HTTP. В конце этого руководства вы успешно отправляете сообщение службы коротких сообщений (SMS) с помощью служб коммуникации и Postman. Затем можно использовать Postman для изучения других API в службах коммуникации.

В этом руководстве описано, как:

  • Скачайте Postman.
  • Настройте Postman для подписывания HTTP-запросов.
  • Отправьте запрос к API SMS служб коммуникации для отправки сообщения.

Prerequisites

Скачивание и установка Postman

Postman — это настольное приложение, которое может выполнять запросы к любому HTTP API. Postman часто используется для тестирования и изучения API. В этом руководстве вы скачиваете последнюю настольную версию с сайта Postman. Postman имеет версии для Windows, Mac и Linux, поэтому скачайте версию, соответствующую вашей операционной системе.

После завершения скачивания откройте приложение. Начальный экран запрашивает вход или создание учетной записи Postman. Создание учетной записи является необязательным, и ее можно пропустить, выбрав "Пропустить" и перейти к приложению. Создание учетной записи сохраняет параметры запроса API в Postman. Затем вы можете забрать запросы на других компьютерах.

Снимок экрана: начальный экран Postman, где можно создать учетную запись или перейти непосредственно в приложение.

После создания учетной записи или пропуска шага вы увидите основной экран Postman.

Создание и настройка коллекции Postman

Postman может упорядочивать запросы различными способами. В целях этого руководства вы создадите коллекцию Postman. Чтобы выполнить эту задачу, в левой части приложения выберите "Коллекции".

Снимок экрана: главный экран Postman с выделенной вкладкой

Нажмите кнопку "Создать новую коллекцию", чтобы начать процесс создания коллекции. Откроется новая вкладка в центре Postman, где вы называете коллекцию. Здесь коллекция называется Службами коммуникации Azure.

Снимок экрана приложения Postman с открытой коллекцией Служб коммуникации и выделенным именем коллекции.

После создания и имени коллекции вы будете готовы к настройке.

Добавление переменных коллекции

Для обработки проверки подлинности и упрощения запросов необходимо указать две переменные коллекции в созданной коллекции Служб коммуникации. Эти переменные доступны для всех запросов в коллекции. Чтобы начать создание переменных, перейдите на вкладку "Переменные".

Скриншот, на котором показан Postman с вкладкой

На вкладке "Коллекции" создайте две переменные:

  • ключ. Эта переменная должна быть одним из ключей на странице ключей служб коммуникации на портале Azure. Примером является oW...A==.
  • конечная точка. Эта переменная должна быть конечной точкой служб коммуникации на странице "Ключ ". Обязательно удалите конечный слэш. Примером является https://contoso.communication.azure.com.

На вкладке "Переменные" введите эти значения в столбце "Начальное значение ". Выберите «Persist All» в правом верхнем углу. При правильной настройке панель Postman должна выглядеть примерно так, как показано на следующем рисунке.

Снимок экрана: Postman с переменными сбора служб коммуникации настроены правильно.

Дополнительные сведения о переменных см. в документации Postman.

Создание скрипта предварительного запроса

Следующим шагом является создание предварительного скрипта в Postman. Скрипт предварительного запроса выполняется перед каждым запросом в Postman. Он может изменять или модифицировать параметры запроса. Этот скрипт используется для подписывания HTTP-запросов, чтобы службы коммуникации могли авторизовать их. Дополнительные сведения о требованиях к подписи см. в нашем руководстве по проверке подлинности.

Вы создаете этот скрипт в коллекции для того, чтобы он выполнялся при любом запросе в коллекции. Для этого на вкладке "Коллекции" выберите скрипт предварительного запроса.

Снимок экрана: Postman с вкладкой

Теперь вы создадите скрипт предварительного запроса, введя его в текстовой области. Этот шаг может быть проще, если вы напишете его в полный редактор кода, например Visual Studio Code , прежде чем вставить его. В этом руководстве описаны все части процесса скрипта. Перейдите к концу, если вы хотите скопировать скрипт в Postman и начать работу. Давайте начнем писать сценарий.

Написание скрипта предварительного запроса

Первым шагом является создание строки универсального времени (UTC) и добавление ее в Date заголовок HTTP. Сохраните эту строку в переменной, чтобы использовать ее позже при подписании.

// Set the Date header to our Date as a UTC String.
const dateStr = new Date().toUTCString();
pm.request.headers.upsert({key:'Date', value: dateStr});

Затем хэшируйте тело запроса с помощью SHA 256 и поместите его в заголовок x-ms-content-sha256. Postman включает некоторые стандартные библиотеки для хэширования и подписывания глобально, поэтому вам не нужно устанавливать их или требовать их.

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

Используйте указанную ранее переменную конечной точки, чтобы определить значение заголовка узла HTTP. Заголовок Host не устанавливается до тех пор, пока не будет обработан этот скрипт.

// 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://','');

С помощью этой информации теперь можно создать строку, которую вы подписываете для HTTP-запроса. Строка состоит из нескольких ранее созданных значений.

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

Наконец, вы подписываете эту строку с помощью ключа Служб коммуникации. Затем добавьте этот ключ в запрос в заголовке 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
});

Последний скрипт предварительного запроса

Последний скрипт предварительного запроса должен выглядеть примерно так:

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

Введите или вставьте этот окончательный скрипт в текстовой области на вкладке "Скрипт предварительного запроса ".

Снимок экрана, показывающий Postman с коллекцией служб коммуникации, в которую введен скрипт предварительного запроса.

После ввода нажмите клавиши CTRL+S или нажмите кнопку "Сохранить ", чтобы сохранить сценарий в коллекции.

Снимок экрана: кнопка

Создание запроса в Postman

Теперь, когда все настроено, вы готовы создать запрос служб коммуникации в Postman. Чтобы приступить к работе, выберите знак плюса (+) рядом с коллекцией Служб коммуникации.

Снимок экрана, показывающий знак плюс (+) в Postman.

Вы создали новую вкладку для запроса в Postman, и теперь ее необходимо настроить. Вы отправляете запрос к API отправки SMS, поэтому обязательно обратитесь к документации по этому API для получения помощи. Давайте настроим запрос Postman.

Чтобы начать, задайте тип POST запроса и введите {{endpoint}}/sms?api-version=2021-03-07 в поле URL-адреса запроса. Этот URL-адрес использует ранее созданную переменную endpoint для автоматической отправки в ресурс Служб связи.

Снимок экрана: запрос Postman с типом, заданным для POST, и правильным набором URL-адресов.

На вкладке "Текст " запроса выберите необработанный элемент. В раскрывающемся списке справа выберите JSON.

Скриншот, показывающий установку тела запроса в режим raw и формат JSON.

Вы настроили запрос на отправку и получение информации в формате JSON.

В текстовой области введите текст запроса в следующем формате:

{
    "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>"
        }
    ]
}

from Для параметра необходимо получить номер телефона на портале служб коммуникации, как упоминалось ранее. Введите его без пробелов и префикса кода страны. Примером является +15555551234. Ваш message может быть чем угодно, что вы хотите отправить, но Hello from Azure Communication Services хороший пример. Значение to должно быть номером телефона, к которому у вас есть доступ, чтобы вы могли получать SMS-сообщения. Использование собственного мобильного телефона является хорошей идеей.

Сохраните этот запрос в созданной ранее коллекции служб коммуникации. Этот шаг гарантирует, что будут использованы переменные и скрипт предварительного запроса, который вы ранее создали. Нажмите кнопку "Сохранить " в правом верхнем углу области запроса.

Снимок экрана: кнопка

Диалоговое окно, которое появляется, спрашивает вас, как вы хотите назвать запрос и где вы хотите его сохранить. Вы можете назвать его как угодно, но убедитесь, что в нижней половине диалогового окна выбрана вами коллекция служб связи.

Снимок экрана: диалоговое окно

Отправка запроса

Теперь, когда все настроено, вы можете отправить запрос и получить SMS-сообщение на телефоне. Чтобы выполнить этот шаг, убедитесь, что ваш запрос выбран, а затем нажмите кнопку "Отправить".

Снимок экрана: запрос Postman с выделенной кнопкой

Если все прошло хорошо, вы увидите ответ от служб коммуникации, который является кодом состояния 202.

Снимок экрана: запрос Postman, отправленный успешно с кодом состояния 202.

Мобильный телефон с номером, указанным в значении to, также получил SMS-сообщение. Теперь у вас есть функциональная конфигурация Postman, которая может взаимодействовать со службами коммуникации и отправлять SMS-сообщения.

Связанный контент

  • Last updated on