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


Отправка запросов в 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 для авторизации запросов.

    Снимок экрана: консоль с результатом команды az account get-access-token. Поле accessToken с выделенным примером значения.

Совет

Этот маркер действителен не менее 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 нажмите кнопку Импорт. Снимок экрана: только что открытое окно Postman. Кнопка

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

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

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

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

Совет

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

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

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

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

Снимок экрана Postman. Будет выделен значок

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

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

    Снимок экрана: диалоговое окно редактирования импортированной коллекции в Postman, отображающее вкладку

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

    Снимок экрана: диалоговое окно редактирования Postman для импортированной коллекции на вкладке Authorization (Авторизация). Типом является OAuth 2.0, а поле Access Token (Маркер доступа) выделено.

    Совет

    Вы можете включить общий доступ к маркерам, если вы хотите сохранить маркер с запросом в облаке 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.

    Снимок экрана: диалоговое окно редактирования импортированной коллекции в Postman, показывающее вкладку

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

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

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

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

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

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

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

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

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

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

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

    Снимок экрана: Postman. Коллекция развернута, чтобы отобразить вкладку текста запроса.

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

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

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

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

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

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

    Снимок экрана: основное окно Postman. Кнопка

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

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

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

    Снимок экрана: диалоговое окно редактирования новой коллекции в Postman. Выделен значок редактирования рядом с именем

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

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

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

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

    Снимок экрана: диалоговое окно редактирования новой коллекции в Postman, отображающее вкладку

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

    Снимок экрана: диалоговое окно редактирования Postman для новой коллекции на вкладке

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

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

Снимок экрана: основное окно Postman. Только что созданная пользовательская коллекция будет выделена на вкладке

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

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

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

    Снимок экрана: основное окно Postman. Кнопка

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

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

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

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

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

Снимок экрана Postman. Коллекция Azure Digital Twins расширяется, отображая сведения о запросе.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Снимок экрана отправленного запроса в Postman. Под сведениями о запросе отображается ответ. Состояние — 200 OK, текст показывает результаты запроса.

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

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

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