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

Aby utworzyć RestApiPoller łącznik danych za pomocą struktury łącznika bez kodu (CCF), 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 wdrażania łącznika danych CCF.

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 CCF ma następującą strukturę:

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

RestApiPoller

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

Nazwa/nazwisko	Wymagania	Typ	opis
nazwa	Prawda	ciąg	Unikatowa nazwa połączenia zgodnego z parametrem identyfikatora URI
rodzaj	Prawda	ciąg	Musi być `RestApiPoller`
etag		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		ciąg	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

Program CCF obsługuje następujące typy uwierzytelniania:

Podstawowa
ApiKey
Uwierzytelnianie OAuth2
JWT

Uwaga

Implementacja protokołu OAuth2 programu CCF 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 struktury łączników bez kodu.

Uwierzytelnianie podstawowe

Pole	Wymagania	Typ
Nazwa użytkownika	Prawda	ciąg
Hasło	Prawda	ciąg

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	Typ	opis	Domyślna wartość
Klucz apiKlucz	Prawda	ciąg	klucz tajny użytkownika
ApiKeyName		ciąg	nazwa nagłówka identyfikatora URI zawierającego wartość ApiKey	`Authorization`
ApiKeyIdentifier		ciąg	wartość ciągu, aby wstępnie otworzyć token	`token`
IsApiKeyInPostPayload		typ logiczny (boolowski)	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

Uwierzytelnianie OAuth2

Struktura łą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	Typ	opis
ClientId	Prawda	Sznurek	Identyfikator klienta
ClientSecret	Prawda	Sznurek	Klucz tajny klienta
Kod autoryzacji	Wartość true, gdy grantType = `authorization_code`	Sznurek	Jeśli typem udzielenia jest `authorization_code` ta wartość pola, będzie kod autoryzacji zwrócony z usługi uwierzytelniania.
Zakres	True dla typu udzielenia `authorization_code` opcjonalnie dla typu udzielenia `client_credentials`	Sznurek	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`	Sznurek	Adres URL przekierowania musi mieć wartość `https://portal.azure.com/TokenAuthorize/ExtensionName/Microsoft_Azure_Security_Insights`
GrantType	Prawda	Sznurek	`authorization_code` lub `client_credentials`
TokenEndpoint	Prawda	Sznurek	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
Punkt autoryzacji	Prawda	Sznurek	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
Parametry zapytania punktu końcowego autoryzacji		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

Uwierzytelnianie JSON Web Token (JWT) obsługuje uzyskiwanie tokenów za pośrednictwem poświadczeń nazwy użytkownika/hasła i używanie ich na potrzeby żądań interfejsu API.

Podstawowy przykład:

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

Poświadczenia w treści POST (ustawienie domyślne):

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

Poświadczenia w nagłówkach (uwierzytelnianie podstawowe):

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

Poświadczenia w nagłówkach (token użytkownika):

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

Przepływ uwierzytelniania:

Wysyłanie poświadczeń do uzyskiwania TokenEndpoint tokenu JWT
- Jeśli IsCredentialsInHeaders: true: wysyła nagłówek uwierzytelniania podstawowego z nazwą użytkownika:password
- Jeśli IsCredentialsInHeaders: false: wysyła poświadczenia w treści POST
Wyodrębnianie tokenu przy użyciu JwtTokenJsonPath nagłówka odpowiedzi lub z nagłówka odpowiedzi
Używanie tokenu w kolejnych żądaniach interfejsu API z ApiKeyName nagłówkiem

Właściwości:

Pole	Wymagania	Typ	opis
type	Prawda	Sznurek	Musi być `JwtToken`
userName (nazwa użytkownika)	True (jeśli parametr userToken nie jest używany)	Objekt	Para klucz-wartość dla poświadczeń nazwy użytkownika. Jeśli `userName` i `password` są wysyłane w żądaniu nagłówka `value` , określ właściwość z nazwą użytkownika. Jeśli `userName` żądanie treści zostanie wysłane i `password` wysłane, określ element `Key` i `Value`
hasło	True (jeśli parametr userToken nie jest używany)	Objekt	Para klucz-wartość dla poświadczeń hasła. Jeśli `userName` i `password` są wysyłane w żądaniu nagłówka `value` , określ właściwość z nazwą użytkownika. Jeśli `userName` żądanie treści zostanie wysłane i `password` wysłane, określ element `Key` i `Value`
userToken	True (jeśli parametr userName nie jest używany)	Sznurek	Token użytkownika wygenerowany przez klienta w celu uzyskania tokenu systemowego na potrzeby uwierzytelniania
UserTokenPrepend	Fałsz	Sznurek	Przed tokenem został wstępnie utworzony tekst. Przykład: `Bearer`
NoAccessTokenPrepend	Fałsz	logiczny	Flaga dostępu wskazująca, że token nie powinien poprzedzać żadnych elementów
TokenEndpointHttpMethod	Fałsz	Sznurek	Metoda HTTP do tokenu punktu końcowego. Może to być `Get` lub `Post`. Domyślnie: `Post`
TokenEndpoint	Prawda	Sznurek	Punkt końcowy adresu URL umożliwiający uzyskanie tokenu JWT
IsCredentialsInHeaders		logiczny	Wyślij poświadczenia jako nagłówek uwierzytelniania podstawowego (`true`) a treść POST (`false`). Domyślnie: `false`
IsJsonRequest		logiczny	Wyślij żądanie jako kod JSON (nagłówek `Content-Type = application/json`) a zakodowane w formularzu (nagłówek `Content-Type = application/x-www-form-urlencoded`). Domyślnie: `false`
JwtTokenJsonPath		Sznurek	JSONPath w celu wyodrębnienia tokenu z odpowiedzi (np. "`$.access_token`")
JwtTokenInResponseHeader		logiczny	Wyodrębnij token z nagłówka odpowiedzi a treścią. Domyślnie: `false`
JwtTokenHeaderName		Sznurek	Nazwa nagłówka, gdy token znajduje się w nagłówku odpowiedzi. Ustawienie domyślne: "`Authorization`"
JwtTokenIdentifier		Sznurek	Identyfikator używany do wyodrębniania zestawu JWT z prefiksowanego ciągu tokenu
Parametry zapytań		Objekt	Niestandardowe parametry zapytania do uwzględnienia podczas wysyłania żądania do punktu końcowego tokenu
Nagłówki		Objekt	Nagłówki niestandardowe do uwzględnienia podczas wysyłania żądania do punktu końcowego tokenu
RequestTimeoutInSeconds		Liczba całkowita	Limit czasu oczekiwania na żądanie w sekundach. Ustawienie domyślne: `100`, Maks. `180`

Przepływ uwierzytelniania:

Wysyłanie poświadczeń do uzyskiwania TokenEndpoint tokenu JWT
- Jeśli IsCredentialsInHeaders: true: wysyła nagłówek uwierzytelniania podstawowego z nazwą użytkownika:password
- Jeśli IsCredentialsInHeaders: false: wysyła poświadczenia w treści POST
Wyodrębnianie tokenu przy użyciu JwtTokenJsonPath nagłówka odpowiedzi lub z nagłówka odpowiedzi
Używanie tokenu w kolejnych żądaniach interfejsu API z ApiKeyName nagłówkiem

Uwaga

Limitations:

Wymaga uwierzytelniania nazwy użytkownika/hasła w celu uzyskania tokenu
Nie obsługuje żądań tokenów opartych na kluczach interfejsu API
Uwierzytelnianie nagłówka niestandardowego (bez nazwy użytkownika/hasła) nie jest obsługiwane

Konfiguracja żądania

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

Pole	Wymagania	Typ	opis
Punkt końcowy interfejsu API	Prawda	Sznurek	Adres URL serwera zdalnego. Definiuje punkt końcowy do ściągania danych.
RateLimitQPS		Liczba całkowita	Definiuje liczbę wywołań lub zapytań dozwolonych w ciągu sekundy.
RateLimitConfig		Objekt	Definiuje konfigurację limitu prędkości dla API RESTful. Zobacz przykład.
ZapytanieWindowInMin		Liczba całkowita	Definiuje dostępne okno zapytania w ciągu kilku minut. Minimalna wartość to 1 minuta. Wartość domyślna to 5 minut.
HttpMethod		Sznurek	Definiuje metodę interfejsu API: `GET`(wartość domyślna) lub `POST`
QueryTimeFormat		Sznurek	Definiuje format daty i godziny oczekiwany przez punkt końcowy (serwer zdalny). Program CCF używa bieżącej daty i godziny wszędzie tam, 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		logiczny	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	Sznurek	Definiuje nazwę parametru zapytania dla czasu rozpoczęcia zapytania. Zobacz przykład.
EndTimeAttributeName	Prawda, gdy `StartTimeAttributeName` jest ustawiona	Sznurek	Definiuje nazwę parametru zapytania dla czasu zakończenia zapytania.
QueryTimeIntervalAttributeName		Sznurek	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	Sznurek	Zobacz `QueryTimeIntervalAttributeName`
QueryTimeIntervalDelimiter	Prawda, gdy `QueryTimeIntervalAttributeName` jest ustawiona	Sznurek	Zobacz `QueryTimeIntervalAttributeName`
QueryParametersTemplate		Sznurek	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ład RateLimitConfig

Rozważ taki przykład:

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

Gdy odpowiedź zawiera nagłówki limitu szybkości, konektor może wykorzystać te informacje do regulacji swojej szybkości żądań.

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	Typ	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		Sznurek	Definiuje ścieżkę do komunikatu o powodzeniu w formacie JSON odpowiedzi. Po zdefiniowaniu tego parametru `SuccessStatusValue` należy również zdefiniować parametr .
SuccessStatusValue		Sznurek	Definiuje ścieżkę do wartości komunikatu o powodzeniu w formacie JSON odpowiedzi
IsGzipCompressed		logiczny	Określa, czy odpowiedź jest kompresowana w pliku gzip
format	Prawda	Sznurek	`json`lub lub `csvxml`
KompresjaAlgo		Sznurek	Algorytm kompresji lub `multi-gzipdeflate`. W przypadku algorytmu kompresji gzip wystarczy skonfigurować `IsGzipCompressed` wartość , aby zamiast ustawiać `True` wartość dla tego parametru.
CsvDelimiter		Sznurek	Jeśli format odpowiedzi to CSV i chcesz zmienić domyślny ogranicznik CSV `","`
HasCsvBoundary		logiczny	Wskazuje, czy dane CSV mają granicę
HasCsvHeader		logiczny	Wskazuje, czy dane CSV mają nagłówek, wartość domyślna to `True`
CsvEscape		Sznurek	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		logiczny	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 CCF 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?
LiczbabasedPaging	Czy odpowiedź interfejsu API obsługuje parametr liczby obiektów do zwrócenia?

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	Typ	opis
LinkHeaderTokenJsonPath	Fałsz	Sznurek	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	Liczba całkowita	Ile zdarzeń na stronę
PageSizeParameterName	Fałsz	Sznurek	Nazwa parametru zapytania dla rozmiaru strony
PagingInfoPlacement	Fałsz	Sznurek	Jak wypełniane są informacje o stronicowaniu. Akceptuje "QueryString" lub "RequestBody"
PagingQueryParamOnly	Fałsz	logiczny	Jeśli ustawiono na true, pominie wszystkie inne parametry zapytania oprócz parametrów stronicowania.

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	Typ	opis
Pagesize	Fałsz	Liczba całkowita	Ile zdarzeń na stronę
PageSizeParameterName	Fałsz	Sznurek	Nazwa parametru zapytania dla rozmiaru strony
NextPageUrl	Fałsz	Sznurek	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	Sznurek	Określa nazwę następnej strony w żądaniu.
HasNextFlagJsonPath	Fałsz	Sznurek	Definiuje ścieżkę do atrybutu flagi HasNextPage
NextPageRequestHeader	Fałsz	Sznurek	Określa nazwę nagłówka następnej strony w żądaniu.
NextPageUrlQueryParametersTemplate	Fałsz	Sznurek	Tylko wtedy, gdy łącznik jest przeznaczony dla interfejsu API Platformy Coralogix
PagingInfoPlacement	Fałsz	Sznurek	Jak wypełniane są informacje o stronicowaniu. Akceptuje "QueryString" lub "RequestBody"
PagingQueryParamOnly	Fałsz	logiczny	Jeśli ustawiono na true, pominie wszystkie inne parametry zapytania oprócz parametrów stronicowania.

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	Typ	opis
Pagesize	Fałsz	Liczba całkowita	Ile zdarzeń na stronę
PageSizeParameterName	Fałsz	ciąg	Nazwa parametru zapytania dla rozmiaru strony
NextPageTokenJsonPath	Fałsz	ciąg	Ścieżka JSON dla tokenu następnej strony w treści odpowiedzi.
NextPageTokenResponseHeader	Fałsz	ciąg	Jeśli `NextPageTokenJsonPath` wartość jest pusta, użyj tokenu w tej nazwie nagłówka dla następnej strony.
NextPageParaName	Fałsz	ciąg	Określa nazwę następnej strony w żądaniu.
HasNextFlagJsonPath	Fałsz	ciąg	Definiuje ścieżkę do atrybutu flagi HasNextPage podczas określania, czy więcej stron pozostanie w odpowiedzi.
NextPageRequestHeader	Fałsz	ciąg	Określa nazwę nagłówka następnej strony w żądaniu.
PagingInfoPlacement	Fałsz	Sznurek	Jak wypełniane są informacje o stronicowaniu. Akceptuje "QueryString" lub "RequestBody"
PagingQueryParamOnly	Fałsz	logiczny	Jeśli ustawiono na true, pominie wszystkie inne parametry zapytania oprócz parametrów stronicowania.

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	Typ	opis
Pagesize	Fałsz	Liczba całkowita	Ile zdarzeń na stronę
PageSizeParameterName	Fałsz	Sznurek	Nazwa parametru zapytania dla rozmiaru strony
OffsetParaName	Fałsz	Sznurek	Następna nazwa parametru zapytania żądania. CCF oblicza wartość przesunięcia dla każdego żądania (wszystkie zdarzenia pozyskane + 1)
PagingInfoPlacement	Fałsz	Sznurek	Jak wypełniane są informacje o stronicowaniu. Akceptuje "QueryString" lub "RequestBody"
PagingQueryParamOnly	Fałsz	logiczny	Jeśli ustawiono na true, pominie wszystkie inne parametry zapytania oprócz parametrów stronicowania.

Przykład:

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

Konfigurowanie funkcji CountBasedPaging

CountBasedPaging Umożliwia klientowi określenie liczby elementów, które mają być zwracane w odpowiedzi. Jest to przydatne w przypadku interfejsów API obsługujących stronicowanie na podstawie parametru count w ramach ładunku odpowiedzi.

Pole	Wymagania	Typ	opis
pageNumberParaName	Prawda	Sznurek	Nazwa parametru numeru strony w żądaniu HTTP
Pagesize	Fałsz	Liczba całkowita	Ile zdarzeń na stronę
ZeroBasedIndexing	Fałsz	logiczny	Flaga wskazująca, czy liczba ma wartość zero
HasNextFlagJsonPath	Fałsz	Sznurek	Ścieżka JSON flagi w ładunku odpowiedzi HTTP, aby wskazać, że jest więcej stron
TotalResultsJsonPath	Fałsz	Sznurek	Ścieżka JSON całkowitej liczby wyników w ładunku odpowiedzi HTTP
PageNumberJsonPath	Fałsz	Sznurek	Wymagane, jeśli podano wartość totalResultsJsonPath. Ścieżka JSON numeru strony w ładunku odpowiedzi HTTP
PageCountJsonPath	Fałsz	Sznurek	Wymagane, jeśli podano wartość totalResultsJsonPath. Ścieżka JSON liczby stron w ładunku odpowiedzi HTTP
PagingInfoPlacement	Fałsz	Sznurek	Jak wypełniane są informacje o stronicowaniu. Akceptuje "QueryString" lub "RequestBody"
PagingQueryParamOnly	Fałsz	logiczny	Jeśli ustawiono na true, pominie wszystkie inne parametry zapytania oprócz parametrów stronicowania.

Przykład:

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

Konfiguracja kontrolera domeny

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

Przykładowy łącznik danych CCF

Oto przykład wszystkich składników kodu JSON łącznika danych CCF.

{
   "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": ["$"]
      }
   }
}

Sprzężenie zwrotne

Czy ta strona była pomocna?

Last updated on 2025-12-11

Udostępnij przez

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

Łączniki danych — tworzenie lub aktualizowanie

Parametry identyfikatora URI

Treść żądania

RestApiPoller

Konfiguracja uwierzytelniania

Uwierzytelnianie podstawowe

ApiKey

Uwierzytelnianie OAuth2

JWT

Konfiguracja żądania

Przykład startTimeAttributeName

Przykład QueryTimeIntervalAttributeName

Przykład RateLimitConfig

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

Konfigurowanie funkcji CountBasedPaging

Konfiguracja kontrolera domeny

Przykładowy łącznik danych CCF

Sprzężenie zwrotne

Dodatkowe źródła