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

注意

時間序列深入解析 （TSI） 服務在 2025 年 3 月之後將不再受到支援。 請考慮儘快將現有的 TSI 環境移轉至替代解決方案。 如需淘汰和移轉的詳細資訊，請瀏覽我們的 檔。

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

受控識別

下列各節說明如何使用來自 Microsoft Entra ID 的受控識別來存取 Azure 時間序列深入解析 API。 在 Azure 上，受控識別可讓開發人員不需要管理認證，方法是在 Microsoft Entra ID 中提供 Azure 資源的身分識別，並將其用來取得 Microsoft Entra ID 權杖。 以下是使用受控識別的一些優點：

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

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

您可以從下列專案使用受控識別：

• Azure VM
• Azure App Service
• Azure Functions
• Azure 容器實例
• 等等...

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

Microsoft Entra 應用程式註冊

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

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

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

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

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

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

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

受控識別

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

• Azure VM
• App Service 和 Azure Functions
• Azure 容器執行個體
• 等等...

應用程式註冊

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

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

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

    • 針對裝載於本機開發環境中的應用程式，選取 [公用用戶端] [行動裝置和桌面]。 請務必將公用用戶端設定為 [是]。
    • 針對裝載於 Azure App 服務 的單頁應用程式，選取 [Web]。

  • 判斷註銷 URL 是否合適。

  • 檢查存取令牌或標識碼令牌，以啟用隱含授與流程。

  

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

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

  

  在搜尋欄位中輸入 Azure Time Series Insights ，然後選取 Azure Time Series Insights。

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

  

• 如果應用程式將自行呼叫您環境的 API，請新增認證。 認證可讓您的應用程式以自身進行驗證，不需要在執行階段與使用者進行互動。

步驟 2：授與存取權

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

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

• 若要使用 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 服務 或 Functions 存取時，請遵循取得 Azure 資源的令牌中的指引。

對於 .NET 應用程式和函式，使用受控識別最簡單的方式是透過適用於 .NET 的 Azure 身分識別客戶端連結庫 。 此用戶端連結庫很受歡迎，因為它的簡單性和安全性優點。 開發人員可以撰寫程式代碼一次，並讓用戶端連結庫判斷如何根據應用程式環境進行驗證-無論是使用開發人員帳戶的開發人員工作站，還是使用受控服務識別部署在 Azure 中。 如需從前置 AppAuthentication 連結庫移轉指引，請參閱 AppAuthentication 至 Azure.Identity 移轉指引。

使用 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。

一般標頭和參數

本節描述一般 HTTP 要求標頭和參數，這些標頭和參數可用來對 Azure 時間序列深入解析 Gen1 和 Gen2 API 進行查詢。 #D7FACF2545EE449BDA042A8734B179429 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	產生此要求的應用程式名稱。 服務會記錄此值。

以下說明選擇性但建議的響應標頭。

回應標頭	描述
Content-type	只支援 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 環境，可以在 或 ColdStore上WarmStore執行查詢。 查詢中的此參數會定義應該執行查詢的存放區。 如果未定義，查詢將會在冷存放區上執行。 若要查詢暖存放區， storeType 必須設定為 WarmStore。 如果未定義，查詢將會針對冷存放區執行。	Gen2

下一步

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

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

• 如需 API 參考資訊，請閱讀 查詢 API 參考 檔。