一意の名前付きリソース
この記事では、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 リソースでは、クライアントが提供するキー プロパティがサポートされているため、べき等の "アップサート" メカニズムを有効にして、リソースが存在しない場合はリソースを作成したり、存在する場合は更新したりできます。 このクライアントが提供するキー プロパティは、代替キーである可能性が高くなりますが、主キーである場合があります。
PATCH /resourceCollection(clientProvidedAlternateKeyProperty='nameValue')
代替キーを使用してリソースを作成すると、サービスによって生成された値が主キー プロパティに設定されます。
このパターンに従うリソースのみが Microsoft Graph Bicep 型として公開され、例外はほとんどありません。
次の表に、Bicep ファイルでサポートされている Microsoft Graph リソースのクライアント指定のキー プロパティを示します。
| Microsoft Graph リソース | クライアント指定のキー プロパティ |
|---|---|
| アプリケーション | uniqueName |
| フェデレーション ID 資格情報 | name |
| 割り当てられたアプリ ロール | オブジェクトを一意に識別するプロパティ値から暗黙的に指定 |
| グループ | uniqueName |
| OAuth2 アクセス許可の付与 | オブジェクトを一意に識別するプロパティ値から暗黙的に指定 |
| サービス プリンシパル | appId |
既存の Microsoft Graph リソース
サポートされているクライアント指定のキー プロパティを使用して、Bicep テンプレート内の既存の Microsoft Graph リソースを参照できます。 HTTP POST を使用して作成されたリソースには、このプロパティが設定されておらず、1 回限りバックフィルが必要な場合があります。
設定すると、クライアント指定のキー プロパティを使用して、リソースを再デプロイ用の Bicep ファイルで宣言できます。 再デプロイせずにリソースのプロパティを読み取る場合は、 existing キーワードを使用します。
重要
一度設定すると、クライアント指定のキー プロパティを変更することはできません。