Azure Time Series Insights API 的驗證和授權

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

受控識別

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

  • 您不需要管理認證。 您甚至無法存取認證。
  • 您可以使用受控識別,對支援 Azure AD 驗證的任何 Azure 服務 (包括 Key Vault) 進行驗證。
  • 不需任何額外成本,即可使用受控識別。

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

您可以使用來自的受控識別:

  • Azure VM
  • Azure App Service
  • Azure Functions
  • Azure 容器實例
  • 還有更多 .。。

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

Azure Active Directory 應用程式註冊

建議您盡可能使用受控識別,如此您就不需要管理認證。 如果您的用戶端應用程式未裝載在支援受控身分識別的 Azure 服務上,您可以向 Azure AD 租使用者註冊您的應用程式。 當您向 Azure AD 註冊應用程式時,您會建立應用程式的身分識別設定,讓它能夠與 Azure AD 整合。 當您在 Azure 入口網站中註冊應用程式時,您可以選擇它是單一租使用者 (只能在您的租使用者中存取) 或在其他租使用者中可存取的多租使用者 (,而且可以選擇性地設定將存取權杖傳送至) 的重新導向 URI (。

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

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

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

如需詳細資訊,請參閱Azure Active Directory 中的應用程式和服務主體物件

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

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

受控識別

您將用來建立受控識別的步驟會根據您的程式碼所在位置,以及您是否要建立系統指派或使用者指派的身分識別,而有所不同。 讀取 受控識別類型 以瞭解差異。 選取您的身分識別類型之後,請在 Azure AD 管理的身分識別 中找出並遵循正確的教學課程。 您會在這裡找到如何設定受控識別的指示:

應用程式註冊

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

  • 在 [ 設定平臺 設定] 的步驟4中選取適當的平臺之後,請在使用者介面右邊的側邊面板中設定重新 導向 Uri存取權杖

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

      • 對於裝載在本機開發環境中的應用程式,請選取 [公用用戶端 (行動和傳統型)]。 請務必將 [公用用戶端] 設定為 [是]。
      • 對於裝載在 Azure App Service 上的單頁應用程式,請選取 [Web]。
    • 判斷 [登出 URL] 是否適當。

    • 勾選 [存取權杖] 或 [識別碼權杖],以啟用隱含授與流程。

    建立重新導向 URI

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

  • 將 Azure Active Directory 應用程式 Azure 時間序列深入解析相關聯。 選取 [API 權限] > [新增權限] > [組織使用的 API]。

    讓 API 與 Azure Active Directory 應用程式建立關聯

    在搜尋列中輸入 Azure Time Series Insights,然後選取 Azure Time Series Insights

  • 接下來,請指定應用程式所需的 API 權限類型。 根據預設,系統會醒目提示 [委派的權限]。 選擇某個權限類型,然後選取 [新增權限]。

    指定應用程式所需的 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 的 >201-timeseriesinsights-environment-with-eventhub 延伸模組需要2.11.0 版或更高版本。 當您第一次執行 az tsi 存取原則命令時,會自動安裝此延伸模組。 深入瞭解 擴充功能。

步驟3:要求權杖

一旦布建您的受控識別或應用程式註冊並指派角色之後,您就可以開始使用它來要求 OAuth 2.0 持有人權杖。 您用來取得權杖的方法會根據您的程式碼裝載位置和您選擇的語言而有所不同。 當指定資源 (也稱為權杖) 的「物件」時,您可以透過 URL 或 GUID 來識別 Azure 時間序列深入解析:

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

重要

如果您使用 URL 做為資源識別碼,則必須將該權杖確切地發出至 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 或函數存取時,請遵循 取得 Azure 資源權杖中的指引。

針對 .NET 應用程式和函式,使用受控識別的最簡單方式是透過適用于 .NET 的 Azure 身分識別用戶端程式庫 。 因為此用戶端程式庫的簡易性和安全性優點,所以很受歡迎。 開發人員只要撰寫程式碼一次,就可以讓用戶端程式庫判斷如何根據應用程式環境進行驗證,不論是在開發人員工作站上使用開發人員的帳戶,或是使用受控服務識別來部署到 Azure。 如需前身 AppAuthentication 程式庫的遷移指導方針,請參閱 AppAuthentication 至 Azure。身分識別遷移指引

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

應用程式註冊

MSAL 可用於許多應用程式案例,包括(但不限於):

如需示範如何取得權杖作為應用程式註冊以及從 Gen2 環境查詢資料的範例 c # 程式碼,請參閱GitHub上的範例應用程式。

重要

如果您使用Azure Active Directory Authentication Library (ADAL) 閱讀有關遷移至 MSAL的資訊。

一般標頭和參數

本節說明用來對 Azure 時間序列深入解析 Gen1 和 Gen2 api 進行查詢的一般 HTTP 要求標頭和參數。 API 特定的需求會在Azure 時間序列深入解析 REST API 參考檔中更詳細地討論。

提示

請閱讀 Azure REST API 參考 (英文),以深入了解如何使用 REST API、提出 HTTP 要求,以及處理 HTTP 回應。

HTTP 標頭

必要的要求標頭如下所述。

必要的要求標頭 描述
授權 若要使用 Azure 時間序列深入解析進行驗證,必須在授權標頭中傳遞有效的 OAuth 2.0 持有人權杖。

提示

閱讀 hosted 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 環境,可在或上執行查詢 WarmStore ColdStore 。 這個查詢中參數會定義應執行查詢的存放區。 如果未定義,則會在冷存放區上執行查詢。 若要查詢暖存放區,storeType 必須設定為 WarmStore。 如果未定義,則會針對冷存放區執行查詢。 Gen2

後續步驟