共用方式為


唯一命名的資源

本文會比較 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 檔案中宣告以進行重新部署。 若要讀取資源的屬性而不重新部署,請使用 現有的 關鍵詞。

重要

設定之後,就無法變更用戶端提供的密鑰屬性。

後續步驟