唯一命名的資源
本文會比較 Microsoft azure API 和 Microsoft Graph API 中的資源唯一重要策略,以及對 Microsoft Graph API 所做的變更,讓這些策略可用於宣告式基礎結構,例如 Bicep 檔案等程式代碼範本檔案。 它也說明如何使用這些變更來參考透過 Bicep 檔案部署以外的機制所建立的現有Microsoft Graph 資源。
重要
Microsoft Graph Bicep 目前處於預覽狀態。 請參閱 Microsoft Azure 預覽版增補使用規定,以了解適用於 Azure 功能 (搶鮮版 (Beta)、預覽版,或尚未正式發行的版本) 的法律條款。
Azure 和 Microsoft Graph 資源密鑰
Microsoft Azure 和 Microsoft Graph API 會使用不同機制來建立資源。 嘗試在相同的 Bicep 範本檔案中宣告這兩個資源時,這些差異變得更加明顯。
Microsoft Azure API 建立資源的標準模式是使用 HTTP PUT 方法搭配稱為 name
的用戶端提供的唯一密鑰。 如果資源不存在,這個等冪作業會建立具有所提供 name
值的資源,如果資源不存在,則如果資源不存在,請更新 (replace) :
PUT /resourceCollection/{nameValue}
Microsoft圖形 API 建立資源的標準模式是使用 HTTP POST 方法。 這個方法不是等冪的,而且會傳回稱為 id
的服務產生的唯一標識符密鑰。
POST /resourceCollection
現有資源的更新是使用 HTTP PATCH 方法完成的,這與 PUT 不同,它不會使用取代語意。
Microsoft Graph 建立語意適用於大多數開發人員,但不符合宣告式檔案範本的兩個主要需求:
- 可重複性:範本檔案部署應該執行多次,結果與部署環境符合範本檔案中所宣告的資源相同。 對於 POST 之類的非冪性方法,無法進行這種重複性。
- 用戶端提供的金鑰或名稱:撰寫和維護宣告式範本檔案時,必須事先宣告資源名稱(或用戶端提供的密鑰)。 對於大部分Microsoft Graph API,用戶端提供的密鑰是不可能的。
Microsoft Graph 用戶端提供的金鑰
某些Microsoft Graph 資源支援用戶端提供的密鑰屬性,讓等冪的「upsert」機制在資源不存在或更新資源時建立資源。 這個用戶端提供的金鑰屬性更可能是替代金鑰,但有時它是主鍵。
PATCH /resourceCollection(clientProvidedAlternateKeyProperty='nameValue')
使用替代索引鍵建立資源時,會為主鍵屬性設定服務產生的值。
只有遵循此模式的資源會公開為圖形 Bicep 類型Microsoft,但有少數例外狀況。
下表列出 Bicep 檔案中支援Microsoft Graph 資源的用戶端提供索引鍵屬性:
Microsoft Graph 資源 | 用戶端提供的金鑰屬性 |
---|---|
應用程式 | uniqueName |
同盟身分識別認證 | name |
指派給的應用程式角色 | 從唯一識別對象的屬性值中隱含 |
群組 | uniqueName |
OAuth2 許可權授與 | 從唯一識別對象的屬性值中隱含 |
服務主體 | 應用程式識別碼 |
現有的 Microsoft Graph 資源
您可以藉由支持的用戶端提供的索引鍵屬性,參考 Bicep 範本中現有的Microsoft Graph 資源。 透過 HTTP POST 建立的資源可能未設定此屬性,而且需要一次性回填。
設定之後,用戶端提供的金鑰屬性可讓資源在 Bicep 檔案中宣告以進行重新部署。 若要讀取資源的屬性而不重新部署,請使用 現有的 關鍵詞。
重要
設定之後,就無法變更用戶端提供的密鑰屬性。