Dokumentacja łącznika danych RestApiPoller dla platformy łącznika bez kodu

Artykuł
10/01/2024

Aby utworzyć RestApiPoller łącznik danych za pomocą platformy łącznika bez kodu (KPCH), użyj tego odwołania jako dodatku do dokumentacji interfejsu API REST usługi Microsoft Sentinel dla łączników danych.

Każdy dataConnector reprezentuje określone połączenie łącznika danych usługi Microsoft Sentinel. Jeden łącznik danych może mieć wiele połączeń, które pobierają dane z różnych punktów końcowych. Konfiguracja JSON utworzona przy użyciu tego dokumentu referencyjnego służy do ukończenia szablonu wdrożenia dla łącznika danych INTERFEJSu API.

Aby uzyskać więcej informacji, zobacz Tworzenie łącznika bez kodu dla usługi Microsoft Sentinel.

Łączniki danych — tworzenie lub aktualizowanie

Zapoznaj się z dokumentacją tworzenia lub aktualizowania w dokumentacji interfejsu API REST, aby znaleźć najnowszą stabilną lub zapoznawczą wersję interfejsu API. Różnica między operacją tworzenia i aktualizacji polega na tym, że aktualizacja wymaga wartości elementu etag .

PUT , metoda

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

Parametry identyfikatora URI

Aby uzyskać więcej informacji na temat najnowszej wersji interfejsu API, zobacz Łączniki danych — tworzenie lub aktualizowanie parametrów identyfikatora URI.

Nazwa/nazwisko	opis
dataConnectorId	Identyfikator łącznika danych musi być unikatową nazwą i jest taki sam jak `name` parametr w treści żądania.
resourceGroupName	Nazwa grupy zasobów, a nie uwzględnia wielkości liter.
subscriptionId	Identyfikator subskrypcji docelowej.
workspaceName	Nazwa obszaru roboczego, a nie identyfikator. Wzorzec wyrażenia regularnego: `^[A-Za-z0-9][A-Za-z0-9-]+[A-Za-z0-9]$`
wersja interfejsu API	Wersja interfejsu API do użycia dla tej operacji.

Treść żądania

Treść żądania dla łącznika RestApiPoller danych PROTOKOŁU KPCH ma następującą strukturę:

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

RestApiPoller

RestApiPoller reprezentuje łącznik danych API Poller TRANSLATOR DANYCH, w którym można dostosować ładunki stronicowania, autoryzacji i żądania/odpowiedzi dla źródła danych.

Nazwisko	Wymagania	Type	opis
name	Prawda	string	Unikatowa nazwa połączenia zgodnego z parametrem identyfikatora URI
rodzaj	Prawda	string	Musi być `RestApiPoller`
etag		Identyfikator GUID	Pozostaw wartość pustą do utworzenia nowych łączników. W przypadku operacji aktualizacji element etag musi być zgodny z identyfikatorem etag istniejącego łącznika (GUID).
properties.connectorDefinitionName		string	Nazwa zasobu DataConnectorDefinition definiującego konfigurację interfejsu użytkownika łącznika danych. Aby uzyskać więcej informacji, zobacz Definicja łącznika danych.
Właściwości.Auth	Prawda	Zagnieżdżony kod JSON	Opisuje właściwości uwierzytelniania do sondowania danych. Aby uzyskać więcej informacji, zobacz Konfiguracja uwierzytelniania.
Właściwości.prosić	Prawda	Zagnieżdżony kod JSON	Opisuje ładunek żądania do sondowania danych, takich jak punkt końcowy interfejsu API. Aby uzyskać więcej informacji, zobacz konfiguracja żądania.
Właściwości.odpowiedź	Prawda	Zagnieżdżony kod JSON	Opisuje obiekt odpowiedzi i zagnieżdżony komunikat zwrócony z interfejsu API podczas sondowania danych. Aby uzyskać więcej informacji, zobacz konfiguracja odpowiedzi.
Właściwości.stronicowanie		Zagnieżdżony kod JSON	Opisuje ładunek stronicowania podczas sondowania danych. Aby uzyskać więcej informacji, zobacz Konfiguracja stronicowania.
Właściwości.dcrConfig		Zagnieżdżony kod JSON	Wymagane parametry, gdy dane są wysyłane do reguły zbierania danych (DCR). Aby uzyskać więcej informacji, zobacz Konfiguracja kontrolera domeny.

Konfiguracja uwierzytelniania

Funkcja TRANSLATOR obsługuje następujące typy uwierzytelniania:

Podstawowa
ApiKey
OAuth2
Jwt

Uwaga

Implementacja protokołu OAuth2 PROTOKOŁU OAUTH2 nie obsługuje poświadczeń certyfikatu klienta.

Najlepszym rozwiązaniem jest użycie parametrów w sekcji uwierzytelniania zamiast poświadczeń kodowania na stałe. Aby uzyskać więcej informacji, zobacz Zabezpieczanie poufnych danych wejściowych.

Aby utworzyć szablon wdrożenia, który używa również parametrów, należy poznać parametry w tej sekcji z dodatkowym początkowym elementem [. Dzięki temu parametry mogą przypisywać wartość na podstawie interakcji użytkownika z łącznikiem. Aby uzyskać więcej informacji, zobacz Znaki ucieczki wyrażeń szablonu.

Aby umożliwić podanie poświadczeń z interfejsu użytkownika, connectorUIConfig sekcja wymaga instructions odpowiednich parametrów. Aby uzyskać więcej informacji, zobacz Dokumentacja definicji łącznika danych dla platformy łącznika bez kodu.

Uwierzytelnianie podstawowe

Pole	Wymagania	Typ
UserName	Prawda	string
Hasło	Prawda	string

Przykład uwierzytelniania podstawowego przy użyciu parametrów zdefiniowanych w programie connectorUIconfig:

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

ApiKey

Pole	Wymagania	Type	Opis	Domyślna wartość
ApiKey	Prawda	string	klucz tajny użytkownika
ApiKeyName		string	nazwa nagłówka identyfikatora URI zawierającego wartość ApiKey	`Authorization`
ApiKeyIdentifier		string	wartość ciągu, aby wstępnie otworzyć token	`token`
IsApiKeyInPostPayload		boolean	wysyłanie wpisu tajnego w treści POST zamiast nagłówka	`false`

Przykłady uwierzytelniania interfejsu APIKey:

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

Ten przykład powoduje wpis tajny zdefiniowany z danych wejściowych użytkownika wysyłanych w następującym nagłówku: X-MyApp-Auth-Header: Bearer apikey

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

W tym przykładzie użyto wartości domyślnych i zostanie przedstawiony następujący nagłówek: Autoryzacja: token 123123123

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

Ponieważ parametr ApiKeyName jest jawnie ustawiony na ""wartość , wynikiem jest następujący nagłówek: Autoryzacja: 123123123

OAuth2

Platforma łącznika bez kodu obsługuje udzielanie kodu autoryzacji OAuth 2.0 i poświadczenia klienta. Typ udzielania kodu autoryzacji jest używany przez poufnych i publicznych klientów do wymiany kodu autoryzacji dla tokenu dostępu. Po powrocie użytkownika do klienta za pośrednictwem adresu URL przekierowania aplikacja pobierze kod autoryzacji z adresu URL i użyje go do żądania tokenu dostępu.

Pole	Wymagania	Type	Opis
ClientId	Prawda	String	Identyfikator klienta
ClientSecret	Prawda	String	Klucz tajny klienta
Kod autoryzacji	Wartość true, gdy grantType = `authorization_code`	String	Jeśli typem udzielenia jest `authorization_code` ta wartość pola, będzie kod autoryzacji zwrócony z usługi uwierzytelniania.
Scope	True dla typu udzielenia `authorization_code` opcjonalnie dla typu udzielenia `client_credentials`	String	Rozdzielona spacjami lista zakresów dla zgody użytkownika. Aby uzyskać więcej informacji, zobacz Zakresy i uprawnienia OAuth2.
Identyfikator Przekierowanie	Wartość true, gdy grantType = `authorization_code`	String	Adres URL przekierowania musi mieć wartość `https://portal.azure.com/TokenAuthorize/ExtensionName/Microsoft_Azure_Security_Insights`
GrantType	Prawda	String	`authorization_code` lub `client_credentials`
TokenEndpoint	Prawda	String	Adres URL wymiany kodu z prawidłowym tokenem w `authorization_code` ramach udzielenia lub identyfikatora klienta i wpisu tajnego z prawidłowym tokenem w `client_credentials` przyznaniu.
TokenEndpointHeaders		Objekt	Opcjonalny obiekt wartości klucza do wysyłania niestandardowych nagłówków do serwera tokenów
TokenEndpointQueryParameters		Objekt	Opcjonalny obiekt wartości klucza do wysyłania parametrów zapytania niestandardowego do serwera tokenów
AuthorizationEndpoint	Prawda	String	Adres URL zgody użytkownika na `authorization_code` przepływ
AuthorizationEndpointHeaders		Objekt	Opcjonalny obiekt wartości klucza do wysyłania nagłówków niestandardowych do serwera uwierzytelniania
AuthorizationEndpointQueryParameters		Objekt	Opcjonalna para wartości klucza używana w żądaniu przepływu kodu autoryzacji OAuth2

Przepływ kodu uwierzytelniania służy do pobierania danych w imieniu uprawnień użytkownika, a poświadczenia klienta są przeznaczone do pobierania danych z uprawnieniami aplikacji. Serwer danych udziela dostępu do aplikacji. Ponieważ w przepływie poświadczeń klienta nie ma żadnego użytkownika, nie jest wymagany żaden punkt końcowy autoryzacji, tylko punkt końcowy tokenu.

Przykład: typ udzielania protokołu 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"
}

Przykład: typ udzielania protokołu 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

Przykład: token internetowy JSON (JWT)

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

Konfiguracja żądania

Sekcja żądania definiuje sposób wysyłania żądań do źródła danych przez łącznik DANYCH PROTOKOŁU KPCH, takich jak punkt końcowy interfejsu API i częstotliwość sondowania tego punktu końcowego.

Pole	Wymagania	Type	Opis
Punkt końcowy interfejsu API	Prawda	String	Adres URL serwera zdalnego. Definiuje punkt końcowy do ściągania danych.
RateLimitQPS		Integer	Definiuje liczbę wywołań lub zapytań dozwolonych w ciągu sekundy.
ZapytanieWindowInMin		Integer	Definiuje dostępne okno zapytania w ciągu kilku minut. Minimalna wartość to 1 minuta. Wartość domyślna to 5 minut.
HttpMethod		String	Definiuje metodę interfejsu API: `GET`(wartość domyślna) lub `POST`
QueryTimeFormat		String	Definiuje format daty i godziny oczekiwany przez punkt końcowy (serwer zdalny). FUNKCJA KPCH używa bieżącej daty i godziny, gdzie jest używana ta zmienna. Możliwe wartości to stałe: `UnixTimestamp`, `UnixTimestampInMills` lub dowolna inna prawidłowa reprezentacja daty i godziny, na przykład: `yyyy-MM-dd`, `MM/dd/yyyy HH:mm:ss` wartość domyślna to ISO 8601 UTC
RetryCount		Liczba całkowita (1...6)	Definiuje `1` , aby ponawiać `6` próby, które mogą odzyskać po awarii. Wartość domyślna to `3`.
Limit czasuInSeconds		Liczba całkowita (1...180)	Definiuje limit czasu żądania w sekundach. Wartość domyślna to `20`
IsPostPayloadJson		Wartość logiczna	Określa, czy ładunek POST jest w formacie JSON. Wartość domyślna to `false`
Nagłówki		Objekt	Pary klucz-wartość definiujące nagłówki żądania.
Parametry zapytań		Objekt	Pary klucz-wartość definiujące parametry zapytania żądania.
StartTimeAttributeName	Prawda, gdy `EndTimeAttributeName` jest ustawiona	String	Definiuje nazwę parametru zapytania dla czasu rozpoczęcia zapytania. Zobacz przykład.
EndTimeAttributeName	Prawda, gdy `StartTimeAttributeName` jest ustawiona	String	Definiuje nazwę parametru zapytania dla czasu zakończenia zapytania.
QueryTimeIntervalAttributeName		String	Jeśli punkt końcowy wymaga wyspecjalizowanego formatu do wykonywania zapytań dotyczących danych w przedziale czasu, użyj tej właściwości z parametrami `QueryTimeIntervalPrepend` i `QueryTimeIntervalDelimiter` . Zobacz przykład.
QueryTimeIntervalPrepend	Prawda, gdy `QueryTimeIntervalAttributeName` jest ustawiona	String	Zobacz `QueryTimeIntervalAttributeName`
QueryTimeIntervalDelimiter	Prawda, gdy `QueryTimeIntervalAttributeName` jest ustawiona	String	Zobacz `QueryTimeIntervalAttributeName`
QueryParametersTemplate		String	Szablon zapytania do użycia podczas przekazywania parametrów w zaawansowanych scenariuszach. br>Na przykład: `"queryParametersTemplate": "{'cid': 1234567, 'cmd': 'reporting', 'format': 'siem', 'data': { 'from': '{_QueryWindowStartTime}', 'to': '{_QueryWindowEndTime}'}, '{_APIKeyName}': '{_APIKey}'}"`

Jeśli interfejs API wymaga złożonych parametrów, użyj queryParameters wartości lub queryParametersTemplate , która zawiera pewne wbudowane zmienne.

wbudowana zmienna	do użycia w `queryParameters`	do użycia w `queryParametersTemplate`
`_QueryWindowStartTime`	tak	tak
`_QueryWindowEndTime`	tak	tak
`_APIKeyName`	nie	tak
`_APIKey`	nie	tak

Przykład startTimeAttributeName

Rozważ taki przykład:

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

Zapytanie wysyłane do serwera zdalnego to: https://www.example.com?from={QueryTimeFormat}&until={QueryTimeFormat + QueryWindowInMin}

Przykład QueryTimeIntervalAttributeName

Rozważ taki przykład:

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

Zapytanie wysyłane do serwera zdalnego to: https://www.example.com?interval=time:{QueryTimeFormat}..{QueryTimeFormat + QueryWindowInMin}

Przykłady żądań przy użyciu programu Microsoft Graph jako interfejsu API źródła danych

Ten przykład wysyła zapytania do komunikatów z parametrem zapytania filtru. Aby uzyskać więcej informacji, zobacz Parametry zapytania interfejsu API programu Microsoft Graph.

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

Poprzedni przykład wysyła GET żądanie do https://graph.microsoft.com/v1.0/me/messages?filter=receivedDateTime gt {time of request} and receivedDateTime lt 2019-09-01T17:00:00.0000000. Znacznik czasu jest aktualizowany za każdym queryWindowInMin razem.

Te same wyniki są osiągane w tym przykładzie:

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

Inną opcją jest to, gdy źródło danych oczekuje 2 parametrów zapytania, jeden dla czasu rozpoczęcia i jeden dla czasu zakończenia.

Przykład:

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

Spowoduje to wysłanie GET żądania do https://graph.microsoft.com/me/calendarView?startDateTime=2019-09-01T09:00:00.0000000&endDateTime=2019-09-01T17:00:00.0000000

W przypadku złożonych zapytań użyj polecenia QueryParametersTemplate. W następnym przykładzie jest wysyłane POST żądanie z parametrami w treści.

Przykład:

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

Konfiguracja odpowiedzi

Zdefiniuj obsługę odpowiedzi łącznika danych przy użyciu następujących parametrów:

Pole	Wymagania	Type	Opis
EventsJsonPaths	Prawda	Lista ciągów	Definiuje ścieżkę do komunikatu w formacie JSON odpowiedzi. Wyrażenie ścieżki JSON określa ścieżkę do elementu lub zestawu elementów w strukturze JSON
SuccessStatusJsonPath		String	Definiuje ścieżkę do komunikatu o powodzeniu w formacie JSON odpowiedzi. Po zdefiniowaniu tego parametru `SuccessStatusValue` należy również zdefiniować parametr .
SuccessStatusValue		String	Definiuje ścieżkę do wartości komunikatu o powodzeniu w formacie JSON odpowiedzi
IsGzipCompressed		Wartość logiczna	Określa, czy odpowiedź jest kompresowana w pliku gzip
format	Prawda	String	`json`lub lub `csvxml`
KompresjaAlgo		String	Algorytm kompresji lub `multi-gzip` `deflate`. W przypadku algorytmu kompresji gzip wystarczy skonfigurować `IsGzipCompressed` wartość , aby zamiast ustawiać `True` wartość dla tego parametru.
CsvDelimiter		String	Jeśli format odpowiedzi to CSV i chcesz zmienić domyślny ogranicznik CSV `","`
HasCsvBoundary		Wartość logiczna	Wskazuje, czy dane CSV mają granicę
HasCsvHeader		Wartość logiczna	Wskazuje, czy dane CSV mają nagłówek, wartość domyślna to `True`
CsvEscape		String	Znak ucieczki dla granicy pola, wartość domyślna to `"` Na przykład plik CSV z nagłówkami i wierszem danych zawierających spacje `id,name,avg` , takie jak `1,"my name",5.5` wymaga `"` granicy pola.
ConvertChildPropertiesToArray		Wartość logiczna	Szczególny przypadek, w którym serwer zdalny zwraca obiekt zamiast listy zdarzeń, w których każda właściwość zawiera dane.

Uwaga

Typ formatu CSV jest analizowany przez specyfikację RFC4180 .

Przykłady konfiguracji odpowiedzi

Oczekiwana jest odpowiedź serwera z formatem JSON z żądanymi danymi w wartości właściwości. Stan właściwości odpowiedzi wskazuje pozyskiwanie danych tylko wtedy, gdy wartość to success.

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

Oczekiwana odpowiedź w tym przykładzie przygotowuje się do pliku CSV bez nagłówka.

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

Konfiguracja stronicowania

Gdy źródło danych nie może wysłać całego ładunku odpowiedzi jednocześnie, łącznik danych USŁUGI KPS musi wiedzieć, jak odbierać fragmenty danych na stronach odpowiedzi. Typy stronicowania do wyboru to:

Typ stronicowania	czynnik decyzyjny
LinkHeader PersistentLinkHeader NextPageUrl	Czy odpowiedź interfejsu API zawiera linki do następnych i poprzednich stron?
NextPageToken Trwałetoken	Czy odpowiedź interfejsu API ma token lub kursor dla następnych i poprzednich stron?
Przesunięcie	Czy odpowiedź interfejsu API obsługuje parametr liczby obiektów do pominięcia podczas stronicowania?

Konfigurowanie elementu LinkHeader lub PersistentLinkHeader

Najczęstszym typem stronicowania jest to, że interfejs API źródła danych serwera udostępnia adresy URL następnym i poprzednim stronom danych. Aby uzyskać więcej informacji na temat specyfikacji nagłówka linku, zobacz RFC 5988.

LinkHeader stronicowanie oznacza, że odpowiedź interfejsu API obejmuje:

Link nagłówek odpowiedzi HTTP
lub ścieżka JSON w celu pobrania linku z treści odpowiedzi.

PersistentLinkHeader stronicowanie ma te same właściwości co , z wyjątkiem tego, że LinkHeadernagłówek łącza jest utrwalany w magazynie zaplecza. Ta opcja umożliwia stronicowanie łączy w oknach zapytań. Na przykład niektóre interfejsy API nie obsługują czasów rozpoczęcia zapytania ani czasów zakończenia. Zamiast tego obsługują kursor po stronie serwera. Trwałe typy stron mogą służyć do zapamiętania kursora po stronie serwera. Aby uzyskać więcej informacji, zobacz Co to jest kursor?.

Uwaga

Dla łącznika może być uruchomione tylko jedno zapytanie z funkcją PersistentLinkHeader, aby uniknąć warunków wyścigu na kursorze po stronie serwera. Może to mieć wpływ na opóźnienie.

Pole	Wymagania	Type	Opis
LinkHeaderTokenJsonPath	Fałsz	String	Użyj tej właściwości, aby wskazać, gdzie uzyskać wartość w treści odpowiedzi. Jeśli na przykład źródło danych zwróci następujący kod JSON: `{ nextPage: "foo", value: [{data}]}` `LinkHeaderTokenJsonPath` będzie to `$.nextPage`
Pagesize	Fałsz	Integer	Ile zdarzeń na stronę
PageSizeParameterName	Fałsz	String	Nazwa parametru zapytania dla rozmiaru strony

Oto kilka przykładów:

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

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

Konfigurowanie elementu NextPageUrl

NextPageUrl stronicowanie oznacza, że odpowiedź interfejsu API zawiera złożony link w treści odpowiedzi podobny do LinkHeader, ale adres URL znajduje się w treści odpowiedzi zamiast nagłówka.

Pole	Wymagania	Type	Opis
Pagesize	Fałsz	Integer	Ile zdarzeń na stronę
PageSizeParameterName	Fałsz	String	Nazwa parametru zapytania dla rozmiaru strony
NextPageUrl	Fałsz	String	Tylko wtedy, gdy łącznik jest przeznaczony dla interfejsu API Platformy Coralogix
NextPageUrlQueryParameters	Fałsz	Pary wartości klucza obiektu — dodawanie niestandardowego parametru zapytania do każdego żądania dla następnej strony
NextPageParaName	Fałsz	String	Określa nazwę następnej strony w żądaniu.
HasNextFlagJsonPath	Fałsz	String	Definiuje ścieżkę do atrybutu flagi HasNextPage
NextPageRequestHeader	Fałsz	String	Określa nazwę nagłówka następnej strony w żądaniu.
NextPageUrlQueryParametersTemplate	Fałsz	String	Tylko wtedy, gdy łącznik jest przeznaczony dla interfejsu API Platformy Coralogix

Przykład:

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

Konfigurowanie elementu NextPageToken lub PersistentToken

NextPageToken stronicowanie używa tokenu (skrótu lub kursora), który reprezentuje stan bieżącej strony. Token jest uwzględniony w odpowiedzi interfejsu API, a klient dołącza go do następnego żądania, aby pobrać następną stronę. Ta metoda jest często używana, gdy serwer musi zachować dokładny stan między żądaniami.

PersistentToken stronicowanie używa tokenu utrwalanego po stronie serwera. Serwer zapamiętuje ostatni token pobrany przez klienta i udostępnia następny token w kolejnych żądaniach. Klient kontynuuje, gdzie został przerwany, nawet jeśli później wysyła nowe żądania.

Pole	Wymagania	Type	Opis
Pagesize	Fałsz	Integer	Ile zdarzeń na stronę
PageSizeParameterName	Fałsz	string	Nazwa parametru zapytania dla rozmiaru strony
NextPageTokenJsonPath	Fałsz	string	Ścieżka JSON dla tokenu następnej strony w treści odpowiedzi.
NextPageTokenResponseHeader	Fałsz	string	Jeśli `NextPageTokenJsonPath` wartość jest pusta, użyj tokenu w tej nazwie nagłówka dla następnej strony.
NextPageParaName	Fałsz	string	Określa nazwę następnej strony w żądaniu.
HasNextFlagJsonPath	Fałsz	string	Definiuje ścieżkę do atrybutu flagi HasNextPage podczas określania, czy więcej stron pozostanie w odpowiedzi.
NextPageRequestHeader	Fałsz	string	Określa nazwę nagłówka następnej strony w żądaniu.

Przykłady:

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

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

Konfigurowanie przesunięcia

Offset stronicowanie określa liczbę stron do pominięcia i limit liczby zdarzeń do pobrania na stronę w żądaniu. Klienci pobierają określony zakres elementów z zestawu danych.

Pole	Wymagania	Type	Opis
Pagesize	Fałsz	Integer	Ile zdarzeń na stronę
PageSizeParameterName	Fałsz	String	Nazwa parametru zapytania dla rozmiaru strony
OffsetParaName	Fałsz	String	Następna nazwa parametru zapytania żądania. FUNKCJA DHCP oblicza wartość przesunięcia dla każdego żądania (wszystkie zdarzenia pozyskane + 1)

Przykład:

Paging: {
   
       "pagingType": "Offset", 
        "offsetParaName": "offset" 
 }

Konfiguracja kontrolera domeny

Pole	Wymagania	Type	Opis
DataCollectionEndpoint	Prawda	String	DCE (punkt końcowy zbierania danych) na przykład: `https://example.ingest.monitor.azure.com`.
DataCollectionRuleImmutableId	Prawda	String	Niezmienny identyfikator DCR. Znajdź go, wyświetlając odpowiedź tworzenia kontrolera domeny lub używając interfejsu API DCR
StreamName	Prawda	string	Ta wartość jest zdefiniowana `streamDeclaration` w kontrolerze domeny (prefiks musi zaczynać się od custom-)

Przykładowy łącznik danych PROTOKOŁU KPS

Poniżej przedstawiono przykład wszystkich składników formatu JSON łącznika danych ORGANIZACJI.

{
   "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,
         "queryWindowInMin": 5,
         "httpMethod": "GET",
         "queryTimeFormat": "UnixTimestamp",
         "startTimeAttributeName": "t0",
         "endTimeAttributeName": "t1",
         "retryCount": 3,
         "timeoutInSeconds": 60,
         "headers": {
            "Accept": "application/json",
            "User-Agent": "Example-app-agent"
         } 
      },
      "paging": {
         "pagingType": "LinkHeader"
      },
      "response": {
         "eventsJsonPaths": ["$"]
      }
   }
}

Udostępnij za pośrednictwem

Dokumentacja łącznika danych RestApiPoller dla platformy łącznika bez kodu

Łączniki danych — tworzenie lub aktualizowanie

Parametry identyfikatora URI

Treść żądania

RestApiPoller

Konfiguracja uwierzytelniania

Uwierzytelnianie podstawowe

ApiKey

OAuth2

Jwt

Konfiguracja żądania

Przykład startTimeAttributeName

Przykład QueryTimeIntervalAttributeName

Przykłady żądań przy użyciu programu Microsoft Graph jako interfejsu API źródła danych

Konfiguracja odpowiedzi

Przykłady konfiguracji odpowiedzi

Konfiguracja stronicowania

Konfigurowanie elementu LinkHeader lub PersistentLinkHeader

Konfigurowanie elementu NextPageUrl

Konfigurowanie elementu NextPageToken lub PersistentToken

Konfigurowanie przesunięcia

Konfiguracja kontrolera domeny

Przykładowy łącznik danych PROTOKOŁU KPS

Opinia

Dodatkowe zasoby