共用方式為

存取 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]。

    A screenshot that shows the Request API permissions page.

  5. 選取委派的權限。

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

  7. 選取新增權限。

    A screenshot that shows the continuation of the Request API permissions page.

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

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

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

    A screenshot that shows the Access control page for a Log Analytics workspace.

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

    A screenshot that shows the Add role assignment page for a Log Analytics workspace.

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

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

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

  7. 選取檢閱+指派。

    A screenshot that shows the Select members pane on the Add role assignment page for a Log Analytics workspace.

  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 中註冊應用程式時，將會提出單一要求，使用在上一個步驟中為應用程式提供的認證來接收權杖。

請使用 https://api.loganalytics.azure.com 端點。

用戶端認證權杖 URL (POST 要求)

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

成功的要求會在回應中收到存取權杖：

    {
        token_type": "Bearer",
        "expires_in": "86399",
        "ext_expires_in": "86399",
        "access_token": ""eyJ0eXAiOiJKV1QiLCJ.....Ax"
    }

在對 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 的相關文件：

下一步