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

Visual Studio 2022 поддерживает файлы, которые можно использовать для .http структуры, хранения и непосредственного отправки HTTP-запросов из приложения. Использование этой функции Visual Studio — это один из способов создания HTTP-запросов и отправки их в REST API Azure Digital Twins. В этой статье описывается настройка .http файла в Visual Studio, который может работать с API Azure Digital Twins.

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

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

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

Дополнительные сведения о .http поддержке файлов в Visual Studio см. в статье "Использование HTTP-файлов в Visual Studio 2022".

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

Чтобы запросить API Azure Digital Twins с помощью Visual Studio, необходимо настроить экземпляр Azure Digital Twins и скачать Visual Studio 2022. Этот раздел предназначен для выполнения этих действий.

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

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

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

Скачать Visual Studio 2022

Затем скачайте Visual Studio 2022. Обязательно включите в установку рабочую нагрузку ASP.NET и веб-разработки .

Настройка проекта Visual Studio

В этом разделе описана настройка проекта в Visual Studio, который будет использоваться для создания HTTP-запросов.

Откройте Visual Studio на компьютере и создайте проект. Используйте шаблон проекта ASP.NET Core Empty.

Следуйте инструкциям из статьи "Создание HTTP-файла", чтобы создать новый .http файл в проекте.

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

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

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

Плоскость данных

Добавьте следующие переменные для запросов плоскости данных. Существует один заполнитель для имени узла экземпляра Azure Digital Twins (заканчивается в digitaltwins.azure.net).

@hostName=<host-name-of-your-Azure-Digital-Twins-instance>
@DPversion=2023-10-31

Плоскость управления

Добавьте следующие переменные для запросов уровня управления. Они содержат заполнители для значений ресурсов.

@instance=<name-of-your-Azure-Digital-Twins-instance>
@subscription=<ID-of-your-Azure-subscription>
@resourceGroup=<resource-group>
@CPversion=2023-01-31

Добавление маркера носителя

Теперь, когда вы настроили экземпляр Azure Digital Twins и проект Visual Studio, необходимо получить маркер носителя, который HTTP-запросы могут использовать для авторизации в API Azure Digital Twins.

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

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

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

   az login
   

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

   Плоскость управления

   Чтобы получить маркер для использования с API плоскости управления, используйте следующее значение для контекста маркера: https://management.azure.com/

   az account get-access-token --resource https://management.azure.com/
   

   Примечание.

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

3. Скопируйте значение accessToken результата. Это значение токена , которое вы вставляете в Visual Studio для авторизации запросов.

   

Совет

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

Добавление маркера в .http файл

.http В файле в Visual Studio добавьте другую переменную, содержащую значение маркера.

Плоскость данных

@token=<paste-data-plane-token>

Теперь переменные должны выглядеть примерно так:

Плоскость управления

@token=<paste-control-plane-token>

Теперь переменные должны выглядеть примерно так:

Добавление запросов

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

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

В этой статье будет использоваться API обновления DigitalTwins из плоскости данных в качестве примера.

1. Добавьте шаблон запроса: скопируйте HTTP-запрос, показанный в справочной документации.

   

   В Visual Studio вставьте запрос в новую строку под переменными в .http файле.

2. Добавление параметров. Просмотрите раздел параметров URI в справочной документации, чтобы узнать, какие значения параметров требуются запросом. Можно заменить некоторые переменными , созданными ранее, и заполнить другие значения параметров соответствующим образом. Чтобы ссылаться на переменную, поместите имя переменной в двойные фигурные скобки, например {{variable}}. Дополнительные сведения см. в разделе "Переменные".

   Примечание.

   Для запросов digitaltwins-hostname плоскости данных также является параметром. Замените это {{hostName}} значением переменной имени узла.

   Вот как выглядит этот шаг в примере запроса:

   

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

   Authorization: Bearer {{token}}
   

   Вот как выглядит этот шаг в примере запроса:

   

4. Добавление дополнительных заголовков. Просмотрите раздел заголовка запроса в справочной документации, чтобы узнать, какие значения заголовков могут сопровождать запрос. Вы также можете включить традиционные заголовки HTTP, например Content-Type. Добавьте каждый заголовок в отдельной строке в формате HeaderName: Value. Дополнительные сведения см. в разделе "Заголовки запросов".

   Вот как выглядит этот шаг в примере запроса:

   

5. Добавление текста. Просмотрите раздел "Текст запроса" справочной документации, чтобы узнать, какие сведения о теле могут потребоваться запросом. Добавьте текст запроса после пустой строки. Дополнительные сведения см. в тексте запроса.

   Вот как выглядит этот шаг в примере запроса:

6. Когда запрос будет готов, выберите "Отправить запрос " над запросом, чтобы отправить его.

   

Visual Studio открывает панель с подробными сведениями об ответе. Ознакомьтесь с разделом "Ответы " справочной документации, чтобы интерпретировать код состояния и все данные в тексте ответа.

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

Чтобы добавить дополнительные запросы в .http файл, разделите их как ### разделитель.

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

Дополнительные сведения о отправке запросов с файлами .http в Visual Studio, включая сведения о синтаксисе и расширенные сценарии, см. в статье "Использование HTTP-файлов в Visual Studio 2022".

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