Уникальные именованные ресурсы

В этой статье сравниваются уникальные ключевые стратегии ресурсов в API Microsoft Azure и API Microsoft Graph, а также изменения, внесенные в API Microsoft Graph, чтобы они могли использоваться в декларативной инфраструктуре в виде файлов шаблонов кода, таких как файлы Bicep. В нем также объясняется, как эти изменения можно использовать для ссылки на существующие ресурсы Microsoft Graph, созданные с помощью механизмов, отличных от развертывания файлов Bicep.

Внимание

Microsoft Graph Bicep в настоящее время находится в предварительной версии. Юридические условия, применимые к функциям Azure, которые находятся в состоянии бета-версии, предварительной версии или иным образом еще не выпущены в общедоступной версии, см. на странице Дополнительные условия использования предварительных версий в Microsoft Azure.

Ключи ресурсов Azure и Microsoft Graph

API Microsoft Azure и Microsoft Graph используют неочерпаемые механизмы для создания ресурсов. Эти различия становятся более очевидными при попытке объявить оба этих ресурса в одних и том же файлах шаблонов Bicep.

Стандартный шаблон API Microsoft Azure для создания ресурсов — использовать метод HTTP PUT с уникальным ключом name, предоставленным клиентом. Эта идемпотентная операция создает ресурс с предоставленным name значением, если он не существует, или обновление (замена), если он существует:

PUT /resourceCollection/{nameValue}

Стандартный шаблон API Microsoft Graph для создания ресурсов — использовать метод HTTP POST. Этот метод не является идемпотентным и возвращает созданный службой уникальный ключ idидентификатора.

POST /resourceCollection

Обновления существующих ресурсов выполняются с помощью метода HTTP PATCH, который, в отличие от PUT, не использует семантику замены.

Семантика создания Microsoft Graph хорошо служит большинству разработчиков, но не соответствует двум ключевым требованиям для декларативных шаблонов файлов:

• Повторяемость. Развертывание файла шаблона должно выполняться несколько раз с одинаковым результатом, что среда развертывания соответствует ресурсам, объявленным в файле шаблона. Эта повторяемость невозможна для неидемпотентных методов, таких как POST.
• Предоставленные клиентом ключи или имена: создание и обслуживание декларативного файла шаблона требует объявления имен ресурсов (или ключей, предоставленных клиентом) заранее. Для большинства API Microsoft Graph ключи, предоставляемые клиентом, недоступны.

Ключи, предоставляемые клиентом Microsoft Graph

Помимо стандартного шаблона создания некоторые ресурсы Microsoft Graph могут указать альтернативное свойство ключа, которое будет использоваться в качестве уникального имени клиента. Вместе с уникальным именем, предоставленным клиентом, эти ресурсы поддерживают механизм idempotent upsert, чтобы создать ресурс, если он не существует или обновить его, если он делает:

PATCH /resourceCollection(uniqueName='nameValue')

При создании ресурса также устанавливается созданный службой уникальный ключ идентификатора. В большинстве случаев для ресурсов Microsoft Graph этот альтернативный ключ вызывается uniqueName.

Только ресурсы, следуйте этому шаблону, предоставляются как типы Bicep Microsoft Graph (с несколькими исключениями).

Существующие ресурсы Microsoft Graph

Ресурсы Microsoft Graph, созданные с помощью метода HTTP POST, не имеют уникального набора свойств имени.

Возможно, потребуется перенести существующие ресурсы в файл Bicep, чтобы они могли управляться, как и другие ресурсы, объявленные в Bicep-файле. Выполняя однократное резервное заполнение уникального свойства имени существующего ресурса, можно объявить этот ресурс в файле Bicep, чтобы повторно развернуть его. Кроме того, можно ссылаться на ресурс в файле Bicep с помощью существующей ключевое слово.

После установки альтернативного свойства ключа его нельзя изменить.

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

Узнайте, как ссылаться на существующие ресурсы