Azure 時間序列深入解析 API 的驗證和授權

注意

時間序列深入解析服務將於 2024 年 7 月 7 日淘汰。 請考慮儘快將現有的環境移轉至替代解決方案。 如需淘汰和移轉的詳細資訊，請瀏覽我們的 檔。

根據您的業務需求，您的解決方案可能包含一或多個用戶端應用程式，讓您用來與 Azure 時間序列深入解析環境 API 互動。 Azure 時間序列 Insights 會使用以 OAuth 2.0為基礎的 Microsoft Entra 安全性令牌來執行驗證。 若要驗證您的用戶端，您必須取得具有正確許可權的持有人令牌，並將它連同 API 呼叫一起傳遞。 本文件說明數種方法，您可以用來取得持有者權杖並進行驗證的憑證，包括使用受控身分識別和 Microsoft Entra 應用程式註冊。

受控識別

下列各節說明如何使用來自 Microsoft Entra ID 的受控識別來存取 Azure 時間序列深入解析 API。 在 Azure 上，受控識別透過在 Microsoft Entra ID 中為 Azure 資源提供身分識別，並利用該身分識別來獲取 Microsoft Entra 令牌，從而消除了開發人員管理認證的需求。 以下是使用受控識別的一些優點：

• 您不需要管理認證。 您甚至無法存取認證。
• 您可以使用受控識別向任何支援 Microsoft Entra 驗證的 Azure 服務進行驗證，包括 Azure Key Vault。
• 您可以使用受控識別，而不需要任何額外費用。

如需兩種受控識別類型的詳細資訊，請參閱 什麼是 Azure 資源的受控識別？

您可以從下列來源使用受控身分識別：

• Azure 虛擬機器
• Azure App Services
• Azure 函數
• Azure 容器實例
• 等等...

如需完整清單，請參閱 支援 Azure 資源受控識別的 Azure 服務。

Microsoft Entra 應用程式註冊

建議您盡可能使用受控識別，讓您不需要管理認證。 如果您的用戶端應用程式未裝載於支援受控識別的 Azure 服務上，您可以使用 Microsoft Entra 租使用者註冊應用程式。 當您使用 Microsoft Entra ID 註冊應用程式時，您要為應用程式建立身分識別組態，讓它與 Microsoft Entra ID 整合。 當您在 Azure 入口網站中註冊應用程式時，您可以選擇它是單一租使用者（只能在租使用者中存取）或多租使用者（在其他租使用者中可存取），也可以選擇性地設定重新導向 URI（傳送存取令牌的位置）。

當您完成應用程式註冊時，您有位於主租使用者或目錄內的應用程式 （應用程式物件） 的全域唯一實例。 您也有應用程式的全域唯一識別碼（應用程式或用戶端識別符）。 在入口網站中，您可以新增秘密或憑證和範圍，讓您的應用程式運作、在登入對話框中自定義應用程式的商標等等。

如果您在入口網站中註冊應用程式，則會自動在主租使用者中建立應用程式對象和服務主體物件。 如果您使用 Microsoft Graph API 註冊/建立應用程式，則建立服務主體對象是個別的步驟。 要請求 token，需要有一個服務主體物件。

請務必檢閱應用程式的 安全性 檢查清單。 最佳做法是，您應該使用 憑證認證，而不是密碼認證（客戶端密碼）。

如需詳細資訊，請參閱 Microsoft Entra ID 中的 應用程式和服務主體物件。

步驟 1：建立受控識別或應用程式註冊

一旦您確定要使用受控識別或應用程式註冊，下一步就是布建其中一個。

受管理的識別

您用來建立受控身分的步驟會根據您的程序代碼所在的位置，以及您正在建立的身分是系統指派或使用者指派而有所不同。 閱讀 受控識別類型 以了解差異。 選取身分識別類型之後，請在 Microsoft Entra 受控身分識別 文件中找出並遵循正確的教學。 您可以在該處找到如何設定受控識別的指示：

• Azure 虛擬機
• App Service 和 Azure Functions
• Azure Container Instances
• 等等...

應用程式註冊

請遵循 註冊應用程式中所述的步驟。

• 在 [設定平臺 設定] 的步驟 4 中選擇適當的平台後，請在使用者介面右側的面板中設定 重新導向 URI 和 存取令牌。

  • 重新導向 URI 必須符合驗證要求所提供的位址：

    • 針對在本機開發環境中運行的應用程式，請選取 公用客戶端（行動裝置 & 桌面）。 請務必將公用用戶端 設定為 [是]。
    • 針對裝載在 Azure App Service 上的 Single-Page 應用程式，選取 [Web]。

  • 判斷 登出 URL 是否適當。

  • 藉由檢查 存取令牌 或 身份令牌來啟用隱式授權流程。

  

  按一下 [設定]，然後 [儲存]。

• 將您的 Microsoft Entra 應用程式與 Azure 時間序列深入解析關聯。 選取 [API 許可權]，>[新增許可權]>[我的組織使用的 API]。

  

  在搜尋列中輸入 Azure Time Series Insights，然後選取 [Azure Time Series Insights]。

• 接下來，指定應用程式所需的 API 許可權種類。 根據預設，[委派的許可權] 將會被標記。 選擇權限類型，然後選擇 新增權限。

  

• 如果應用程式本身會呼叫您環境的 API，新增認證。 認證可讓應用程式以本身身分進行驗證，不需要在運行時間與用戶互動。

步驟 2：授與存取權

當您的 Azure 時間序列深入解析環境收到要求時，會先驗證呼叫端的持有人令牌。 如果通過驗證，則呼叫端已經過驗證，然後進行另一項檢查，以確保呼叫者有權執行要求的動作。 若要授權任何使用者或服務主體，您必須先指派「讀取者」或「參與者」角色，授與他們環境存取權。

• 若要透過 Azure 入口網站 UI 授與存取權，請遵循 授與環境 數據存取一文中所列的指示。 選取使用者時，您可以依名稱或 ID 搜尋受控身分識別或應用程式註冊。

• 若要使用 Azure CLI 授與存取權，請執行下列命令。 請檢閱此處的檔 ，以取得可用來管理存取權的完整命令清單。

  az tsi access-policy create --name "ap1" --environment-name "env1" --description "some description" --principal-object-id "aGuid" --roles Reader Contributor --resource-group "rg1"
  

注意

Azure CLI 的 timeseriesinsights 擴充功能需要 2.11.0 版或更高版本。 擴充功能會在您第一次執行 az tsi access-policy 命令時自動安裝。 深入瞭解擴充功能。

步驟 3：要求令牌

布建並指派角色后，您的受控識別或應用程式註冊之後，您就可以開始使用它來要求 OAuth 2.0 持有人令牌。 您用來取得令牌的方法會根據裝載程式代碼的位置和您選擇的語言而有所不同。 當指定資源（也稱為令牌的「受眾」）時，您可以透過其 URL 或 GUID 識別 Azure 時間序列見解：

• https://api.timeseries.azure.com/
• 120d688d-1518-4cf7-bd38-182f158850b6

重要

如果您使用網址作為資源識別碼，則令牌必須精確頒發給 https://api.timeseries.azure.com/。 保留尾端的斜線是必要的。

• 如果使用 Postman 您的 AuthURL 將會是：https://login.microsoftonline.com/microsoft.onmicrosoft.com/oauth2/authorize?scope=https://api.timeseries.azure.com//.default
• https://api.timeseries.azure.com/ 有效，但 https://api.timeseries.azure.com 無效。

受管理的識別

從 Azure App Service 或 Functions 存取 Azure 資源時，請遵循取得 Azure 資源的代碼中的指引。

針對 .NET 應用程式和函式，使用受控識別最簡單的方式是透過適用於 .NET 的 azure 身分識別用戶端連結庫 。 該客戶端連結庫因為簡單且具有安全的優勢而受到歡迎。 開發人員可以撰寫一次程式碼，並讓用戶端程式庫判斷如何基於應用程式環境進行身份驗證，無論是使用開發人員帳戶的開發人員工作站，還是使用受控服務身分部署在 Azure 中。 如需從前身 AppAuthentication 程式庫的遷移指引，請參閱 AppAuthentication 至 Azure.Identity Migration Guidance。

使用 C# 和適用於 .NET 的 Azure 身分識別用戶端程式庫請求 Azure 時間序列深入解析的令牌：

using Azure.Identity;
// ...
var credential = new DefaultAzureCredential();
var token = credential.GetToken(
new Azure.Core.TokenRequestContext(
    new[] { "https://api.timeseries.azure.com/" }));
var accessToken = token.Token;

應用程式註冊

• 使用 Microsoft 驗證庫 (MSAL) 來取得應用程式註冊的令牌。

MSAL 可用於許多應用程式案例，包括但不限於：

• 單頁應用程式 （JavaScript）
• Web 應用程式登入使用者，並代表使用者呼叫 Web API
• Web API 代表登入的使用者呼叫另一個下游 Web API
• 桌面應用程式代表登入的使用者呼叫 Web API
• 行動應用程式，代表以互動方式登入的使用者呼叫 Web API，。
• 桌面/服務精靈應用程式代表本身呼叫 Web API

如需示範如何從 Gen2 環境取得令牌作為應用程式註冊和查詢數據的範例 C# 程式代碼，請檢視 GitHub 上的範例應用程式

重要

如果您使用 Azure Active Directory 驗證連結庫 （ADAL），移轉至 MSAL。

一般標頭和參數

本節介紹用於對 Azure 時間序列深入解析 Gen1 和 Gen2 API 查詢的一般 HTTP 要求標頭與參數。 Azure 時間序列深入解析 REST API 參考檔中會更詳細地涵蓋 API 特定需求。

提示

若要深入瞭解如何使用 REST API、提出 HTTP 要求及處理 HTTP 回應，請閱讀 Azure REST API 參考。

HTTP 標頭

以下說明必要的請求標頭。

必需的請求標頭	描述
授權	若要向 Azure 時間序列深入解析進行驗證，必須在 授權標頭中傳遞有效的 OAuth 2.0 持有人令牌，。

提示

閱讀託管的 Azure 時間序列深入解析用戶端 SDK 範例視覺化，了解如何使用 JavaScript 用戶端 SDK 及圖表和圖形，程式化地與 Azure 時間序列深入解析 API 進行驗證。

以下是可選的要求標頭的說明。

可選的要求標頭	描述
Content-type	僅支援 application/json。
x-ms-client-request-id	用戶端要求標識碼。 服務會記錄此值。 允許服務在不同服務之間追蹤操作。
x-ms-client-session-id	用戶端會話標識碼。 服務會記錄此值。 允許服務追蹤跨服務的相關作業群組。
x-ms-client-application-name	產生此要求的應用程式名稱。 服務會記錄此值。

以下列出選擇性但建議的回應標頭。

回應標頭	描述
內容類型	僅支援 application/json。
x-ms-request-id	伺服器產生的要求識別碼。 可用來連絡 Microsoft，以便調查請求。
x-ms-property-not-found-behavior (屬性未找到行為)	GA API 可選響應標頭。 可能的值為 ThrowError （預設值） 或 UseNull。

HTTP 參數

提示

在 參考檔案中尋找必要和選擇性查詢資訊的詳細資訊，。

必要的 URL 查詢字串參數取決於 API 版本。

釋放	API 版本值
Gen1	api-version=2016-12-12
Gen2	api-version=2020-07-31

選擇性的 URL 查詢字串參數包括設定 HTTP 要求執行時間的超時。

選擇性查詢參數	描述	版本
timeout=<timeout>	HTTP 要求執行的伺服器端逾時。 僅適用於 取得環境事件 和 取得環境匯總 的 API。 逾時值應為 ISO 8601 持續時間格式，例如 "PT20S"，且應位於 1-30 s範圍中。 預設值為 30 s。	Gen1
storeType=<storeType>	針對已啟用暖存放區的 Gen2 環境，可以在 WarmStore 或 ColdStore上執行查詢。 查詢中的此參數會定義查詢應該在哪個目標存放區執行。 如果未定義，查詢將會在冷存放區上執行。 若要查詢暖存放區，storeType 必須設定為 WarmStore。 如果未定義，查詢將會針對冷存放區執行。	Gen2

後續步驟

• 如需呼叫 Gen1 Azure 時間序列深入解析 API 的範例程式代碼，請使用 C#讀取 Query Gen1 數據。

• 如需呼叫 Gen2 Azure 時間序列深入解析 API 程式代碼範例的範例程式代碼，請使用 C#讀取 Query Gen2 數據。

• 如需 API 參考資訊，請參閱 API 查詢參考 文件。