Referensi konektor data RestApiPoller untuk Kerangka Kerja Konektor Tanpa Kode

Anda dapat membuat konektor data RestApiPoller dengan Codeless Connector Framework (CCF) dengan menggunakan artikel ini sebagai suplemen untuk Microsoft Sentinel REST API untuk konektor data dokumen.

Setiap konektor data mewakili connection tertentu konektor data Microsoft Sentinel. Satu konektor data mungkin memiliki beberapa koneksi, yang mengambil data dari titik akhir yang berbeda. Anda dapat menyelesaikan templat penyebaran untuk konektor data CCF dengan menggunakan konfigurasi JSON yang Anda buat dengan artikel ini.

Untuk informasi selengkapnya, lihat Buat konektor tanpa kode untuk Microsoft Sentinel.

Membuat atau memperbarui konektor data

Temukan versi API stabil atau pratinjau terbaru dengan merujuk create operasi atau update di dokumen REST API. Perbedaan antara create operasi dan update adalah yang update memerlukan etag nilai .

PUT Metode:

https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resourceGroupName}}/providers/Microsoft.OperationalInsights/workspaces/{{workspaceName}}/providers/Microsoft.SecurityInsights/dataConnectors/{{dataConnectorId}}?api-version={{apiVersion}}

Parameter URI

Untuk informasi selengkapnya tentang versi API terbaru, lihat Konektor data: membuat atau memperbarui parameter URI.

Nama	Deskripsi
`dataConnectorId`	ID konektor data. Nama harus unik yang sama `name` dengan parameter dalam isi permintaan.
`resourceGroupName`	Nama grup sumber daya, tidak peka huruf besar/kecil.
`subscriptionId`	ID langganan target.
`workspaceName`	Nama ruang kerja, bukan ID. Pola regex adalah `^[A-Za-z0-9][A-Za-z0-9-]+[A-Za-z0-9]$`.
`api-version`	Versi API yang digunakan untuk operasi ini.

Isi permintaan

Isi permintaan untuk RestApiPoller konektor data CCF memiliki struktur berikut:

{
   "name": "{{dataConnectorId}}",
   "kind": "RestApiPoller",
   "etag": "",
   "properties": {
        "connectorDefinitionName": "",
        "auth": {},
        "request": {},
        "response": {},
        "paging": "",
        "dcrConfig": ""
   }
}

RestApiPoller

RestApiPoller adalah konektor data CCF poller API yang dapat Anda gunakan untuk menyesuaikan payload halaman, otorisasi, dan permintaan/respons untuk sumber data Anda.

Nama	Wajib	Tipe	Deskripsi
`name`	Benar	string	Nama unik koneksi yang cocok dengan parameter URI.
`kind`	Benar	string	Nilai `kind`. Bidang ini harus diatur ke `RestApiPoller`.
`etag`		GUID	Nilai `etag`. Bidang ini harus dibiarkan kosong untuk pembuatan konektor baru. Untuk operasi pembaruan, `etag` harus cocok dengan konektor `etag` (GUID) yang ada.
`properties.connectorDefinitionName`		string	Nama `DataConnectorDefinition` sumber daya yang menentukan konfigurasi UI konektor data. Untuk informasi selengkapnya, buka Definisi konektor data.
`properties.auth`	Benar	JSON berlapis	Properti autentikasi untuk polling data. Untuk informasi selengkapnya, buka Konfigurasi autentikasi.
`properties.request`	Benar	JSON berlapis	Payload permintaan untuk polling data, seperti titik akhir API. Untuk informasi selengkapnya, buka Konfigurasi permintaan.
`properties. response`	Benar	JSON berlapis	Objek respons dan pesan bertumpuk yang dikembalikan API saat melakukan polling data. Untuk informasi selengkapnya, buka Konfigurasi respons.
`properties.paging`		JSON berlapis	Payload penomoran halaman saat melakukan polling data. Untuk informasi selengkapnya, buka Konfigurasi halaman.
`properties.dcrConfig`		JSON berlapis	Parameter yang diperlukan saat data dikirim ke aturan pengumpulan data (DCR). Untuk informasi selengkapnya, buka konfigurasi DCR.

Konfigurasi autentikasi

CCF mendukung jenis autentikasi berikut:

Dasar
Kunci API
OAuth2
JWT

Catatan

Implementasi CCF OAuth2 tidak mendukung kredensial sertifikat klien.

Sebagai praktik terbaik, gunakan parameter di bagian autentikasi alih-alih kredensial hard-coding. Untuk informasi selengkapnya, lihat Mengamankan input rahasia.

Untuk membuat templat penyebaran, yang juga menggunakan parameter, Anda perlu menghindari parameter di bagian ini dengan awal [ekstra . Langkah ini memungkinkan parameter untuk menetapkan nilai berdasarkan interaksi pengguna dengan konektor. Untuk informasi selengkapnya, lihat Ekspresi templat karakter escape.

Untuk mengaktifkan kredensial yang akan dimasukkan dari UI, connectorUIConfig bagian mengharuskan Anda memasukkan parameter yang diinginkan di instructions. Untuk informasi selengkapnya, lihat Referensi definisi konektor data untuk Kerangka Kerja Konektor Tanpa Kode.

Autentikasi dasar

Bidang	Wajib	Tipe
`UserName`	Benar	string
`Password`	Benar	string

Berikut adalah contoh autentikasi dasar yang menggunakan parameter yang ditentukan dalam connectorUIconfig:

"auth": {
    "type": "Basic",
    "UserName": "[[parameters('username')]",
    "Password": "[[parameters('password')]"
}

Kunci API

Bidang	Wajib	Tipe	Deskripsi	Nilai default
`ApiKey`	Benar	string	Kunci rahasia pengguna.
`ApiKeyName`		string	Nama header URI yang berisi `ApiKey` nilai .	`Authorization`
`ApiKeyIdentifier`		string	Nilai string untuk menambahkan token sebelumnya.	`token`
`IsApiKeyInPostPayload`		Boolean	Nilai yang menentukan apakah akan mengirim rahasia dalam isi `POST` , bukan header.	`false`

APIKey contoh autentikasi:

"auth": {
    "type": "APIKey",
    "ApiKey": "[[parameters('apikey')]",
    "ApiKeyName": "X-MyApp-Auth-Header",
    "ApiKeyIdentifier": "Bearer"
}

Hasil dari contoh ini adalah rahasia yang ditentukan dari input pengguna yang dikirim di header berikut: X-MyApp-Auth-Header: Bearer apikey.

"auth": { 
    "type": "APIKey",
    "ApiKey": "123123123",
}

Contoh ini menggunakan nilai default dan menghasilkan header berikut: : Authorizationtoken 123123123.

"auth": { 
    "type": "APIKey",
    "ApiKey": "123123123",
    "ApiKeyName": ""
}

Karena ApiKeyName secara eksplisit diatur ke "", hasilnya adalah header berikut: : Authorization123123123.

OAuth2

Codeless Connector Framework mendukung pemberian kode otorisasi OAuth 2.0 dan kredensial klien. Jenis pemberian Kode Otorisasi digunakan oleh klien rahasia dan publik untuk menukar kode otorisasi dengan token akses.

Setelah pengguna kembali ke klien melalui URL pengalihan, aplikasi akan mendapatkan kode otorisasi dari URL dan menggunakannya untuk meminta token akses.

Bidang	Wajib	Tipe	Deskripsi
`ClientId`	Benar.	string	ID klien.
`ClientSecret`	Benar.	string	Rahasia klien.
`AuthorizationCode`	Benar ketika `grantType` nilainya adalah `authorization_code`.	string	Jika jenis pemberian adalah `authorization_code`, nilai bidang ini adalah kode otorisasi yang dikembalikan server autentikasi.
`Scope`	Benar untuk jenis pemberian `authorization_code` . Opsional untuk jenis pemberian `client_credentials` .	string	Daftar cakupan yang dipisahkan spasi untuk persetujuan pengguna. Untuk informasi selengkapnya, lihat Cakupan dan izin OAuth2.
`RedirectUri`	Benar ketika `grantType` nilainya adalah `authorization_code`.	string	URL untuk pengalihan harus `https://portal.azure.com/TokenAuthorize/ExtensionName/Microsoft_Azure_Security_Insights`.
`GrantType`	Benar.	string	Jenis pemberian. Bisa `authorization_code` atau `client_credentials`.
`TokenEndpoint`	Benar.	string	URL untuk bertukar kode dengan token yang valid dalam pemberian `authorization_code` , atau ID klien dan rahasia dengan token yang valid dalam pemberian `client_credentials` .
`TokenEndpointHeaders`		Objek	Objek kunci/nilai opsional untuk mengirim header kustom ke server token.
`TokenEndpointQueryParameters`		Objek	Objek kunci/nilai opsional untuk mengirim parameter kueri kustom ke server token.
`AuthorizationEndpoint`	Benar.	string	URL untuk persetujuan pengguna untuk `authorization_code` alur.
`AuthorizationEndpointHeaders`		Objek	Objek kunci/nilai opsional untuk mengirim header kustom ke server autentikasi.
`AuthorizationEndpointQueryParameters`		Objek	Pasangan kunci/nilai opsional yang digunakan dalam permintaan alur kode otorisasi OAuth2.

Anda dapat menggunakan alur kode autentikasi untuk mengambil data atas nama izin pengguna. Anda dapat menggunakan kredensial klien untuk mengambil data dengan izin aplikasi. Server data memberikan akses ke aplikasi. Karena tidak ada pengguna dalam alur kredensial klien, tidak ada titik akhir otorisasi yang diperlukan, hanya titik akhir token.

Berikut adalah contoh jenis pemberian OAuth2 authorization_code :

"auth": {
    "type": "OAuth2",
    "ClientId": "[[parameters('appId')]",
    "ClientSecret": "[[parameters('appSecret')]",
    "tokenEndpoint": "https://login.microsoftonline.com/{{tenantId}}/oauth2/v2.0/token",
    "authorizationEndpoint": "https://login.microsoftonline.com/{{tenantId}}/oauth2/v2.0/authorize",
    "authorizationEndpointHeaders": {},
    "authorizationEndpointQueryParameters": {
        "prompt": "consent"
    },
    "redirectUri": "https://portal.azure.com/TokenAuthorize/ExtensionName/Microsoft_Azure_Security_Insights",
    "tokenEndpointHeaders": {
        "Accept": "application/json",
        "Content-Type": "application/x-www-form-urlencoded"
    },
    "TokenEndpointQueryParameters": {},
    "scope": "openid offline_access some_scope",
    "grantType": "authorization_code"
}

Berikut adalah contoh jenis pemberian OAuth2 client_credentials :

"auth": {
    "type": "OAuth2",
    "ClientId": "[[parameters('appId')]",
    "ClientSecret": "[[parameters('appSecret')]",
    "tokenEndpoint": "https://login.microsoftonline.com/{{tenantId}}/oauth2/v2.0/token",
    "tokenEndpointHeaders": {
        "Accept": "application/json",
        "Content-Type": "application/x-www-form-urlencoded"
    },
    "TokenEndpointQueryParameters": {},
    "scope": "openid offline_access some_scope",
    "grantType": "client_credentials"
}

JWT

Autentikasi JSON Web Token (JWT) mendukung perolehan token melalui kredensial nama pengguna dan kata sandi dan menggunakannya untuk permintaan API.

Contoh dasar

"auth": {
    "type": "JwtToken",
    "userName": {
        "key": "username",
        "value": "[[parameters('UserName')]"
    },
    "password": {
        "key": "password", 
        "value": "[[parameters('Password')]"
    },
    "TokenEndpoint": "https://token_endpoint.contoso.com",
    "IsJsonRequest": true,
    "JwtTokenJsonPath": "$.access_token"
}

Kredensial dalam isi POST (default)

"auth": {
    "type": "JwtToken",
    "userName": {
        "key": "username",
        "value": "[[parameters('UserName')]"
    },
    "password": {
        "key": "password",
        "value": "[[parameters('Password')]"
    },
    "TokenEndpoint": "https://api.example.com/token",
    "Headers": {
        "Accept": "application/json",
        "Content-Type": "application/json"
    },
    "IsCredentialsInHeaders": false,
    "IsJsonRequest": true,
    "JwtTokenJsonPath": "$.access_token"
}

Kredensial dalam header (autentikasi dasar)

"auth": {
    "type": "JwtToken",
    "userName": {
        "key": "client_id",
        "value": "[[parameters('ClientId')]"
    },
    "password": {
        "key": "client_secret",
        "value": "[[parameters('ClientSecret')]"
    },
    "TokenEndpoint": "https://api.example.com/oauth/token",
    "Headers": {
        "Accept": "application/json"
    },
    "IsCredentialsInHeaders": true,
    "IsJsonRequest": true,
    "JwtTokenJsonPath": "$.access_token",
    "RequestTimeoutInSeconds": 30
}

Kredensial dalam header (token pengguna)

"auth": {
    "type": "JwtToken",
    "UserToken": "[[parameters('userToken')]",
    "UserTokenPrepend": "Bearer",
    "TokenEndpoint": "https://api.example.com/oauth/token",
    "Headers": {
        "Accept": "application/json"
    },
    "TokenEndpointHttpMethod": "GET",
    "NoAccessTokenPrepend": true,
    "JwtTokenJsonPath": "$.systemToken"
}

Ikuti alur autentikasi ini:

Kirim kredensial ke untuk TokenEndpoint mendapatkan token JWT, saat menggunakan userName dan password, IsCredentialsInHeaders digunakan untuk menentukan tempat meletakkan kredensial dalam permintaan.
- Jika IsCredentialsInHeaders: true: Mengirim header autentikasi dasar dengan username:password.
- Jika IsCredentialsInHeaders: false: Mengirim kredensial dalam isi POST .
Ekstrak token dengan menggunakan JwtTokenJsonPath atau dari header respons.
Header Otorisasi untuk token JWT adalah konstanta dan akan selalu menjadi "Otorisasi".

Bidang	Wajib	Tipe	Deskripsi
`type`	Benar	string	Jenisnya. Harus berupa `JwtToken`
`userName`	True (jika `userToken` tidak digunakan)	Objek	Pasangan kunci/nilai untuk `userName` kredensial. Jika `userName` dan `password` dikirim dalam permintaan header, tentukan `value` properti dengan nama pengguna. Jika `userName` dan `password` dikirim dalam permintaan isi, tentukan `Key` dan `Value`.
`password`	True (jika `userToken` tidak digunakan)	Objek	Pasangan kunci/nilai untuk kredensial kata sandi. Jika `userName` dan `password` dikirim dalam permintaan header, tentukan `value` properti dengan `userName`. Jika `userName` dan `password` dikirim dalam permintaan isi, tentukan `Key` dan `Value`.
`userToken`	True (jika `userName` tidak digunakan)	string	Token pengguna yang dihasilkan oleh klien untuk mendapatkan token sistem untuk autentikasi.
`UserTokenPrepend`	Salah	string	Nilai yang menunjukkan apakah akan menambahkan teks sebelumnya sebelum token. Standar: `Bearer`.
`NoAccessTokenPrepend`	Salah	Boolean	Bendera akses yang menunjukkan bahwa token tidak boleh menambahkan apa pun.
`TokenEndpointHttpMethod`	Salah	string	Metode HTTP untuk titik akhir token. Bisa berupa `Get` atau `Post`. Defaultnya adalah `Post`.
`TokenEndpoint`	Benar	string	Titik akhir URL yang digunakan untuk mendapatkan token JWT.
`IsCredentialsInHeaders`		Boolean	Nilai yang menunjukkan apakah akan mengirim kredensial sebagai header autentikasi dasar (`true`) versus `POST` isi (`false`), diabaikan saat menggunakan `userToken`. Defaultnya adalah `false`.
`IsJsonRequest`		Boolean	Nilai yang menunjukkan apakah akan mengirim permintaan di JSON (header `Content-Type = application/json`) versus dikodekan formulir (header `Content-Type = application/x-www-form-urlencoded`). Defaultnya adalah `false`.
`JwtTokenJsonPath`		string	Nilai yang menunjukkan nilai yang `JSONPath` akan digunakan untuk mengekstrak token dari respons. Misalnya: `$.access_token`.
`JwtTokenInResponseHeader`		Boolean	Nilai yang menunjukkan apakah akan mengekstrak token dari header respons versus isi. Defaultnya adalah `false`.
`JwtTokenHeaderName`.		string	Nilai yang menunjukkan nama header saat token berada di header respons. Defaultnya adalah `Authorization`.
`JwtTokenIdentifier`		string	Pengidentifikasi yang digunakan untuk mengekstrak JWT dari string token awalan.
`QueryParameters`		Objek	Parameter kueri kustom untuk disertakan saat mengirim permintaan ke titik akhir token.
`Headers`		Objek	Header kustom yang akan disertakan saat mengirim permintaan ke titik akhir token.
`RequestTimeoutInSeconds`		Bilangan bulat	Batas waktu permintaan dalam hitung detik. Nilai defaultnya adalah `100`, dengan nilai `180`maksimum .

Catatan

Keterbatasan

Memerlukan autentikasi nama pengguna dan kata sandi untuk akuisisi token
Tidak mendukung permintaan token berbasis kunci API
Tidak mendukung autentikasi header kustom (tanpa nama pengguna dan kata sandi)

Konfigurasi permintaan

Bagian permintaan menentukan bagaimana konektor data CCF mengirim permintaan ke sumber data Anda (misalnya, titik akhir API dan seberapa sering melakukan polling titik akhir tersebut).

Bidang	Wajib	Tipe	Deskripsi
`ApiEndpoint`	Benar.	string	Bidang ini menentukan URL untuk server jarak jauh dan menentukan titik akhir tempat menarik data.
`RateLimitQPS`		Bilangan bulat	Bidang ini menentukan jumlah panggilan atau kueri yang diizinkan dalam detik untuk permintaan awal. Ini tidak berlaku untuk permintaan yang dipaginasi. Untuk membatasi penomoran halaman, atur `PaginatedCallsPerSecond`juga .
`PaginatedCallsPerSecond`		Ganda (0...1000)	Bidang ini menentukan jumlah panggilan per detik yang diizinkan untuk permintaan paginasi ke RESTful API. Ini memperkenalkan penundaan `(1000 / paginatedCallsPerSecond)` milidetik antara setiap panggilan API paginasi. Pembatasan ini hanya berlaku untuk permintaan penomoran halaman dan terpisah dari `RateLimitQPS`, yang mengontrol tingkat permintaan awal. Biasanya, ini akan ditetapkan nilai `RateLimitQPS` yang sama untuk menghormati batas laju sumber data di semua permintaan. `0` nilai berarti tidak ada pembatasan penomoran halaman yang diterapkan.
`RateLimitConfig`		Objek	Bidang ini menentukan konfigurasi batas tarif untuk RESTful API. Untuk informasi selengkapnya, buka `RateLimitConfig` contoh.
`QueryWindowInMin`		Bilangan bulat	Bidang ini menentukan jendela kueri yang tersedia dalam hitung menit. Minimumnya adalah 1 menit. Defaultnya adalah 5 menit.
`HttpMethod`		string	Bidang ini menentukan metode API: `GET`(default) atau `POST`.
`QueryTimeFormat`		string	Bidang ini menentukan format tanggal dan waktu yang diharapkan titik akhir (server jarak jauh). CCF menggunakan tanggal dan waktu saat ini di mana pun variabel ini digunakan. Nilai yang mungkin adalah konstanta: `UnixTimestamp`, , `UnixTimestampInMills`atau representasi tanggal dan waktu lain yang valid. Misalnya: `yyyy-MM-dd`, `MM/dd/yyyy HH:mm:ss`. Defaultnya adalah `ISO 8601 UTC`.
`RetryCount`		Bilangan bulat (1...6)	Bidang ini menentukan bahwa nilai percobaan `16` ulang diizinkan untuk pulih dari kegagalan. Nilai defaultnya adalah `3`.
`TimeoutInSeconds`		Bilangan bulat (1...180)	Bidang ini menentukan batas waktu permintaan dalam hitung detik. Nilai defaultnya adalah `20`.
`IsPostPayloadJson`		Boolean	Bidang ini menentukan apakah `POST` payload dalam format JSON. Nilai defaultnya adalah `false`.
`Headers`		Objek	Bidang ini mencakup pasangan kunci/nilai yang menentukan header permintaan.
`QueryParameters`		Objek	Bidang ini mencakup pasangan kunci/nilai yang menentukan parameter kueri permintaan.
`StartTimeAttributeName`	Benar saat `EndTimeAttributeName` nilai diatur.	string	Bidang ini menentukan nama parameter kueri untuk waktu mulai kueri. Untuk informasi selengkapnya, buka `StartTimeAttributeName` contoh.
`EndTimeAttributeName`	Benar ketika `StartTimeAttributeName` diatur.	string	Bidang ini menentukan nama parameter kueri untuk waktu akhir kueri.
`QueryTimeIntervalAttributeName`		string	Bidang ini digunakan jika titik akhir memerlukan format khusus untuk mengkueri data pada jangka waktu. Gunakan properti ini dengan `QueryTimeIntervalPrepend` parameter dan `QueryTimeIntervalDelimiter` . Untuk informasi selengkapnya, buka `QueryTimeIntervalAttributeName` contoh.
`QueryTimeIntervalPrepend`	Benar ketika `QueryTimeIntervalAttributeName` diatur.	string	Referensi `QueryTimeIntervalAttributeName`.
`QueryTimeIntervalDelimiter`	Benar ketika `QueryTimeIntervalAttributeName` diatur.	string	Referensi `QueryTimeIntervalAttributeName`.
`QueryParametersTemplate`		string	Bidang ini mereferensikan templat kueri yang akan digunakan saat meneruskan parameter dalam skenario tingkat lanjut. Misalnya: `"queryParametersTemplate": "{'cid': 1234567, 'cmd': 'reporting', 'format': 'siem', 'data': { 'from': '{_QueryWindowStartTime}', 'to': '{_QueryWindowEndTime}'}, '{_APIKeyName}': '{_APIKey}'}"`.
`InitialCheckpointTimeUtc`		DateTime (UTC)	Menentukan waktu mulai kueri untuk polling pertama saat tidak ada titik pemeriksaan tersimpan. Setelah titik pemeriksaan dipertahankan setelah polling pertama yang berhasil, nilai ini diabaikan. Pengaturan ini hanya berlaku ketika konfigurasi permintaan konektor menentukan parameter kueri waktu mulai (seperti `startTimeAttributeName` atau `{_QueryWindowStartTime}` token penggantian) tanpa parameter waktu akhir yang sesuai. Ini tidak berpengaruh pada konektor yang hanya mengandalkan kursor atau token penomoran halaman. Format: Tanggalwaktu ISO 8601 UTC (misalnya, `2024-01-15T00:00:00Z`).

Saat API memerlukan parameter kompleks, gunakan queryParameters atau queryParametersTemplate. Perintah ini mencakup beberapa variabel bawaan.

Variabel bawaan	Untuk digunakan di `queryParameters`	Untuk digunakan di `queryParametersTemplate`
`_QueryWindowStartTime`	Yes	Yes
`_QueryWindowEndTime`	Yes	Yes
`_APIKeyName`	No	Yes
`_APIKey`	No	Yes

Contoh StartTimeAttributeName

Pertimbangkan contoh ini:

StartTimeAttributeName = from
EndTimeAttributeName = until
ApiEndpoint = https://www.example.com

Kueri yang dikirim ke server jarak jauh adalah: https://www.example.com?from={QueryTimeFormat}&until={QueryTimeFormat + QueryWindowInMin}.

Contoh QueryTimeIntervalAttributeName

Pertimbangkan contoh ini:

QueryTimeIntervalAttributeName = interval
QueryTimeIntervalPrepend = time:
QueryTimeIntervalDelimiter = ..
ApiEndpoint = https://www.example.com

Kueri yang dikirim ke server jarak jauh adalah: https://www.example.com?interval=time:{QueryTimeFormat}..{QueryTimeFormat + QueryWindowInMin}.

Contoh RateLimitConfig

Pertimbangkan contoh ini:

ApiEndpoint = https://www.example.com.

"rateLimitConfig": {
  "evaluation": {
    "checkMode": "OnlyWhen429"
  },
  "extraction": {
    "source": "CustomHeaders",
    "headers": {
      "limit": {
        "name": "X-RateLimit-Limit",
        "format": "Integer"
      },
      "remaining": {
        "name": "X-RateLimit-Remaining",
        "format": "Integer"
      },
      "reset": {
        "name": "X-RateLimit-RetryAfter",
        "format": "UnixTimeSeconds"
      }
    }
  },
  "retryStrategy": {
    "useResetOrRetryAfterHeaders": true
  }
}

Ketika respons menyertakan header batas laju, konektor dapat menggunakan informasi ini untuk menyesuaikan tingkat permintaannya.

Contoh permintaan yang menggunakan Microsoft Graph sebagai API sumber data

Contoh ini meminta pesan dengan parameter kueri filter. Untuk informasi selengkapnya, lihat parameter kueri Microsoft Graph API.

"request": {
  "apiEndpoint": "https://graph.microsoft.com/v1.0/me/messages",
  "httpMethod": "Get",
  "queryTimeFormat": "yyyy-MM-ddTHH:mm:ssZ",
  "queryWindowInMin": 10,
  "retryCount": 3,
  "rateLimitQPS": 20,
  "headers": {
    "Accept": "application/json",
    "User-Agent": "Example-app-agent"
  },
  "QueryTimeIntervalAttributeName": "filter",
  "QueryTimeIntervalPrepend": "receivedDateTime gt ",
  "QueryTimeIntervalDelimiter": " and receivedDateTime lt "
}

Contoh sebelumnya mengirim GET permintaan ke https://graph.microsoft.com/v1.0/me/messages?filter=receivedDateTime gt {time of request} and receivedDateTime lt 2019-09-01T17:00:00.0000000. Stempel waktu diperbarui untuk setiap queryWindowInMin kali.

Anda mencapai hasil yang sama dengan contoh ini:

"request": {
  "apiEndpoint": "https://graph.microsoft.com/v1.0/me/messages",
  "httpMethod": "Get",
  "queryTimeFormat": "yyyy-MM-ddTHH:mm:ssZ",
  "queryWindowInMin": 10,
  "retryCount": 3,
  "rateLimitQPS": 20,
  "headers": {
    "Accept": "application/json",
  },
  "queryParameters": {
    "filter": "receivedDateTime gt {_QueryWindowStartTime} and receivedDateTime lt {_QueryWindowEndTime}"
  }
}

Ada opsi lain untuk situasi ketika sumber data mengharapkan dua parameter kueri (satu untuk waktu mulai dan satu untuk waktu akhir).

Contoh:

"request": {
  "apiEndpoint": "https://graph.microsoft.com/v1.0/me/calendarView",
  "httpMethod": "Get",
  "queryTimeFormat": "yyyy-MM-ddTHH:mm:ssZ",
  "queryWindowInMin": 10,
  "retryCount": 3,
  "rateLimitQPS": 20,
  "headers": {
    "Accept": "application/json",
  },
  "StartTimeAttributeName": "startDateTime",
  "EndTimeAttributeName": "endDateTime",
}

Opsi ini mengirimkan GET permintaan ke https://graph.microsoft.com/me/calendarView?startDateTime=2019-09-01T09:00:00.0000000&endDateTime=2019-09-01T17:00:00.0000000.

Untuk kueri kompleks, gunakan QueryParametersTemplate. Contoh ini mengirimkan POST permintaan dengan parameter dalam isi:

"request": {
  "apiEndpoint": "https://graph.microsoft.com/v1.0/me/messages",
  "httpMethod": "POST",
  "queryTimeFormat": "yyyy-MM-ddTHH:mm:ssZ",
  "queryWindowInMin": 10,
  "retryCount": 3,
  "rateLimitQPS": 20,
  "headers": {
    "Accept": "application/json",
  },
  "isPostPayloadJson": true,
  "queryParametersTemplate": "{\"query":"TableName | where createdTimestamp between (datetime({_QueryWindowStartTime}) .. datetime({_QueryWindowEndTime}))\"}"
}

Konfigurasi respons

Tentukan bagaimana konektor data Anda menangani respons dengan menggunakan parameter berikut:

Bidang	Wajib	Tipe	Deskripsi
`EventsJsonPaths`	Benar	Daftar untai(karakter)	Menentukan jalur ke pesan dalam JSON respons. Ekspresi jalur JSON menentukan jalur ke elemen, atau sekumpulan elemen, dalam struktur JSON.
`SuccessStatusJsonPath`		string	Menentukan jalur ke pesan berhasil dalam JSON respons. Ketika parameter ini ditentukan, `SuccessStatusValue` parameter juga harus ditentukan.
`SuccessStatusValue`		string	Menentukan jalur ke nilai pesan keberhasilan dalam respons JSON.
`IsGzipCompressed`		Boolean	Menentukan apakah respons dikompresi dalam file GZIP.
`format`	Benar	string	Menentukan apakah formatnya adalah `json`, `csv`, atau `xml`.
`CompressionAlgo`		string	Menentukan algoritma kompresi, baik `multi-gzip` atau `deflate`. Untuk algoritma kompresi GZIP, konfigurasikan `IsGzipCompressed` ke `True` alih-alih mengatur nilai untuk parameter ini.
`CsvDelimiter`		string	Referensi jika format respons adalah CSV dan Anda ingin mengubah pemisah CSV default .`","`
`HasCsvBoundary`		Boolean	Menunjukkan apakah data CSV memiliki batas.
`HasCsvHeader`		Boolean	Menunjukkan apakah data CSV memiliki header. Defaultnya adalah `True`.
`CsvEscape`		string	Menentukan karakter escape untuk batas bidang. Defaultnya adalah `"` Misalnya, CSV dengan header `id,name,avg` dan baris data yang berisi spasi seperti `1,"my name",5.5` memerlukan `"` batas bidang.
`ConvertChildPropertiesToArray`		Boolean	Mereferensikan kasus khusus di mana server jarak jauh mengembalikan objek alih-alih daftar peristiwa di mana setiap properti menyertakan data.

Catatan

Jenis format CSV diurai RFC4180 berdasarkan spesifikasi.

Contoh konfigurasi respons

Respons server dalam format JSON diharapkan. Respons memiliki data yang diminta dalam nilai properti. Status properti respons menunjukkan untuk menyerap data hanya jika nilainya adalah success.

"response": {
  "EventsJsonPaths ": ["$.value"],
  "format": "json",
  "SuccessStatusJsonPath": "$.status",
  "SuccessStatusValue": "success",
  "IsGzipCompressed": true
 }

Respons yang diharapkan dalam contoh ini mempersiapkan CSV tanpa header.

"response": {
  "EventsJsonPaths ": ["$"],
  "format": "csv",
  "HasCsvHeader": false
 }

Konfigurasi penomoran halaman

Ketika sumber data tidak dapat mengirim seluruh payload respons sekaligus, konektor data CCF perlu mengetahui cara menerima bagian data di halaman respons. Jenis halaman yang akan dipilih adalah:

Jenis halaman	Faktor keputusan
`LinkHeader` `PersistentLinkHeader` `NextPageUrl`	Apakah respons API memiliki tautan ke halaman berikutnya dan sebelumnya?
`NextPageToken` `PersistentToken`	Apakah respons API memiliki token atau kursor untuk halaman berikutnya dan sebelumnya?
`Offset`	Apakah respons API mendukung parameter untuk jumlah objek yang akan dilewati saat penomoran halaman?
`CountBasedPaging`	Apakah respons API mendukung parameter untuk jumlah objek yang akan dikembalikan?

Mengonfigurasi LinkHeader atau PersistentLinkHeader

Jenis halaman yang paling umum adalah ketika API sumber data server menyediakan URL ke halaman data berikutnya dan sebelumnya. Untuk informasi selengkapnya tentang spesifikasi Header Tautan , lihat RFC 5988.

LinkHeader halaman berarti respons API mencakup:

Header Link respons HTTP.
Jalur JSON untuk mengambil tautan dari isi respons.

PersistentLinkHeader-type paging memiliki properti yang sama dengan LinkHeader, kecuali header tautan tetap ada di penyimpanan back-end. Opsi ini mengaktifkan tautan halaman di seluruh jendela kueri.

Misalnya, beberapa API tidak mendukung waktu mulai atau waktu akhir kueri. Sebaliknya, mereka mendukung kursor sisi server. Anda dapat menggunakan jenis halaman persisten untuk mengingat kursor sisi server. Untuk informasi selengkapnya, lihat Apa itu kursor?.

Catatan

Hanya satu kueri untuk konektor yang dapat dijalankan untuk PersistentLinkHeader menghindari kondisi balapan di kursor sisi server. Masalah ini dapat memengaruhi latensi.

Bidang	Wajib	Tipe	Deskripsi
`LinkHeaderTokenJsonPath`	Salah	string	Gunakan properti ini untuk menunjukkan tempat mendapatkan nilai dalam isi respons. Misalnya, jika sumber data mengembalikan JSON berikut: `{ nextPage: "foo", value: [{data}]}`, nilainya `LinkHeaderTokenJsonPath` adalah `$.nextPage`.
`PageSize`	Salah	Bilangan bulat	Gunakan properti ini untuk menentukan jumlah peristiwa per halaman.
`PageSizeParameterName`	Salah	string	Gunakan nama parameter kueri ini untuk menunjukkan ukuran halaman.
`PagingInfoPlacement`	Salah	string	Gunakan properti ini untuk menentukan bagaimana info halaman diisi. Menerima baik `QueryString` atau `RequestBody`.
`PagingQueryParamOnly`	Salah	Boolean	Gunakan properti ini untuk menentukan parameter kueri. Jika diatur ke true, ini menghilangkan semua parameter kueri lainnya kecuali parameter kueri halaman.

Berikut adalah beberapa contoh:

"paging": {
  "pagingType": "LinkHeader",
  "linkHeaderTokenJsonPath" : "$.metadata.links.next"
}

"paging": {
 "pagingType" : "PersistentLinkHeader", 
 "pageSizeParameterName" : "limit", 
 "pageSize" : 500 
}

Mengonfigurasi NextPageUrl

NextPageUrl-type paging berarti respons API menyertakan tautan kompleks dalam isi respons yang mirip LinkHeaderdengan , tetapi URL disertakan dalam isi respons alih-alih header.

Bidang	Wajib	Tipe	Deskripsi
`PageSize`	Salah	Bilangan bulat	Jumlah peristiwa per halaman.
`PageSizeParameterName`	Salah	string	Nama parameter kueri untuk ukuran halaman.
`NextPageUrl`	Salah	string	Bidang yang hanya digunakan jika konektor adalah untuk API Coralogix.
`NextPageUrlQueryParameters`	Salah	Objek	Pasangan kunci/nilai yang menambahkan parameter kueri kustom ke setiap permintaan untuk halaman berikutnya.
`NextPageParaName`	Salah	string	Nama halaman berikutnya dalam permintaan.
`HasNextFlagJsonPath`	Salah	string	Jalur ke `HasNextPage` atribut bendera.
`NextPageRequestHeader`	Salah	string	Nama header halaman berikutnya dalam permintaan.
`NextPageUrlQueryParametersTemplate`	Salah	string	Bidang yang hanya digunakan jika konektor adalah untuk API Coralogix.
`PagingInfoPlacement`	Salah	string	Bidang yang menentukan bagaimana info halaman diisi. Menerima baik `QueryString` atau `RequestBody`.
`PagingQueryParamOnly`	Salah	Boolean	Bidang yang menentukan parameter kueri. Jika diatur ke true, ini menghilangkan semua parameter kueri lainnya kecuali parameter kueri halaman.

Contoh:

"paging": {
 "pagingType" : "NextPageUrl", 
  "nextPageTokenJsonPath" : "$.data.repository.pageInfo.endCursor", 
  "hasNextFlagJsonPath" : "$.data.repository.pageInfo.hasNextPage", 
  "nextPageUrl" : "https://api.github.com/graphql", 
  "nextPageUrlQueryParametersTemplate" : "{'query':'query{repository(owner:\"xyz\")}" 
}

Mengonfigurasi NextPageToken atau PersistentToken

NextPageToken-type pagination menggunakan token (hash atau kursor) yang mewakili status halaman saat ini. Token disertakan dalam respons API dan klien menambahkannya ke permintaan berikutnya untuk mengambil halaman berikutnya. Metode ini sering digunakan ketika server perlu mempertahankan status yang tepat di antara permintaan.

PersistentToken pagination menggunakan token yang bertahan di sisi server. Server mengingat token terakhir yang diambil klien dan menyediakan token berikutnya dalam permintaan berikutnya. Klien melanjutkan di mana ia meninggalkan, bahkan jika membuat permintaan baru nanti.

Bidang	Wajib	Tipe	Deskripsi
`PageSize`	Salah	Bilangan bulat	Jumlah peristiwa per halaman.
`PageSizeParameterName`	Salah	string	Nama parameter kueri untuk ukuran halaman.
`NextPageTokenJsonPath`	Salah	string	Jalur JSON untuk token halaman berikutnya dalam isi respons.
`NextPageTokenResponseHeader`	Salah	string	Bidang yang menentukan bahwa jika `NextPageTokenJsonPath` kosong, gunakan token dalam nama header ini untuk halaman berikutnya.
`NextPageParaName`	Salah	string	Bidang yang menentukan nama halaman berikutnya dalam permintaan.
`HasNextFlagJsonPath`	Salah	string	Bidang yang menentukan jalur ke `HasNextPage` atribut bendera saat menentukan apakah lebih banyak halaman dibiarkan dalam respons.
`NextPageRequestHeader`	Salah	string	Bidang yang menentukan nama header halaman berikutnya dalam permintaan.
`PagingInfoPlacement`	Salah	string	Bidang yang menentukan bagaimana info halaman diisi. Menerima baik `QueryString` atau `RequestBody`.
`PagingQueryParamOnly`	Salah	Boolean	Bidang yang menentukan parameter kueri. Jika diatur ke true, ini menghilangkan semua parameter kueri lainnya kecuali parameter kueri halaman.

Contoh:

"paging": {
 "pagingType" : "NextPageToken", 
 "nextPageRequestHeader" : "ETag", 
 "nextPageTokenResponseHeader" : "ETag" 
}

"paging": {
 "pagingType" : "PersistentToken", 
    "nextPageParaName" : "gta", 
    "nextPageTokenJsonPath" : "$.alerts[-1:]._id" 
}

Mengonfigurasi Offset

Offset-type pagination menentukan jumlah halaman yang akan dilewati dan batas jumlah peristiwa yang akan diambil per halaman dalam permintaan. Klien mengambil rentang item tertentu dari himpunan data.

Bidang	Wajib	Tipe	Deskripsi
`PageSize`	Salah	Bilangan bulat	Jumlah peristiwa per halaman.
`PageSizeParameterName`	Salah	string	Nama parameter kueri untuk ukuran halaman.
`OffsetParaName`	Salah	string	Nama parameter kueri permintaan berikutnya. CCF menghitung nilai offset untuk setiap permintaan (semua peristiwa yang diserap + 1).
`PagingInfoPlacement`	Salah	string	Bidang yang menentukan bagaimana info halaman diisi. Menerima baik `QueryString` atau `RequestBody`.
`PagingQueryParamOnly`	Salah	Boolean	Bidang yang menentukan parameter kueri. Jika diatur ke true, ini menghilangkan semua parameter kueri lainnya kecuali parameter kueri halaman.

Contoh:

"paging": {
  "pagingType": "Offset", 
  "offsetParaName": "offset",
  "pageSize": 50,
  "pagingQueryParamOnly": true,
  "pagingInfoPlacement": "QueryString"
}

Mengonfigurasi CountBasedPaging

CountBasedPaging-type pagination memungkinkan klien untuk menentukan jumlah item yang akan dikembalikan dalam respons. Kemampuan ini berguna untuk API yang mendukung penomoran halaman berdasarkan parameter hitungan sebagai bagian dari payload respons.

Bidang	Wajib	Tipe	Deskripsi
`pageNumberParaName`	Benar	string	Nama parameter nomor halaman dalam permintaan HTTP.
`PageSize`	Salah	Bilangan bulat	Jumlah peristiwa per halaman.
`ZeroBasedIndexing`	Salah	Boolean	Bendera yang menunjukkan bahwa jumlahnya berbasis nol.
`HasNextFlagJsonPath`	Salah	string	Jalur JSON bendera dalam payload respons HTTP yang menunjukkan ada lebih banyak halaman.
`TotalResultsJsonPath`	Salah	string	Jalur JSON dari jumlah total hasil dalam payload respons HTTP.
`PageNumberJsonPath`	Salah	string	Jalur JSON dari nomor halaman dalam payload respons HTTP. Diperlukan jika `totalResultsJsonPath` disediakan.
`PageCountJsonPath`	Salah	string	Jalur JSON dari jumlah halaman dalam payload respons HTTP. Diperlukan jika `totalResultsJsonPath` disediakan.
`PagingInfoPlacement`	Salah	string	Bidang yang menentukan bagaimana info halaman diisi. Menerima baik `QueryString` atau `RequestBody`.
`PagingQueryParamOnly`	Salah	Boolean	Bidang yang menentukan parameter kueri. Jika diatur ke true, ini menghilangkan semua parameter kueri lainnya kecuali parameter kueri halaman.

Contoh:

"paging": {
 "pagingType" : "CountBasedPaging", 
 "pageNumberParaName" : "page", 
 "pageSize" : 10, 
 "zeroBasedIndexing" : true, 
 "hasNextFlagJsonPath" : "$.hasNext", 
 "totalResultsJsonPath" : "$.totalResults", 
 "pageNumberJsonPath" : "$.pageNumber", 
 "pageCountJsonPath" : "$.pageCount"
}

Konfigurasi DCR

Bidang	Wajib	Tipe	Deskripsi
`DataCollectionEndpoint`	Benar	string	Titik akhir pengumpulan data (DCE). Misalnya: `https://example.ingest.monitor.azure.com`.
`DataCollectionRuleImmutableId`	Benar	string	ID DCR yang tidak dapat diubah. Temukan dengan melihat respons pembuatan DCR atau dengan menggunakan API DCR.
`StreamName`	Benar	string	Nilai ini adalah yang `streamDeclaration` ditentukan dalam DCR. Awalan harus dimulai dengan `Custom-`.

Contoh konektor data CCF

Berikut adalah contoh semua komponen konektor data CCF JSON:

{
   "kind": "RestApiPoller",
   "properties": {
      "connectorDefinitionName": "ConnectorDefinitionExample",
      "dcrConfig": {
           "streamName": "Custom-ExampleConnectorInput",
           "dataCollectionEndpoint": "https://example-dce-sbsr.location.ingest.monitor.azure.com",
           "dataCollectionRuleImmutableId": "dcr-32_character_hexadecimal_id"
            },
      "dataType": "ExampleLogs",
      "auth": {
         "type": "Basic",
         "password": "[[parameters('username')]",
         "userName": "[[parameters('password')]"
      },
      "request": {
         "apiEndpoint": "https://rest.contoso.com/example",
         "rateLimitQPS": 10,
         "rateLimitConfig": {
            "evaluation": {
              "checkMode": "OnlyWhen429"
            },
            "extraction": {
              "source": "CustomHeaders",
              "headers": {
                "limit": {
                  "name": "X-RateLimit-Limit",
                  "format": "Integer"
                },
                "remaining": {
                  "name": "X-RateLimit-Remaining",
                  "format": "Integer"
                },
                "reset": {
                  "name": "X-RateLimit-RetryAfter",
                  "format": "UnixTimeSeconds"
                }
              }
            },
            "retryStrategy": {
              "useResetOrRetryAfterHeaders": true
            }
         },
         "queryWindowInMin": 5,
         "httpMethod": "POST",
         "queryTimeFormat": "UnixTimestamp",
         "startTimeAttributeName": "t0",
         "endTimeAttributeName": "t1",
         "retryCount": 3,
         "timeoutInSeconds": 60,
         "headers": {
            "Accept": "application/json",
            "User-Agent": "Example-app-agent"
         } 
      },
      "paging": {
         "pagingType": "LinkHeader",
         "pagingInfoPlacement": "RequestBody",
         "pagingQueryParamOnly": true
      },
      "response": {
         "eventsJsonPaths": ["$"]
      }
   }
}

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-03-11

Bagikan melalui

Referensi konektor data RestApiPoller untuk Kerangka Kerja Konektor Tanpa Kode

Membuat atau memperbarui konektor data

Parameter URI

Isi permintaan

RestApiPoller

Konfigurasi autentikasi

Autentikasi dasar

Kunci API

OAuth2

JWT

Contoh dasar

Kredensial dalam isi POST (default)

Kredensial dalam header (autentikasi dasar)

Kredensial dalam header (token pengguna)

Konfigurasi permintaan

Contoh StartTimeAttributeName

Contoh QueryTimeIntervalAttributeName

Contoh RateLimitConfig

Contoh permintaan yang menggunakan Microsoft Graph sebagai API sumber data

Konfigurasi respons

Contoh konfigurasi respons

Konfigurasi penomoran halaman

Mengonfigurasi LinkHeader atau PersistentLinkHeader

Mengonfigurasi NextPageUrl

Mengonfigurasi NextPageToken atau PersistentToken

Mengonfigurasi Offset

Mengonfigurasi CountBasedPaging

Konfigurasi DCR

Contoh konektor data CCF

Saran dan Komentar

Sumber Daya Tambahan: