Mengakses API Log Analytics Azure Monitor

Anda dapat mengirimkan permintaan kueri ke ruang kerja dengan menggunakan titik https://api.loganalytics.azure.comakhir Analitik Log Azure Monitor . Untuk mengakses titik akhir, Anda harus mengautentikasi melalui ID Microsoft Entra.

Catatan

Titik api.loganalytics.io akhir sedang digantikan oleh api.loganalytics.azure.com. Titik api.loganalytics.io akhir akan terus didukung untuk masa mendatang yang dapat dilihat.

Mengautentikasi dengan kunci API demo

Untuk menjelajahi API dengan cepat tanpa autentikasi Microsoft Entra, gunakan ruang kerja demonstrasi dengan data sampel, yang mendukung autentikasi kunci API.

Untuk mengautentikasi dan menjalankan kueri terhadap ruang kerja sampel, gunakan DEMO_WORKSPACE sebagai {workspace-id} dan lewati kunci API DEMO_KEY.

Jika ID Aplikasi atau kunci API salah, layanan API mengembalikan kesalahan 403 (Terlarang).

Kunci API DEMO_KEY dapat diteruskan dengan tiga cara berbeda, tergantung pada apakah Anda ingin menggunakan header, URL, atau autentikasi dasar:

• Header kustom: Berikan kunci API di header X-Api-Keykustom .
• Parameter kueri: Berikan kunci API dalam parameter api_keyURL .
• Autentikasi dasar: Berikan kunci API sebagai nama pengguna atau kata sandi. Jika Anda menyediakan keduanya, kunci API harus ada di nama pengguna.

Contoh ini menggunakan ID ruang kerja dan kunci API di header:

    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"
    }

Titik akhir API Publik

Titik akhir API publik adalah:

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

di mana:

• api-version: Versi API. Versi saat ini adalah "v1."
• workspaceId: ID ruang kerja Anda.

Kueri diteruskan dalam isi permintaan.

Contohnya:

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

Mengonfigurasikan autentikasi

Untuk mengakses API, Anda mendaftarkan aplikasi klien dengan ID Microsoft Entra dan meminta token.

1. Daftarkan aplikasi di ID Microsoft Entra.

2. Pada halaman gambaran umum aplikasi, pilih Izin API.

3. Pilih Tambahkan izin.

4. Pada tab API yang digunakan organisasi saya, cari Log Analytics dan pilih Log Analytics API dari daftar.

   

5. Pilih Izin yang didelegasikan.

6. Pilih kotak centang Data.Read .

7. Pilih Tambahkan izin.

   

Sekarang setelah aplikasi Anda terdaftar dan memiliki izin untuk menggunakan API, berikan aplikasi Anda akses ke ruang kerja Analitik Log Anda.

1. Dari halaman gambaran umum ruang kerja Analitik Log Anda, pilih Kontrol akses (IAM).

2. Pilih Tambahkan penetapan peran.

   

3. Pilih peran Pembaca lalu pilih Anggota.

   

4. Pada tab Anggota , pilih Pilih anggota.

5. Masukkan nama aplikasi Anda di kotak Pilih .

6. Pilih aplikasi Anda dan pilih Pilih.

7. Pilih Tinjau + tetapkan.

   

8. Setelah Anda menyelesaikan penyiapan Direktori Aktif dan izin ruang kerja, minta token otorisasi.

Catatan

Untuk contoh ini, kami menerapkan peran Pembaca. Peran ini adalah salah satu dari banyak peran bawaan dan mungkin menyertakan lebih banyak izin daripada yang Anda butuhkan. Peran dan izin yang lebih terperinci dapat dibuat. Untuk informasi selengkapnya, lihat Mengelola akses ke ruang kerja Analitik Log.

Meminta token otorisasi

Sebelum memulai, pastikan Anda memiliki semua nilai yang diperlukan untuk membuat permintaan berhasil. Semua permintaan memerlukan:

• ID penyewa Microsoft Entra Anda.
• ID ruang kerja Anda.
• ID klien Microsoft Entra Anda untuk aplikasi.
• Rahasia klien Microsoft Entra untuk aplikasi.

API Analitik Log mendukung autentikasi Microsoft Entra dengan tiga alur Microsoft Entra ID OAuth2 yang berbeda:

• Informasi masuk klien
• Kode otorisasi
• Implisit

Alur Info masuk Klien

Dalam alur kredensial klien, token digunakan dengan titik akhir Analitik Log. Satu permintaan dibuat untuk menerima token dengan menggunakan kredensial yang disediakan untuk aplikasi Anda di langkah sebelumnya saat Anda mendaftarkan aplikasi di ID Microsoft Entra.

Gunakan resource=https://api.loganalytics.azure.com.

Dapatkan token autentikasi menggunakan salah satu metode berikut:

• CLI
• REST API
• SDK

Saat meminta token, Anda harus memberikan resource parameter. Parameter resource adalah URL sumber daya yang ingin Anda akses.

Sumber daya meliputi:

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

REST

Mendapatkan token menggunakan permintaan REST

Gunakan panggilan REST API berikut untuk mendapatkan token. Permintaan ini menggunakan ID klien dan rahasia klien untuk mengautentikasi permintaan. ID klien dan rahasia klien diperoleh saat Anda mendaftarkan aplikasi Anda dengan ID Microsoft Entra. Untuk informasi selengkapnya, lihat Mendaftarkan Aplikasi untuk meminta token otorisasi dan bekerja dengan 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'

Isi respons muncul dalam format berikut:

{
    "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

Mendapatkan token menggunakan Azure CLI

Untuk mendapatkan token menggunakan CLI, Anda bisa menggunakan perintah berikut

az account get-access-token 

Untuk informasi selengkapnya, lihat az account get-access-token

SDK

Mendapatkan token menggunakan SDK

Sampel kode berikut menunjukkan cara mendapatkan token menggunakan:

• C#
• NodeJS
• Python

C#

Kode berikut menunjukkan cara mendapatkan token menggunakan Azure. Pustaka identitas Ini memerlukan ID klien dan rahasia klien untuk mengautentikasi permintaan.

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;

Atau, Anda dapat menggunakan kelas DefaultAzureCredential untuk mendapatkan token. Metode ini menggunakan kredensial Azure default untuk mengautentikasi permintaan dan tidak memerlukan ID klien atau rahasia klien.

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

Anda juga dapat menentukan identitas terkelola atau kredensial perwakilan layanan Anda sebagai berikut:

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" }));

Untuk informasi selengkapnya, lihat Kelas DefaultAzureCredential

Node.js

Untuk informasi tentang autentikasi menggunakan JavaScript dan NodeJS, lihat Cara mengautentikasi aplikasi JavaScript ke layanan Azure menggunakan Azure SDK for JavaScript

Kode berikut menunjukkan cara mendapatkan token menggunakan kelas DefaultAzureCredential. Metode ini menggunakan kredensial Azure default untuk mengautentikasi permintaan dan tidak memerlukan ID klien atau rahasia klien.

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

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

Anda juga dapat menggunakan InteractiveBrowserCredential kelas untuk mendapatkan kredensial. Metode ini memberikan pengalaman autentikasi berbasis browser bagi pengguna untuk mengautentikasi dengan layanan Azure.

Untuk informasi selengkapnya, lihat Kelas DefaultAzureCredential dan Kelas InteractiveBrowserCredential

Atau Anda dapat menggunakan kelas ClientSecretCredential untuk mendapatkan token. Metode ini memerlukan ID klien dan rahasia klien untuk mengautentikasi permintaan.

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");

Untuk informasi selengkapnya, lihat Kelas ClientSecretCredential

Python

Kode berikut menunjukkan cara mendapatkan token menggunakan kelas DefaultAzureCredential. Metode ini menggunakan kredensial Azure default untuk mengautentikasi permintaan dan tidak memerlukan ID klien atau rahasia klien.

from azure.identity import DefaultAzureCredential

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

Anda juga dapat menggunakan InteractiveBrowserCredential kelas untuk mendapatkan kredensial. Metode ini memberikan pengalaman autentikasi berbasis browser bagi pengguna untuk mengautentikasi dengan layanan Azure.

Untuk informasi selengkapnya, lihat Kelas DefaultAzureCredential dan Kelas InteractiveBrowserCredential

Atau Anda dapat menggunakan kelas ClientSecretCredential untuk mendapatkan token. Metode ini memerlukan ID klien dan rahasia klien untuk mengautentikasi permintaan.

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)

Untuk informasi selengkapnya, lihat Kelas ClientSecretCredential

Gunakan token dalam permintaan ke titik akhir Analitik Log:

    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"
    }

Contoh respons:

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

Alur kode otorisasi

Aliran OAuth2 utama yang didukung adalah melalui kode otorisasi. Metode ini memerlukan dua permintaan HTTP untuk memperoleh token untuk memanggil API Analitik Log Azure Monitor. Ada dua URL, dengan satu titik akhir per permintaan. Formatnya dijelaskan di bagian berikut.

URL kode otorisasi (permintaan 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

Saat permintaan dibuat ke URL otorisasi, client_id adalah ID aplikasi dari aplikasi Microsoft Entra Anda, yang disalin dari menu properti aplikasi. redirect_uri adalah URL beranda/login dari aplikasi Microsoft Entra yang sama. Ketika permintaan berhasil, titik akhir ini mengarahkan Anda ke halaman masuk yang Anda berikan saat mendaftar dengan kode otorisasi yang ditambahkan ke URL. Lihat contoh berikut:

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

Pada titik ini, Anda telah mendapatkan kode otorisasi, yang Anda butuhkan sekarang untuk meminta token akses.

URL token kode otorisasi (permintaan 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>

Semua nilai sama seperti sebelumnya, dengan beberapa tambahan. Kode otorisasi adalah kode yang sama dengan yang Anda terima dalam permintaan sebelumnya setelah pengalihan berhasil. Kode dikombinasikan dengan kunci yang diperoleh dari aplikasi Microsoft Entra. Jika Anda tidak menyimpan kunci, Anda dapat menghapusnya dan membuat kunci baru dari tab kunci menu aplikasi Microsoft Entra. Responsnya adalah string JSON yang berisi token dengan skema berikut. Jenis ditunjukkan untuk nilai token.

Contoh respons:

    {
        "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"
    }

Bagian token akses dari respons ini adalah apa yang Anda sajikan kepada API Analitik Log di header Authorization: Bearer. Anda juga dapat menggunakan token refresh di masa mendatang untuk memperoleh access_token baru dan refresh_token ketika token Anda telah basi. Untuk permintaan ini, format dan titik akhir adalah:

    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>

Contoh respons:

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

Alur kode implisit

API Analitik Log mendukung alur implisit OAuth2. Untuk alur ini, hanya satu permintaan yang diperlukan, tetapi tidak ada token refresh yang dapat diperoleh.

URL otorisasi kode implisit

    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

Permintaan yang berhasil menghasilkan pengalihan ke URI pengalihan Anda dengan token di URL:

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

Access_token ini dapat digunakan sebagai Authorization: Bearer nilai header saat diteruskan ke API Analitik Log untuk mengotorisasi permintaan.

Informasi selengkapnya

Anda dapat menemukan dokumentasi tentang OAuth2 dengan Microsoft Entra di sini:

• Alur kode otorisasi Microsoft Entra
• Alur pemberian implisit Microsoft Entra
• Alur kredensial klien Microsoft Entra S2S

Langkah berikutnya

• Format permintaan
• Format respons
• Mengkueri log untuk sumber daya Azure
• Kueri batch