Dokumentacja łącznika danych RestApiPoller dla struktury łączników bez kodu

Łącznik danych można utworzyć RestApiPoller za pomocą struktury ccf (Codeless Connector Framework), korzystając z tego artykułu jako dodatku do dokumentacji interfejsu API REST Microsoft Sentinel dla łączników danych.

Każdy łącznik danych reprezentuje określone połączenie łącznika danych Microsoft Sentinel. Jeden łącznik danych może mieć wiele połączeń, które pobierają dane z różnych punktów końcowych. Szablon wdrożenia łącznika danych CCF można ukończyć przy użyciu konfiguracji JSON utworzonej w tym artykule.

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

Tworzenie lub aktualizowanie łączników danych

Znajdź najnowszą stabilną wersję interfejsu API lub wersję zapoznawczą interfejsu create API, odwołując się do operacji lub update w dokumentacji interfejsu API REST. Różnica między operacjami i update polega na create tym, że update wymaga wartościetag.

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.

Name (Nazwa)	Opis
dataConnectorId	Identyfikator łącznika danych. Musi to być unikatowa nazwa, która jest taka sama jak name parametr w treści żądania.
resourceGroupName	Nazwa grupy zasobów, a nie uwzględnia wielkość liter.
subscriptionId	Identyfikator subskrypcji docelowej.
workspaceName	Nazwa obszaru roboczego, a nie identyfikator. Wzorzec regex to ^[A-Za-z0-9][A-Za-z0-9-]+[A-Za-z0-9]$.
api-version	Wersja interfejsu API do użycia dla tej operacji.

Treść żądania

Treść żądania łącznika RestApiPoller danych CCF ma następującą strukturę:

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

RestApiPoller

RestApiPoller to łącznik danych CCF sondatora interfejsu API, którego można użyć do dostosowywania ładunków stronicowania, autoryzacji i żądania/odpowiedzi dla źródła danych.

Name (Nazwa)	Wymagany	Wpisać	Opis
name	True	Ciąg	Unikatowa nazwa połączenia zgodnego z parametrem URI.
kind	True	Ciąg	Wartość kind . To pole musi być ustawione na RestApiPollerwartość .
etag		Identyfikator guid	Wartość etag . To pole musi pozostać puste w celu utworzenia nowego łącznika. W przypadku operacji etag aktualizacji musi być zgodny z istniejącym łącznikiem etag (GUID).
properties.connectorDefinitionName		Ciąg	Nazwa zasobu DataConnectorDefinition , który definiuje konfigurację interfejsu użytkownika łącznika danych. Aby uzyskać więcej informacji, przejdź do tematu Definicja łącznika danych.
properties.auth	True	Zagnieżdżony kod JSON	Właściwości uwierzytelniania do sondowania danych. Aby uzyskać więcej informacji, przejdź do pozycji Konfiguracja uwierzytelniania.
properties.request	True	Zagnieżdżony kod JSON	Ładunek żądania do sondowania danych, taki jak punkt końcowy interfejsu API. Aby uzyskać więcej informacji, przejdź do tematu Żądanie konfiguracji.
properties. response	True	Zagnieżdżony kod JSON	Obiekt odpowiedzi i zagnieżdżony komunikat, który interfejs API zwraca podczas sondowania danych. Aby uzyskać więcej informacji, przejdź do pozycji Konfiguracja odpowiedzi.
properties.paging		Zagnieżdżony kod JSON	Ładunek dzielenia na strony podczas sondowania danych. Aby uzyskać więcej informacji, przejdź do tematu Konfiguracja stronicowania.
properties.dcrConfig		Zagnieżdżony kod JSON	Wymagane parametry podczas wysyłania danych do reguły zbierania danych (DCR). Aby uzyskać więcej informacji, przejdź do konfiguracji dcr.

Konfiguracja uwierzytelniania

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

• Basic
• Klucz interfejsu API
• OAuth2
• JWT

Uwaga

Implementacja CCF OAuth2 nie obsługuje poświadczeń certyfikatu klienta.

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

Aby utworzyć szablon wdrożenia, który również używa parametrów, musisz uniknąć parametrów w tej sekcji z dodatkowym początkowym [elementem . Ten krok umożliwia parametrom przypisywanie wartości na podstawie interakcji użytkownika z łącznikiem. Aby uzyskać więcej informacji, zobacz Znaki ucieczki wyrażeń szablonu.

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

Uwierzytelnianie podstawowe

Pole	Wymagany	Wpisać
UserName	True	Ciąg
Password	True	Ciąg

Oto przykład uwierzytelniania podstawowego, które używa parametrów zdefiniowanych w programie connectorUIconfig:

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

Klucz interfejsu API

Pole	Wymagany	Wpisać	Opis	Wartość domyślna
ApiKey	True	Ciąg	Klucz tajny użytkownika.
ApiKeyName		Ciąg	Nazwa nagłówka identyfikatora URI zawierającego ApiKey wartość.	Authorization
ApiKeyIdentifier		Ciąg	Wartość ciągu umożliwiająca przygotowanie tokenu.	token
IsApiKeyInPostPayload		Wartość logiczna	Wartość określająca, czy wpis tajny ma zostać wysłany w treści, a nie w POST nagłówku.	false

APIKey przykłady uwierzytelniania:

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

Wynikiem tego przykładu jest wpis tajny zdefiniowany na podstawie danych wejściowych użytkownika wysł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 wynik w następującym nagłówku: Authorization. token 123123123

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

Ponieważ ApiKeyName jest jawnie ustawiona na "", wynik jest następujący nagłówek: Authorization. 123123123

OAuth2

Program Codeless Connector Framework obsługuje przyznawanie kodu autoryzacji OAuth 2.0 i poświadczenia klienta. Typ przyznawania kodu autoryzacji jest używany przez klientów poufnych i publicznych 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	Wymagany	Wpisać	Opis
ClientId	True.	Ciąg	Identyfikator klienta.
ClientSecret	True.	Ciąg	Klucz tajny klienta.
AuthorizationCode	Wartość true, grantType gdy wartość to authorization_code.	Ciąg	Jeśli typ przyznawania to authorization_code, ta wartość pola jest kodem autoryzacji zwróconym przez serwer uwierzytelniania.
Scope	Wartość true dla typu przyznawania authorization_code . Opcjonalnie dla typu przyznawania client_credentials .	Ciąg	Rozdzielana spacjami lista zakresów na potrzeby zgody użytkownika. Aby uzyskać więcej informacji, zobacz Zakresy i uprawnienia OAuth2.
RedirectUri	Wartość true, grantType gdy wartość to authorization_code.	Ciąg	Adres URL przekierowania musi mieć wartość https://portal.azure.com/TokenAuthorize/ExtensionName/Microsoft_Azure_Security_Insights.
GrantType	True.	Ciąg	Typ przyznawania. Może być authorization_code lub client_credentials.
TokenEndpoint	True.	Ciąg	Adres URL wymiany kodu z prawidłowym tokenem w authorization_code udzielu lub identyfikator klienta i wpis tajny z prawidłowym tokenem w udziel.client_credentials
TokenEndpointHeaders		Obiektu	Opcjonalny obiekt klucz/wartość do wysyłania nagłówków niestandardowych do serwera tokenów.
TokenEndpointQueryParameters		Obiektu	Opcjonalny obiekt klucz/wartość do wysyłania niestandardowych parametrów zapytania do serwera tokenów.
AuthorizationEndpoint	True.	Ciąg	Adres URL zgody użytkownika dla authorization_code przepływu.
AuthorizationEndpointHeaders		Obiektu	Opcjonalny obiekt klucz/wartość do wysyłania niestandardowych nagłówków do serwera uwierzytelniania.
AuthorizationEndpointQueryParameters		Obiektu	Opcjonalna para klucz/wartość używana w żądanym przepływie kodu autoryzacji OAuth2.

Przepływ kodu uwierzytelniania umożliwia pobieranie danych w imieniu uprawnień użytkownika. Poświadczenia klienta umożliwiają pobieranie danych z uprawnieniami aplikacji. Serwer danych udziela dostępu do aplikacji. Ponieważ w przepływie poświadczeń klienta nie ma użytkownika, nie jest potrzebny żaden punkt końcowy autoryzacji, tylko punkt końcowy tokenu.

Oto przykład typu dotacji 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"
}

Oto przykład typu dotacji 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 i hasła oraz używanie ich do żą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"
}

Postępuj zgodnie z tym przepływem uwierzytelniania:

1. Wysyłanie poświadczeń w celu TokenEndpoint uzyskania tokenu JWT podczas korzystania z userName funkcji i passwordIsCredentialsInHeaders służy do określania, gdzie umieścić poświadczenia w żądaniu.

   • Jeśli IsCredentialsInHeaders: true: wysyła nagłówek uwierzytelniania podstawowego za pomocą username:passwordpolecenia .
   • Jeśli IsCredentialsInHeaders: false: wysyła poświadczenia w POST treści.

2. Wyodrębnij token przy użyciu JwtTokenJsonPath lub z nagłówka odpowiedzi.

3. Nagłówek autoryzacji tokenów JWT jest stałą i zawsze będzie mieć wartość "Autoryzacja".

Pole	Wymagany	Wpisać	Opis
type	True	Ciąg	Typ. Musi być JwtToken
userName	Prawda (jeśli userToken nie jest używana)	Obiektu	Para klucz/wartość dla userName poświadczeń. Jeśli userName i password są wysyłane w żądaniu nagłówka, określ właściwość value z nazwą użytkownika. Jeśli userName i password są wysyłane w żądaniu treści, określ Key i Value.
password	Prawda (jeśli userToken nie jest używana)	Obiektu	Para klucz/wartość dla poświadczeń hasła. Jeśli userName i password są wysyłane w żądaniu nagłówka, określ właściwość value za pomocą userNamepolecenia . Jeśli userName i password są wysyłane w żądaniu treści, określ Key i Value.
userToken	Prawda (jeśli userName nie jest używana)	Ciąg	Token użytkownika wygenerowany przez klienta w celu uzyskania tokenu systemowego na potrzeby uwierzytelniania.
UserTokenPrepend	False	Ciąg	Wartość, która wskazuje, czy przedpłaty tekstu przed tokenem. Wartość domyślna: Bearer.
NoAccessTokenPrepend	False	Wartość logiczna	Flaga dostępu wskazująca, że token nie powinien niczego poprzedzać.
TokenEndpointHttpMethod	False	Ciąg	Metoda HTTP dla punktu końcowego tokenu. Może to być Get lub Post. Wartość domyślna to Post.
TokenEndpoint	True	Ciąg	Punkt końcowy adresu URL używany do uzyskania tokenu JWT.
IsCredentialsInHeaders		Wartość logiczna	Wartość wskazująca, czy wysyłać poświadczenia jako nagłówek uwierzytelniania podstawowego (true) a treść (false), ignorowana POST podczas korzystania z polecenia userToken. Wartość domyślna to false.
IsJsonRequest		Wartość logiczna	Wartość wskazująca, czy wysłać żądanie w formacie JSON (nagłówek Content-Type = application/json) w porównaniu z kodowanym formularzem (nagłówek Content-Type = application/x-www-form-urlencoded). Wartość domyślna to false.
JwtTokenJsonPath		Ciąg	Wartość wskazująca JSONPath wartość, która ma zostać użyta do wyodrębnienia tokenu z odpowiedzi. Przykład: $.access_token.
JwtTokenInResponseHeader		Wartość logiczna	Wartość wskazująca, czy wyodrębnić token z nagłówka odpowiedzi w porównaniu z treścią. Wartość domyślna to false.
JwtTokenHeaderName.		Ciąg	Wartość wskazująca nazwę nagłówka, gdy token znajduje się w nagłówku odpowiedzi. Wartość domyślna to Authorization.
JwtTokenIdentifier		Ciąg	Identyfikator używany do wyodrębniania JWT z prefiksowanego ciągu tokenu.
QueryParameters		Obiektu	Niestandardowe parametry zapytania do uwzględnienia podczas wysyłania żądania do punktu końcowego tokenu.
Headers		Obiektu	Niestandardowe nagłówki do uwzględnienia podczas wysyłania żądania do punktu końcowego tokenu.
RequestTimeoutInSeconds		Liczba całkowita	Limit czasu żądania w sekundach. Wartość domyślna to 100, z maksymalną wartością 180.

Uwaga

Ograniczenia

• Wymaga uwierzytelniania nazwy użytkownika i hasła na potrzeby pozyskiwania tokenu
• Nie obsługuje żądań tokenów opartych na kluczach interfejsu API
• Nie obsługuje niestandardowego uwierzytelniania nagłówka (bez nazwy użytkownika i hasła)

Konfiguracja żądania

Sekcja żądania definiuje sposób, w jaki łącznik danych CCF wysyła żądania do źródła danych (na przykład do punktu końcowego interfejsu API i jak często sonduje ten punkt końcowy).

Pole	Wymagany	Wpisać	Opis
ApiEndpoint	True.	Ciąg	To pole określa adres URL serwera zdalnego i definiuje punkt końcowy, z którego mają być ściągane dane.
RateLimitQPS		Liczba całkowita	To pole definiuje liczbę wywołań lub zapytań dozwolonych w ciągu sekundy dla początkowego żądania. Nie dotyczy żądań podzielonych na strony. Aby ograniczyć podział na strony, ustaw również wartość PaginatedCallsPerSecond.
PaginatedCallsPerSecond		Podwójny (0...1000)	To pole definiuje liczbę wywołań na sekundę dozwoloną dla żądań podzielonych na strony do interfejsu API RESTful. Wprowadza opóźnienie milisekund między każdym wywołaniem interfejsu API podzielonego (1000 / paginatedCallsPerSecond) na strony. To ograniczanie ma zastosowanie tylko do żądań podzielonych na strony i jest oddzielone od RateLimitQPSelementu , który kontroluje początkową szybkość żądań. Zazwyczaj jest to taka sama wartość, jak RateLimitQPS w przypadku przestrzegania limitu szybkości źródła danych we wszystkich żądaniach. 0 wartość oznacza, że nie jest stosowane ograniczanie podziałów na strony.
RateLimitConfig		Obiektu	To pole definiuje konfigurację limitu szybkości dla interfejsu API RESTful. Aby uzyskać więcej informacji, przejdź do przykładuRateLimitConfig.
QueryWindowInMin		Liczba całkowita	To pole definiuje dostępne okno zapytania w ciągu kilku minut. Minimalna wartość to 1 minuta. Wartość domyślna to 5 minut.
HttpMethod		Ciąg	To pole definiuje metodę interfejsu API: GET(wartość domyślna) lub POST.
QueryTimeFormat		Ciąg	To pole definiuje format daty i godziny, jakiego oczekuje punkt końcowy (serwer zdalny). Plik 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, UnixTimestampInMillslub 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)	To pole definiuje, że wartości ponownych 16 prób mogą zostać odzyskane po awarii. Wartość domyślna to 3.
TimeoutInSeconds		Liczba całkowita (1...180)	To pole definiuje limit czasu żądania w sekundach. Wartość domyślna to 20.
IsPostPayloadJson		Wartość logiczna	To pole określa, czy ładunek POST ma format JSON. Wartość domyślna to false.
Headers		Obiektu	To pole zawiera pary klucz/wartość, które definiują nagłówki żądania.
QueryParameters		Obiektu	To pole zawiera pary klucz/wartość, które definiują parametry zapytania żądania.
StartTimeAttributeName	Wartość true, EndTimeAttributeName gdy wartość jest ustawiona.	Ciąg	To pole definiuje nazwę parametru zapytania dla czasu rozpoczęcia zapytania. Aby uzyskać więcej informacji, przejdź do przykładuStartTimeAttributeName.
EndTimeAttributeName	Prawda, gdy StartTimeAttributeName jest ustawiona.	Ciąg	To pole definiuje nazwę parametru zapytania dla czasu zakończenia zapytania.
QueryTimeIntervalAttributeName		Ciąg	To pole jest używane, jeśli punkt końcowy wymaga wyspecjalizowanego formatu do wykonywania zapytań o dane w danym okresie. Użyj tej właściwości z parametrami QueryTimeIntervalPrepend i QueryTimeIntervalDelimiter . Aby uzyskać więcej informacji, przejdź do przykładuQueryTimeIntervalAttributeName.
QueryTimeIntervalPrepend	Prawda, gdy QueryTimeIntervalAttributeName jest ustawiona.	Ciąg	Dokumentacja QueryTimeIntervalAttributeName.
QueryTimeIntervalDelimiter	Prawda, gdy QueryTimeIntervalAttributeName jest ustawiona.	Ciąg	Dokumentacja QueryTimeIntervalAttributeName.
QueryParametersTemplate		Ciąg	To pole odwołuje się do szablonu zapytania używanego podczas przekazywania parametrów w zaawansowanych scenariuszach. Przykład: "queryParametersTemplate": "{'cid': 1234567, 'cmd': 'reporting', 'format': 'siem', 'data': { 'from': '{_QueryWindowStartTime}', 'to': '{_QueryWindowEndTime}'}, '{_APIKeyName}': '{_APIKey}'}".
InitialCheckpointTimeUtc		DateTime (UTC)	Określa czas rozpoczęcia zapytania dla pierwszej ankiety, gdy nie istnieje przechowywany punkt kontrolny. Gdy punkt kontrolny zostanie utrwalony po pierwszym pomyślnym sondowaniu, ta wartość zostanie zignorowana. To ustawienie ma zastosowanie tylko wtedy, gdy konfiguracja żądania łącznika definiuje parametr zapytania czasu rozpoczęcia (na przykład startTimeAttributeName lub {_QueryWindowStartTime} token zastępczy) bez odpowiedniego parametru czasu końcowego. Nie ma to wpływu na łączniki, które polegają wyłącznie na kursorach lub tokenach dzielenia na strony. Format: ISO 8601 UTC datetime (na przykład 2024-01-15T00:00:00Z).

Gdy interfejs API wymaga złożonych parametrów, użyj polecenia queryParameters lub queryParametersTemplate. Te polecenia obejmują niektóre 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żmy ten 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żmy ten 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żmy ten 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, łącznik może użyć tych informacji do dostosowania szybkości żądania.

Przykłady żądań korzystających z programu Microsoft Graph jako interfejsu API źródła danych

Ten przykład wysyła zapytania do komunikatów za pomocą parametru zapytania filtru. Aby uzyskać więcej informacji, zobacz Microsoft interfejs Graph API parametry zapytania.

"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 żądanie do obiektu GEThttps://graph.microsoft.com/v1.0/me/messages?filter=receivedDateTime gt {time of request} and receivedDateTime lt 2019-09-01T17:00:00.0000000. Sygnatura czasowa jest aktualizowana za każdym queryWindowInMin razem.

W tym przykładzie można osiągnąć te same wyniki:

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

Istnieje inna opcja w sytuacjach, gdy źródło danych oczekuje dwóch 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",
}

Ta opcja wysyła GET żądanie do programu 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. Ten przykład wysyła POST żądanie z parametrami w treści:

"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 sposób, w jaki łącznik danych obsługuje odpowiedzi, używając następujących parametrów:

Pole	Wymagany	Wpisać	Opis
EventsJsonPaths	True	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		Ciąg	Definiuje ścieżkę do komunikatu o powodzeniu w formacie JSON odpowiedzi. Po zdefiniowaniu tego parametru SuccessStatusValue należy również zdefiniować parametr.
SuccessStatusValue		Ciąg	Definiuje ścieżkę do wartości komunikatu o powodzeniu w formacie JSON odpowiedzi.
IsGzipCompressed		Wartość logiczna	Określa, czy odpowiedź jest skompresowana w pliku GZIP.
format	True	Ciąg	Określa, czy format to json, csvczy xml.
CompressionAlgo		Ciąg	Definiuje algorytm kompresji albo multi-gzip lub deflate. W przypadku algorytmu kompresji GZIP skonfiguruj IsGzipCompressed wartość , zamiast ustawiać True wartość dla tego parametru.
CsvDelimiter		Ciąg	Odwołuje się do formatu odpowiedzi 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		Ciąg	Definiuje znak ucieczki dla granicy pola. Wartość domyślna to " Na przykład wolumin CSV z nagłówkami id,name,avg i wierszem danych zawierającymi spacje, takie jak 1,"my name",5.5 , wymaga granicy " pola.
ConvertChildPropertiesToArray		Wartość logiczna	Odwołuje się do specjalnego przypadku, 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 w formacie JSON. Odpowiedź zawiera żądane dane w wartości właściwości. Stan właściwości odpowiedzi wskazuje na 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 utworzenia pliku CSV bez nagłówka.

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

Konfiguracja stronicowania

Jeśli źródło danych nie może wysłać całego ładunku odpowiedzi jednocześnie, łącznik danych CCF musi wiedzieć, jak odbierać części 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 PersistentToken	Czy odpowiedź interfejsu API ma token lub kursor dla następnych i poprzednich stron?
Offset	Czy odpowiedź interfejsu API obsługuje parametr liczby obiektów do pominięcia podczas stronicowania?
CountBasedPaging	Czy odpowiedź interfejsu API obsługuje parametr liczby zwracanych obiektów?

Konfigurowanie elementu LinkHeader lub PersistentLinkHeader

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

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

• Nagłówek Link odpowiedzi HTTP.
• Ścieżka JSON służąca do pobierania linku z treści odpowiedzi.

PersistentLinkHeaderStronicowanie typu ma takie same właściwości jak LinkHeader, z wyjątkiem tego, że nagłówek linku 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 lub zakończenia zapytania. Zamiast tego obsługują kursor po stronie serwera. Możesz użyć trwałych typów stron, aby zapamiętać kursor po stronie serwera. Aby uzyskać więcej informacji, zobacz Co to jest kursor?.

Uwaga

Można uruchomić tylko jedno zapytanie dotyczące łącznika, PersistentLinkHeader aby uniknąć warunków wyścigu na kursorze po stronie serwera. Ten problem może mieć wpływ na opóźnienie.

Pole	Wymagany	Wpisać	Opis
LinkHeaderTokenJsonPath	False	Ciąg	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 wartość to $.nextPage.
PageSize	False	Liczba całkowita	Ta właściwość służy do określania liczby zdarzeń na stronę.
PageSizeParameterName	False	Ciąg	Użyj tej nazwy parametru zapytania, aby wskazać rozmiar strony.
PagingInfoPlacement	False	Ciąg	Ta właściwość służy do określania sposobu wypełniania informacji stronicowania. Akceptuje wartość lub QueryStringRequestBody.
PagingQueryParamOnly	False	Wartość logiczna	Ta właściwość służy do określania parametrów zapytania. Jeśli wartość ma wartość true, pomija wszystkie inne parametry zapytania z wyjątkiem parametrów zapytania stronicowania.

Oto kilka przykładów:

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

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

Konfigurowanie elementu NextPageUrl

NextPageUrl-type stronicowanie oznacza, że odpowiedź interfejsu API zawiera złożone łącze w treści odpowiedzi podobne do LinkHeader, ale adres URL jest uwzględniony w treści odpowiedzi zamiast nagłówka.

Pole	Wymagany	Wpisać	Opis
PageSize	False	Liczba całkowita	Liczba zdarzeń na stronę.
PageSizeParameterName	False	Ciąg	Nazwa parametru zapytania dla rozmiaru strony.
NextPageUrl	False	Ciąg	Pole używane tylko wtedy, gdy łącznik jest przeznaczony dla interfejsu API Platformy Coralogix.
NextPageUrlQueryParameters	False	Obiektu	Pary klucz/wartość, które dodają niestandardowy parametr zapytania do każdego żądania dla następnej strony.
NextPageParaName	False	Ciąg	Nazwa następnej strony w żądaniu.
HasNextFlagJsonPath	False	Ciąg	Ścieżka do atrybutu HasNextPage flagi.
NextPageRequestHeader	False	Ciąg	Nazwa nagłówka następnej strony w żądaniu.
NextPageUrlQueryParametersTemplate	False	Ciąg	Pole używane tylko wtedy, gdy łącznik jest przeznaczony dla interfejsu API Platformy Coralogix.
PagingInfoPlacement	False	Ciąg	Pole określające sposób wypełniania informacji stronicowania. Akceptuje wartość lub QueryStringRequestBody.
PagingQueryParamOnly	False	Wartość logiczna	Pole określające parametry zapytania. Jeśli wartość ma wartość true, pomija wszystkie inne parametry zapytania z wyjątkiem parametrów zapytania 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-type pagination 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 Podział na strony używa tokenu, który utrwala stronę serwera. Serwer zapamiętuje ostatni token pobrany przez klienta i udostępnia następny token w kolejnych żądaniach. Klient kontynuuje działanie tam, gdzie zostało przerwane, nawet jeśli później wysyła nowe żądania.

Pole	Wymagany	Wpisać	Opis
PageSize	False	Liczba całkowita	Liczba zdarzeń na stronę.
PageSizeParameterName	False	Ciąg	Nazwa parametru zapytania dla rozmiaru strony.
NextPageTokenJsonPath	False	Ciąg	Ścieżka JSON dla tokenu następnej strony w treści odpowiedzi.
NextPageTokenResponseHeader	False	Ciąg	Pole, które określa, że jeśli NextPageTokenJsonPath jest puste, użyj tokenu w tej nazwie nagłówka dla następnej strony.
NextPageParaName	False	Ciąg	Pole określające nazwę następnej strony w żądaniu.
HasNextFlagJsonPath	False	Ciąg	Pole definiujące ścieżkę do atrybutu HasNextPage flagi podczas określania, czy w odpowiedzi pozostało więcej stron.
NextPageRequestHeader	False	Ciąg	Pole określające nazwę nagłówka następnej strony w żądaniu.
PagingInfoPlacement	False	Ciąg	Pole określające sposób wypełniania informacji stronicowania. Akceptuje wartość lub QueryStringRequestBody.
PagingQueryParamOnly	False	Wartość logiczna	Pole określające parametry zapytania. Jeśli wartość ma wartość true, pomija wszystkie inne parametry zapytania z wyjątkiem parametrów zapytania stronicowania.

Przykłady:

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

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

Konfigurowanie przesunięcia

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

Pole	Wymagany	Wpisać	Opis
PageSize	False	Liczba całkowita	Liczba zdarzeń na stronę.
PageSizeParameterName	False	Ciąg	Nazwa parametru zapytania dla rozmiaru strony.
OffsetParaName	False	Ciąg	Nazwa parametru zapytania następnego żądania. CcF oblicza wartość przesunięcia dla każdego żądania (wszystkie zdarzenia pozyskane + 1).
PagingInfoPlacement	False	Ciąg	Pole określające sposób wypełniania informacji stronicowania. Akceptuje wartość lub QueryStringRequestBody.
PagingQueryParamOnly	False	Wartość logiczna	Pole określające parametry zapytania. Jeśli wartość ma wartość true, pomija wszystkie inne parametry zapytania z wyjątkiem parametrów zapytania stronicowania.

Przykład:

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

Konfigurowanie funkcji CountBasedPaging

CountBasedPaging-type pagination umożliwia klientowi określenie liczby elementów do zwrócenia w odpowiedzi. Ta możliwość jest przydatna w przypadku interfejsów API obsługujących podział na strony na podstawie parametru count w ramach ładunku odpowiedzi.

Pole	Wymagany	Wpisać	Opis
pageNumberParaName	True	Ciąg	Nazwa parametru numeru strony w żądaniu HTTP.
PageSize	False	Liczba całkowita	Liczba zdarzeń na stronę.
ZeroBasedIndexing	False	Wartość logiczna	Flaga wskazująca, że liczba jest równa zero.
HasNextFlagJsonPath	False	Ciąg	Ścieżka JSON flagi w ładunku odpowiedzi HTTP wskazująca, że jest więcej stron.
TotalResultsJsonPath	False	Ciąg	Ścieżka JSON łącznej liczby wyników w ładunku odpowiedzi HTTP.
PageNumberJsonPath	False	Ciąg	Ścieżka JSON numeru strony w ładunku odpowiedzi HTTP. Wymagane w przypadku totalResultsJsonPath dostarczenia.
PageCountJsonPath	False	Ciąg	Ścieżka JSON liczby stron w ładunku odpowiedzi HTTP. Wymagane w przypadku totalResultsJsonPath dostarczenia.
PagingInfoPlacement	False	Ciąg	Pole określające sposób wypełniania informacji stronicowania. Akceptuje wartość lub QueryStringRequestBody.
PagingQueryParamOnly	False	Wartość logiczna	Pole określające parametry zapytania. Jeśli wartość ma wartość true, pomija wszystkie inne parametry zapytania z wyjątkiem parametrów zapytania stronicowania.

Przykład:

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

Konfiguracja dcr

Pole	Wymagany	Wpisać	Opis
DataCollectionEndpoint	True	Ciąg	Punkt końcowy zbierania danych (DCE). Przykład: https://example.ingest.monitor.azure.com.
DataCollectionRuleImmutableId	True	Ciąg	Niezmienny identyfikator DCR. Znajdź ją, wyświetlając odpowiedź tworzenia dcr lub przy użyciu interfejsu API DCR.
StreamName	True	Ciąg	Ta wartość jest zdefiniowana streamDeclaration w dcr. Prefiks musi zaczynać się od Custom-.

Przykładowy łącznik danych CCF

Oto przykład wszystkich składników 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": ["$"]
      }
   }
}