存取 Azure 監視器 Log Analytics API

您可以使用 Azure 監視器 Log Analytics 端點 https://api.loganalytics.azure.com，將查詢要求提交至工作區。 若要存取該端點，您必須透過 Microsoft Entra ID 進行驗證。

注意

api.loganalytics.io 端點即將取代為 api.loganalytics.azure.com。 在可預見的未來，將繼續支援 api.loganalytics.io 端點。

使用示範 API 金鑰進行驗證

若要在不使用 Microsoft Entra 驗證的情況下快速探索 API，請使用示範工作區搭配範例資料 (支援 API 金鑰驗證)。

若要驗證和執行範例工作區的查詢，請使用 DEMO_WORKSPACE 作為 {workspace-id} 並傳入 API 金鑰 DEMO_KEY。

如果應用程式識別碼或 API 金鑰不正確，API 服務會傳回 403 (禁止) 錯誤。

根據您要使用標頭、URL 還是基本驗證，API 金鑰 DEMO_KEY 可透過三種不同的方式傳遞：

• 自訂標頭：在自訂標頭 X-Api-Key 中提供 API 金鑰。
• 查詢參數：在 URL 參數 api_key 中提供 API 金鑰。
• 基本驗證：提供 API 金鑰作為使用者名稱或密碼。 如果您同時提供這兩者，API 金鑰就必須位於使用者名稱中。

此範例使用位於標頭中的工作區識別碼和 API 金鑰：

    POST https://api.loganalytics.azure.com/v1/workspaces/DEMO_WORKSPACE/query
    X-Api-Key: DEMO_KEY
    Content-Type: application/json
    
    {
        "query": "AzureActivity | summarize count() by Category"
    }

公用 API 端點

公用 API 端點為：

    https://api.loganalytics.azure.com/{api-version}/workspaces/{workspaceId}

其中：

• api-version：API 版本。 目前的版本為 "v1"。
• workspaceId：您的工作區識別碼。

查詢會在要求本文中傳遞。

例如：

   https://api.loganalytics.azure.com/v1/workspaces/1234abcd-def89-765a-9abc-def1234abcde
   
   Body:
   {
       "query": "Usage"
   }

設定驗證

若要存取 API，請使用 Microsoft Entra ID 註冊用戶端應用程式，並要求權杖。

1. 在 Microsoft Entra ID 中註冊應用程式。

2. 在應用程式的概觀頁面上，選取 [API 權限]。

3. 選取新增權限。

4. 在 [我的組織使用的 API] 索引標籤上搜尋 Log Analytics，然後從清單中選取 [Log Analytics API]。

   

5. 選取委派的權限。

6. 選取 [Data.Read] 核取方塊。

7. 選取新增權限。

   

現在，您的應用程式已註冊並具有使用 API 的權限，請為應用程式授與 Log Analytics 工作區的存取權。

1. 從 Log Analytics 工作區的概觀頁面，選取 [存取控制 (IAM)]。

2. 選取 [新增角色指派]。

   

3. 選取 [讀者] 角色，然後選取 [成員]。

   

4. 在 [成員] 索引標籤上，選擇 [選取成員]。

5. 在 [選取] 方塊中輸入應用程式的名稱。

6. 選取您的應用程式，然後選擇 [選取]。

7. 選取檢閱+指派。

   

8. 在完成 Active Directory 設定和工作區權限作業後，要求授權權杖。

注意

在此範例中，我們套用了讀者角色。 此角色是眾多內建角色之一，可能包含比您所需還要多的權限。 您可以建立更細微的角色和權限。 如需詳細資訊，請參閱管理 Log Analytics 工作區的存取權。

要求授權權杖

開始之前，請確定您具有成功提出要求所需的所有值。 所有要求都需要：

• 您的 Microsoft Entra 租用戶識別碼。
• 您的工作區識別碼。
• 應用程式的 Microsoft Entra 用戶端識別碼。
• 應用程式的 Microsoft Entra 用戶端密碼。

Log Analytics API 支援使用三種不同的 Microsoft Entra ID OAuth2 流程進行 Microsoft Entra 驗證：

• 用戶端認證
• 授權碼
• 隱式

用戶端認證流程

在用戶端認證流程中，權杖會與 Log Analytics 端點搭配使用。 當您在 Microsoft Entra ID 中註冊應用程式時，將會提出單一要求，使用在上一個步驟中為應用程式提供的認證來接收權杖。

使用 resource=https://api.loganalytics.azure.com。

使用下列任何方法來取得驗證權杖：

• CLI
• REST API
• SDK

要求權杖時，您必須提供 resource 參數。 resource 參數是您想要存取的資源的 URL。

這些資源包括：

• https://management.azure.com
• https://api.loganalytics.io
• https://monitoring.azure.com

REST

使用 REST 要求取得權杖

使用下列 REST API 呼叫來取得權杖。 此要求會使用用戶端識別碼和用戶端密碼來驗證要求。 當您向 Microsoft Entra ID 註冊應用程式時，會取得用戶端識別碼和用戶端密碼。 如需詳細資訊，請參閱註冊應用程式以要求授權權杖並使用 API

curl -X POST 'https://login.microsoftonline.com/<tennant ID>/oauth2/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=<your apps client ID>' \
--data-urlencode 'client_secret=<your apps client secret' \
--data-urlencode 'resource=https://monitoring.azure.com'

回應本文會以下列格式出現：

{
    "token_type": "Bearer",
    "expires_in": "86399",
    "ext_expires_in": "86399",
    "expires_on": "1672826207",
    "not_before": "1672739507",
    "resource": "https://monitoring.azure.com",
    "access_token": "eyJ0eXAiOiJKV1Qi....gpHWoRzeDdVQd2OE3dNsLIvUIxQ"
}

CLI

使用 Azure CLI 取得權杖

若要使用 CLI 取得權杖，您可以使用下列命令

az account get-access-token 

如需詳細資訊，請參閱 az account get-access-token

SDK

使用 SDK 取得權杖

下列程式碼範例示範如何使用下列方式來取得權杖：

• C#
• NodeJS
• Python

C#

下列程式碼示範如何使用 Azure 取得權杖。 身分識別程式庫需要用戶端識別碼和用戶端密碼才能驗證要求。

var context = new AuthenticationContext("https://login.microsoftonline.com/<tennant ID>");
var clientCredential = new ClientCredential("<your apps client ID>", "<your apps client secret>");
var result = context.AcquireTokenAsync("https://monitoring.azure.com", clientCredential).Result;

或者，您可以使用 DefaultAzureCredential 類別來取得權杖。 此方法會使用預設的 Azure 認證來驗證要求，而且不需要用戶端識別碼或用戶端密碼。

var credential = new DefaultAzureCredential();
var token = credential.GetToken(new TokenRequestContext(new[] { "https://management.azure.com/.default" }));

您也可以指定受控識別或服務主體認證，如下所示：

string userAssignedClientId = "<your managed identity client ID>";
var credential = new DefaultAzureCredential(
    new DefaultAzureCredentialOptions
    {
        ManagedIdentityClientId = userAssignedClientId
    });

var token = credential.GetToken(new TokenRequestContext(new[] { "https://management.azure.com/.default" }));

如需詳細資訊，請參閱 DefaultAzureCredential 類別

Node.js

如需驗證使用 JavaScript 和 NodeJS 的相關資訊，請參閱如何使用適用於 JavaScript 的 Azure SDK 向 Azure 服務驗證 JavaScript 應用程式

下列程式碼示範如何使用 DefaultAzureCredential 類別來取得權杖。 此方法會使用預設的 Azure 認證來驗證要求，而且不需要用戶端識別碼或用戶端密碼。

const { DefaultAzureCredential } = require("@azure/identity");

const credential = new DefaultAzureCredential();
const accessToken = await credential.getToken("https://management.azure.com/.default");

您也可以使用 InteractiveBrowserCredential 類別來取得認證。 此方法提供瀏覽器型驗證體驗，讓使用者能夠向 Azure 服務進行驗證。

如需詳細資訊，請參閱 DefaultAzureCredential 類別和 InteractiveBrowserCredential 類別

或者，您可以使用 ClientSecretCredential 類別來取得權杖。 此方法需要用戶端識別碼和用戶端密碼才能驗證要求。

const { ClientSecretCredential } = require("@azure/identity");
credential = ClientSecretCredential(
    client_id="<client_id>",
    username="<username>",
    password="<password>"
   )
const accessToken = await credential.getToken("https://management.azure.com/.default");

如需詳細資訊，請參閱 ClientSecretCredential 類別

Python

下列程式碼示範如何使用 DefaultAzureCredential 類別來取得權杖。 此方法會使用預設的 Azure 認證來驗證要求，而且不需要用戶端識別碼或用戶端密碼。

from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()
token = credential.get_token('https://management.azure.com/.default')
print(token.token)

您也可以使用 InteractiveBrowserCredential 類別來取得認證。 此方法提供瀏覽器型驗證體驗，讓使用者能夠向 Azure 服務進行驗證。

如需詳細資訊，請參閱 DefaultAzureCredential 類別和 InteractiveBrowserCredential 類別

或者，您可以使用 ClientSecretCredential 類別來取得權杖。 此方法需要用戶端識別碼和用戶端密碼才能驗證要求。

from azure.identity import ClientSecretCredential

credential = ClientSecretCredential (
     tenant_id="<tenant id>",
     client_id="<Client id>",
     client_secret="client secret"
    )
token =  credential.get_token("https://management.azure.com/.default")
print(token.token)

如需詳細資訊，請參閱 ClientSecretCredential 類別

在對 Log Analytics 端點的要求中使用權杖：

    POST /v1/workspaces/your workspace id/query?timespan=P1D
    Host: https://api.loganalytics.azure.com
    Content-Type: application/json
    Authorization: Bearer <your access token>

    Body:
    {
    "query": "AzureActivity |summarize count() by Category"
    }

範例回應：

    {
        "tables": [
            {
                "name": "PrimaryResult",
                "columns": [
                    {
                        "name": "OperationName",
                        "type": "string"
                    },
                    {
                        "name": "Level",
                        "type": "string"
                    },
                    {
                        "name": "ActivityStatus",
                        "type": "string"
                    }
                ],
                "rows": [
                    [
                        "Metric Alert",
                        "Informational",
                        "Resolved",
                        ...
                    ],
                    ...
                ]
            },
            ...
        ]
    }

授權碼流程

支援的主要 OAuth2 流程是透過授權碼來完成。 此方法需要兩個 HTTP 要求來取得權杖，以呼叫 Azure 監視器 Log Analytics API。 有兩個 URL，每個要求各一個端點。 其格式將於以下幾節說明。

授權碼 URL (GET 要求)

    GET https://login.microsoftonline.com/YOUR_Azure AD_TENANT/oauth2/authorize?
    client_id=<app-client-id>
    &response_type=code
    &redirect_uri=<app-redirect-uri>
    &resource=https://api.loganalytics.io

對授權 URL 提出要求時，client_id 是您 Microsoft Entra 應用程式的應用程式識別碼 (複製自應用程式的屬性功能表)。 redirect_uri 是相同 Microsoft Entra 應用程式的首頁/登入 URL。 要求成功時，此端點會將您重新導向至您在註冊時提供的登入頁面，並將授權碼附加至 URL。 請參閱下列範例：

    http://<app-client-id>/?code=AUTHORIZATION_CODE&session_state=STATE_GUID

此時您已取得授權碼，接下來必須要求存取權杖。

授權碼權杖 URL (POST 要求)

    POST /YOUR_Azure AD_TENANT/oauth2/token HTTP/1.1
    Host: https://login.microsoftonline.com
    Content-Type: application/x-www-form-urlencoded
    
    grant_type=authorization_code
    &client_id=<app client id>
    &code=<auth code fom GET request>
    &redirect_uri=<app-client-id>
    &resource=https://api.loganalytics.io
    &client_secret=<app-client-secret>

所有值都與先前相同，但有一些新增項目。 授權碼是您在成功重新導向之後，於先前要求中收到的相同代碼。 此授權碼會與取自 Microsoft Entra 應用程式的金鑰合併。 如果您未儲存金鑰，則可將其刪除，並從 Microsoft Entra 應用程式功能表的 [金鑰] 索引標籤中建立新金鑰。 回應是一個 JSON 字串，其中包含具有下列結構描述的權杖。 會針對權杖值指出類型。

回應範例：

    {
        "access_token": "eyJ0eXAiOiJKV1QiLCJ.....Ax",
        "expires_in": "3600",
        "ext_expires_in": "1503641912",
        "id_token": "not_needed_for_log_analytics",
        "not_before": "1503638012",
        "refresh_token": "eyJ0esdfiJKV1ljhgYF.....Az",
        "resource": "https://api.loganalytics.io",
        "scope": "Data.Read",
        "token_type": "bearer"
    }

此回應的存取權杖部分是您在 Authorization: Bearer 標頭中，向 Log Analytics API 呈現的內容。 您也可以在未來使用重新整理權杖取得新的 access_token，並在其過期時取得 refresh_token。 針對此要求，格式和端點為：

    POST /YOUR_AAD_TENANT/oauth2/token HTTP/1.1
    Host: https://login.microsoftonline.com
    Content-Type: application/x-www-form-urlencoded
    
    client_id=<app-client-id>
    &refresh_token=<refresh-token>
    &grant_type=refresh_token
    &resource=https://api.loganalytics.io
    &client_secret=<app-client-secret>

回應範例：

    {
      "token_type": "Bearer",
      "expires_in": "3600",
      "expires_on": "1460404526",
      "resource": "https://api.loganalytics.io",
      "access_token": "eyJ0eXAiOiJKV1QiLCJ.....Ax",
      "refresh_token": "eyJ0esdfiJKV1ljhgYF.....Az"
    }

隱含代碼流程

Log Analytics API 支援 OAuth2 隱含流程。 針對此流程只需單一要求，但無法取得任何重新整理權杖。

隱含代碼授權 URL

    GET https://login.microsoftonline.com/YOUR_AAD_TENANT/oauth2/authorize?
    client_id=<app-client-id>
    &response_type=token
    &redirect_uri=<app-redirect-uri>
    &resource=https://api.loganalytics.io

若要求成功，則會使用 URL 中的權杖重新導向至您的重新導向 URI：

    http://YOUR_REDIRECT_URI/#access_token=YOUR_ACCESS_TOKEN&token_type=Bearer&expires_in=3600&session_state=STATE_GUID

傳遞至 Log Analytics API 為要求授權時，此 access_token 可作為 Authorization: Bearer 標頭值。

其他相關資訊

您可以在這裡找到將 OAuth2 用於 Microsoft Entra 的相關文件：

• Microsoft Entra 授權碼流程
• Microsoft Entra 隱含授與流程
• Microsoft Entra S2S 用戶端認證流程

下一步

• 要求格式
• 回應格式
• 查詢 Azure 資源的記錄
• 批次查詢