一意の名前付きリソース
この記事では、Microsoft Azure API と Microsoft Graph API のリソース固有のキー戦略と、Microsoft Graph API に加えられた変更を比較して、Bicep ファイルなどの宣言型インフラストラクチャでコード テンプレート ファイルとして使用できるようにします。 また、これらの変更を使用して、Bicep ファイルのデプロイ以外のメカニズムを使用して作成された既存の Microsoft Graph リソースを参照する方法についても説明します。
重要
Microsoft Graph Bicep は現在プレビュー段階です。 ベータ版、プレビュー版、または一般提供としてまだリリースされていない Azure の機能に適用される法律条項については、「Microsoft Azure プレビューの追加使用条件」を参照してください。
Azure と Microsoft Graph のリソース キー
Microsoft Azure API と Microsoft Graph API は、リソースを作成するために微妙に異なるメカニズムを使用します。 これらの違いは、両方のリソースを同じ Bicep テンプレート ファイルで宣言しようとすると、より明らかになります。
リソースを作成するための Microsoft Azure API の標準的なパターンは、クライアントが提供する一意のキーを呼び出 nameして HTTP PUT メソッドを使用することです。 このべき等操作では、指定された name 値が存在しない場合はリソースが作成され、存在する場合は更新 (置換) されます。
PUT /resourceCollection/{nameValue}
リソースを作成するための Microsoft Graph API の標準パターンは、HTTP POST メソッドを使用することです。 このメソッドはべき等ではなく、サービスによって生成された一意の ID キーを返します id。
POST /resourceCollection
既存のリソースへの更新は、HTTP PATCH メソッドを使用して実現されます。PUT とは異なり、代替セマンティックは使用されません。
Microsoft Graph 作成セマンティクスはほとんどの開発者に役立ちますが、宣言型ファイル テンプレートの 2 つの重要な要件を満たしていません。
- 再現性: テンプレート ファイルのデプロイは、同じ結果で複数回実行する必要があります。デプロイ環境は、テンプレート ファイルで宣言されているリソースと一致します。 POST のような非べき等メソッドでは、この繰り返し性は使用できません。
- クライアントが提供するキーまたは名前: 宣言型テンプレート ファイルの作成とメインには、リソース名 (またはクライアントが提供するキー) を事前に宣言する必要があります。 ほとんどの Microsoft Graph API では、クライアントが提供するキーは使用できません。
Microsoft Graph クライアント提供のキー
標準の作成パターンに加えて、一部の Microsoft Graph リソースでは、クライアント指定の一意の名前として使用する代替キー プロパティを指定できます。 クライアントが指定した一意の名前と共に、これらのリソースはべき等の "upsert" メカニズムをサポートし、リソースが存在しない場合はリソースを作成し、存在する場合は更新します。
PATCH /resourceCollection(uniqueName='nameValue')
リソースが作成されると、サービスによって生成された一意の ID キーも設定されます。 ほとんどの場合、Microsoft Graph リソースでは、この代替キー プロパティが呼び出されます uniqueName。
このパターンに従うリソースのみが、Microsoft Graph Bicep 型として公開されます (いくつかの例外があります)。
既存の Microsoft Graph リソース
HTTP POST メソッドを使用して作成された Microsoft Graph リソースには、一意の名前プロパティが設定されていません。
これらの既存のリソースを Bicep ファイルに取り込んで、Bicep ファイルで宣言されている他のリソースと同様に管理することができます。 既存のリソースの一意の名前プロパティの 1 回限りのバックフィルを実行することで、そのリソースを Bicep ファイルで宣言して、再デプロイすることができます。 または、既存のキーワード (keyword)を使用して、Bicep ファイル内のリソースを参照することもできます。
代替キー プロパティを設定した後は、変更できません。