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.

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.

Konfiguracja uwierzytelniania

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

• Podstawowa
• ApiKey
• Uwierzytelnianie OAuth2
• JWT

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

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

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

ApiKey

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.

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:

1. 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

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

3. Używanie tokenu w kolejnych żądaniach interfejsu API z ApiKeyName nagłówkiem

Właściwości:

Przepływ uwierzytelniania:

1. 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

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

3. Używanie tokenu w kolejnych żądaniach interfejsu API z ApiKeyName nagłówkiem

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.

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

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:

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:

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?.

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.

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.

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.

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.

Przykład:

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

Konfiguracja kontrolera domeny

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