Отправка запросов в API Azure Digital Twins с помощью Postman

  • Статья

Postman — это средство тестирования REST, предоставляющее основные возможности HTTP-запросов в пользовательском интерфейсе для классических программ и на основе подключаемых модулей. Его можно использовать для создания HTTP-запросов и их отправки в API REST Azure Digital Twins. В этой статье описывается, как настроить rest-клиент Postman для взаимодействия с API Azure Digital Twins. Эти сведения относятся к службе Azure Digital Twins.

В этой статье содержатся сведения о следующих шагах:

  1. Используйте Azure CLI, чтобы получить маркер носителя, который будет использоваться для выполнения запросов API в Postman.
  2. Настройте коллекцию Postman и настройте клиент REST Postman на использование маркера носителя для проверки подлинности. При настройке коллекции можно выбрать один из следующих вариантов:
    1. Импортируйте предварительно созданную коллекцию запросов API Azure Digital Twins.
    2. Создайте собственную коллекцию с нуля.
  3. Добавьте запросы в настроенную коллекцию и отправьте их в интерфейсы API Azure Digital Twins.

В Azure Digital Twins есть два набора интерфейсов API, с которыми вы можете работать: плоскость данных и плоскость управления. Дополнительные сведения о различиях между этими наборами API см. в статье API и пакеты SDK для Azure Digital Twins. Эта статья содержит сведения для обоих наборов API.

Необходимые компоненты

Чтобы продолжить использовать Postman для доступа к API-интерфейсам Azure Digital Twins, необходимо настроить экземпляр Azure Digital Twins и скачать Postman. Соответствующие действия описаны далее в разделе.

Настройка экземпляра Azure Digital Twins

Для работы с Azure Digital Twins в этой статье потребуется экземпляр Azure Digital Twins и необходимые разрешения для его использования. Если у вас уже настроен экземпляр Azure Digital Twins, этот экземпляр можно использовать и перейти к следующему разделу. В противном случае выполните инструкции по настройке экземпляра и аутентификации. В инструкциях приводится информация, которая поможет вам убедиться, что вы успешно выполнили каждый шаг.

После настройки экземпляра запишите имя узла экземпляра. Вы можете найти имя хоста на портале Azure.

Скачивание файлов Postman

Затем скачайте настольную версию клиента Postman.

Получение маркера носителя.

Теперь, когда вы настроили Postman и свой экземпляр Azure Digital Twins, вам потребуется получить маркер носителя, направляющий запросы, которые можно использовать для авторизации в API Azure Digital Twins.

Получить этот маркер можно несколькими способами. В этой статье используется Azure CLI для входа в учетную запись Azure и получения маркера.

Если компонент Azure CLI установлен локально, вы можете запустить командную строку на компьютере, чтобы выполнить указанные ниже команды. В противном случае можно открыть окно Azure Cloud Shell в браузере и выполнить в нем команды.

  1. Сначала убедитесь, что вы выполнили вход в Azure с соответствующими учетными данными, выполнив следующую команду:

    az login

  2. Затем используйте команду AZ Account Get-Access-Token, чтобы получить маркер носителя с доступом к службе Azure Digital Twins. В этой команде вы передадите идентификатор ресурса для конечной точки службы цифровых двойников Azure, чтобы получить маркер доступа, который может получить доступ к ресурсам Azure Digital Twins.

    Необходимый контекст для маркера зависит от того, какой набор API используется, поэтому используйте следующие вкладки для выбора между API плоскости данных и плоскости управления.

    Чтобы получить маркер для использования с API плоскости данных, используйте следующее статическое значение для контекста маркера: 0b07f429-9f4b-4714-9392-cc5e8e80c8b0 Это значение является идентификатором ресурса для конечной точки службы Azure Digital Twins.

    az account get-access-token --resource 0b07f429-9f4b-4714-9392-cc5e8e80c8b0

    Примечание.

    Если вам нужно получить доступ к экземпляру Azure Digital Twins с помощью субъекта-службы или учетной записи пользователя, которая принадлежит другому клиенту Microsoft Entra из экземпляра, вам потребуется запросить маркер из "домашнего" клиента экземпляра Azure Digital Twins. Дополнительные сведения об этой процедуре см. в статье Написание кода проверки подлинности приложения.

  3. Скопируйте значение accessToken в результат и сохраните его для использования в следующем разделе. Это значение маркера , которое вы предоставите Postman для авторизации запросов.

    Screenshot of the console showing the result of the az account get-access-token command. The accessToken field with its sample value highlighted.

Совет

Этот маркер действителен не менее 5 и не более 60 минут. Если вы исчерпали время, выделенное для текущего маркера, можно повторить шаги, описанные в этом разделе, чтобы получить новый.

Далее вы настроите Postman, чтобы использовать этот маркер для выполнения запросов API к Azure Digital Twins.

О коллекциях Postman

Запросы в Postman сохраняются в коллекциях (группах запросов). При создании коллекции для группирования запросов можно одновременно применить общие параметры к нескольким запросам. Общие параметры могут значительно упростить авторизацию, если планируется создать несколько запросов к API Azure Digital Twins, так как эти сведения нужно настроить только один раз для всей коллекции.

При работе с Azure Digital Twins можно начать с импорта предварительно созданной коллекции всех запросов Azure Digital Twins. Вы можете импортировать эту коллекцию, если вы изучаете API и хотите быстро настроить проект с примерами запросов.

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

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

Импорт коллекции API Azure Digital Twins

Быстрый способ начать работу с Azure Digital Twins в Postman — импортировать предварительно созданную коллекцию запросов для API. Выполните приведенные ниже действия, чтобы импортировать коллекцию популярных запросов API плоскости данных Azure Digital Twins, содержащих примеры данных запроса.

  1. В главном окне Postman нажмите кнопку Импорт. Screenshot of a newly opened Postman window. The 'Import' button is highlighted.

  2. В следующем окне импорта выберите "Ссылка" и введите следующий URL-адрес: https://raw.githubusercontent.com/microsoft/azure-digital-twins-postman-samples/main/postman_collection.json Затем нажмите кнопку "Импорт ", чтобы подтвердить.

    Screenshot of Postman's 'Import' window, showing the file to import as a collection and the Import button.

Теперь можно просмотреть только что импортированную коллекцию в главном представлении Postman на вкладке коллекций.

Screenshot of the main Postman window. The newly imported collection is highlighted in the 'Collections' tab.

Совет

Чтобы импортировать полный набор вызовов API для определенной версии API Azure Digital Twins (включая плоскость управления или плоскость данных), можно также импортировать файлы Swagger в виде коллекций. Ссылки на файлы Swagger для API уровня управления и плоскости данных см . в API и пакетах SDK для Azure Digital Twins.

Затем перейдите к следующему разделу, чтобы добавить маркер носителя в коллекцию для авторизации и подключить его к экземпляру Azure Digital Twins.

Настройка авторизации

Затем измените созданную коллекцию, чтобы настроить определенные сведения о доступе. Выделите созданную коллекцию и выберите значок "Просмотреть дополнительные действия " для отображения параметров действия. Выберите команду Изменить.

Screenshot of Postman. The 'View more actions' icon for the imported collection is highlighted, and 'Edit' is highlighted in the options.

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

  1. В диалоговом окне редактирования коллекции убедитесь, что вы находитесь на вкладке Авторизация.

    Screenshot of the imported collection's edit dialog in Postman, showing the 'Authorization' tab.

  2. Задайте для типа OAuth 2.0 и вставьте маркер доступа в поле маркера доступа. Необходимо использовать правильный маркер для типа используемого API, так как существуют различные маркеры для API плоскости данных и API уровня управления. Выберите Сохранить.

    Screenshot of Postman edit dialog for the imported collection, on the 'Authorization' tab. Type is 'OAuth 2.0', and Access Token box is highlighted.

    Совет

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

Прочая конфигурация

Вы можете легко подключить коллекцию к ресурсам Azure Digital Twins, задав некоторые переменные, предоставляемые коллекцией. Если для большого числа запросов в коллекции требуется одинаковое значение (например, имя узла для своего экземпляра Azure Digital Twins), можно сохранить значение в переменной, которая применяется к каждому запросу в коллекции. Коллекция Azure Digital Twins поставляется с предварительно созданными переменными, которые можно задать на уровне коллекции.

  1. В диалоговом окне редактирования для коллекции перейдите на вкладку Переменные.

  2. Используйте следующую таблицу, чтобы задать значения переменных в коллекции:

    Переменная Набор API Description
    digitaltwins-hostname Плоскость данных имя узла вашего экземпляра Azure Digital Twins. Это значение можно найти на странице обзора экземпляра на портале.
    subscriptionId Уровень управления Идентификатор вашей подписки Azure.
    digitalTwinInstance Уровень управления Имя экземпляра Azure Digital Twins.

    Screenshot of the imported collection's edit dialog in Postman, showing the 'Variables' tab. The 'CURRENT VALUE' field is highlighted.

  3. Если в коллекции есть дополнительные переменные, заполните и сохраните эти значения.

  4. Выберите Сохранить.

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

Изучение запросов

Теперь изучите запросы в коллекции API Azure Digital Twins. Можно развернуть коллекцию, чтобы просмотреть предварительно созданные запросы (отсортированные по категории операций).

Для разных запросов требуются разные сведения об экземпляре и его данных. Чтобы просмотреть все сведения, необходимые для составления конкретного запроса, найдите сведения о запросе в справочной документации по API REST Azure Digital Twins.

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

  1. Выберите его из списка, чтобы получить редактируемые сведения.

  2. Большинство запросов в образце коллекции предварительно настроены для выполнения без каких-либо дополнительных изменений.

  3. На следующем снимке экрана показан API добавления DigitalTwinModels. На вкладке "Текст" вы увидите полезные данные JSON, определяющие новую модель для добавления:

  4. Заполните значения переменных, перечисленных на вкладке параметров, в Переменные пути.

    Screenshot of Postman. The collection is expanded to show the body tab of a request.

  5. Чтобы запустить запрос, используйте кнопку "Отправить ".

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

Создание собственной коллекции

Вместо импорта существующей коллекции API Azure Digital Twins можно также создать собственную коллекцию с нуля. Затем вы можете заполнить его отдельными запросами, используя справочную документацию по API REST Azure Digital Twins.

Создание коллекции Postman

  1. Чтобы создать коллекцию, нажмите кнопку "Создать " в главном окне Postman.

    Screenshot of the main Postman window. The 'New' button is highlighted.

    Выберите тип коллекции.

    Screenshot of the 'Create New' dialog in Postman. The 'Collection' option is highlighted.

  2. Откроется вкладка. Заполните сведения о новой коллекции. Щелкните значок редактирования рядом с именем по умолчанию для коллекции (Новая коллекция), чтобы заменить его на свой выбор.

    Screenshot of the new collection's edit dialog in Postman. The Edit icon next to the name 'New Collection' is highlighted.

Затем перейдите к следующему разделу, чтобы добавить в коллекцию маркер носителя для авторизации.

Настройка авторизации

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

  1. В диалоговом окне редактирования для новой коллекции перейдите на вкладку Авторизация.

    Screenshot of the new collection's edit dialog in Postman, showing the 'Authorization' tab.

  2. Задайте тип OAuth 2.0, вставьте маркер доступа в поле маркера доступа и нажмите кнопку Сохранить.

    Screenshot of the Postman edit dialog for the new collection, on the 'Authorization' tab. Type is 'OAuth 2.0', and Access Token box is highlighted.

С выполнением описанных выше действий вы закончите настройку коллекции. Теперь можно закрыть вкладку редактирования для новой коллекции.

Новую коллекцию можно увидеть в главном представлении Postman на вкладке коллекций.

Screenshot of the main Postman window. The newly created custom collection is highlighted in the 'Collections' tab.

Добавление отдельного запроса

Теперь, когда ваша коллекция настроена, вы можете добавить собственные запросы в интерфейсы API Azure Digital Twins.

  1. Чтобы создать запрос, снова используйте кнопку Создать.

    Screenshot of the main Postman window. The 'New' button is highlighted.

    Выберите тип Запроса.

    Screenshot of the 'Create New' dialog in Postman. The 'Request' option is highlighted.

  2. Это действие открывает окно SAVE REQUEST (Сохранить запрос), где можно ввести имя запроса, присвоить ему необязательное описание и выбрать коллекцию, частью которой он является. Заполните сведения и сохраните запрос в созданной ранее коллекции.

Screenshot of 'Save request' window in Postman showing the fields described. The 'Save to Azure Digital Twins collection' button is highlighted.

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

Screenshot of Postman. The Azure Digital Twins collection is expanded to show the request's details.

Задание сведений о запросе

Чтобы отправить запрос Postman к одному из интерфейсов API Azure Digital Twins, вам потребуется URL-адрес API и информация о необходимых ему сведениях. Эти сведения можно найти в справочной документации по API REST Azure Digital Twins.

Чтобы продолжить выполнение примера запроса, в этой статье будет использоваться API запросов Azure Digital Twins для запроса всех цифровых двойников в экземпляре.

  1. Получите URL-адрес запроса и тип из справочной документации. Для API запросов это в настоящее время posthttps://digitaltwins-host-name/query?api-version=2020-10-31.

  2. В окне Postman настройте тип запроса и введите URL-адрес запроса, вставляя в URL-адрес заполнители в соответствии с требованиями. Используйте имя узла экземпляра из раздела "Предварительные требования".

    Screenshot of the new request's details in Postman. The query URL from the reference documentation has been filled into the request URL box.

  3. Убедитесь, что параметры, показанные для запроса на вкладке параметров, соответствуют описанным в справочной документации. Для этого запроса в Postman параметр api-version был автоматически заполнен при вводе URL-адреса запроса на предыдущем шаге. Для API запросов это единственный обязательный параметр, так что этот этап завершен.

  4. На вкладке Авторизация установите тип на Наследовать проверку подлинности от родительского. Это означает, что в этом запросе будет использоваться авторизация, настроенная ранее для всей коллекции.

  5. Убедитесь, что параметры, показанные для запроса на вкладке Заголовки, соответствуют описанным в справочной документации. Для этого запроса несколько заголовков были заполнены автоматически. Для API запросов ни один из параметров заголовка не является обязательным, поэтому этот этап завершен.

  6. Убедитесь, что текст, отображаемый для запроса на вкладке Текст, соответствует требованиям, описанным в справочной документации. Для API запросов текст JSON необходим для предоставления текста запроса. Ниже приведен пример текста для этого запроса, который запрашивает все цифровые двойники в экземпляре:

    Screenshot of the new request's details in Postman, on the Body tab. It contains a raw JSON body with a query of 'SELECT * FROM DIGITALTWINS'.

    Дополнительные сведения о создании запросов Azure Digital Twins см. в статье Запрос данных о графе двойника.

  7. Просмотрите справочную документацию по любым другим полям, которые могут потребоваться для вашего типа запроса. Для API запросов все требования теперь выполнены в запросе Postman, поэтому этот шаг завершен.

  8. Используйте кнопку Отправить, чтобы отправить завершенный запрос. Screenshot of Postman showing the details of the new request. The Send button is highlighted.

После отправки запроса сведения об ответе появятся в окне Postman под запросом. Можно просмотреть код состояния ответа и весь основной текст.

Screenshot of the sent request in Postman. Below the request details, the response is shown. Status is 200 OK and body shows query results.

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

Следующие шаги

Дополнительные сведения об интерфейсах API Azure Digital Twins см. в статье API и пакеты SDK Azure Digital Twins или в справочной документации по интерфейсам REST API.