Referência do conector de dados RestApiPoller para o Codeless Connector Framework

Para criar um conector de RestApiPoller dados com o Codeless Connector Framework (CCF), use esta referência como um suplemento para os documentos Microsoft Sentinel REST API for Data Connectors .

Cada dataConnector um representa uma conexão específica de um conector de dados do Microsoft Sentinel. Um conector de dados pode ter várias conexões, que buscam dados de pontos de extremidade diferentes. A configuração JSON criada usando este documento de referência é usada para concluir o modelo de implantação para o conector de dados CCF.

Para obter mais informações, consulte Criar um conector sem código para o Microsoft Sentinel.

Conectores de dados - Criar ou atualizar

Consulte a operação Criar ou Atualizar nos documentos da API REST para encontrar a versão estável ou de visualização mais recente da API. A diferença entre a operação de criação e a operação de atualização é que a atualização requer o valor etag .

Método PUT

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

Parâmetros de URI

Para obter mais informações sobre a versão mais recente da API, consulte Conectores de dados - Criar ou atualizar parâmetros de URI.

Corpo do pedido

O corpo da solicitação para um RestApiPoller conector de dados CCF tem a seguinte estrutura:

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

RestApiPoller

O RestApiPoller representa um conector de dados CCF do API Poller onde você personaliza a paginação, a autorização e as cargas úteis de solicitação/resposta para sua fonte de dados.

Configuração de autenticação

O CCF suporta os seguintes tipos de autenticação:

• Básica
• APIKey
• OAuth2
• JWT

Como prática recomendada, use parâmetros na seção de autenticação em vez de credenciais de codificação. Para obter mais informações, consulte Proteger entrada confidencial.

Para criar o modelo de implantação que também usa parâmetros, você precisa escapar dos parâmetros nesta seção com um início [extra. Isso permite que os parâmetros atribuam um valor com base na interação do usuário com o conector. Para obter mais informações, consulte Caracteres de escape de expressões de modelo.

Para permitir que as credenciais sejam inseridas a partir da interface do usuário, a connectorUIConfig seção requer instructions os parâmetros desejados. Para obter mais informações, consulte Referência de definições de conector de dados para o Codeless Connector Framework.

Autenticação básica

Exemplo de autenticação básica usando parâmetros definidos em connectorUIconfig:

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

APIKey

APIKey auth exemplos:

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

Este exemplo resulta no segredo definido a partir da entrada do usuário enviada no seguinte cabeçalho: X-MyApp-Auth-Header: Bearer apikey

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

Este exemplo usa os valores padrão e resulta no seguinte cabeçalho: Authorization: token 123123123

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

Como o ApiKeyName está explicitamente definido como "", o resultado é o seguinte cabeçalho: Autorização: 123123123

OAuth2

O Codeless Connector Framework suporta a concessão de código de autorização OAuth 2.0 e credenciais de cliente. O tipo de concessão de Código de Autorização é usado por clientes confidenciais e públicos para trocar um código de autorização por um token de acesso. Depois que o usuário retornar ao cliente por meio da URL de redirecionamento, o aplicativo obterá o código de autorização da URL e o usará para solicitar um token de acesso.

O fluxo de código de autenticação é para buscar dados em nome das permissões de um usuário e as credenciais do cliente são para buscar dados com permissões de aplicativo. O servidor de dados concede acesso ao aplicativo. Como não há nenhum usuário no fluxo de credenciais do cliente, nenhum ponto de extremidade de autorização é necessário, apenas um ponto de extremidade de token.

Exemplo: tipo de concessão 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"
}

Exemplo: tipo de concessão 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

A autenticação JSON Web Token (JWT) suporta a obtenção de tokens por meio de credenciais de nome de usuário/senha e o uso delas para solicitações de API.

Exemplo básico:

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

Credenciais no corpo do POST (padrão):

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

Credenciais em cabeçalhos (autenticação básica):

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

Credenciais em cabeçalhos (token de usuário):

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

Fluxo de autenticação:

1. Enviar credenciais para TokenEndpoint para obter o token JWT

   • If IsCredentialsInHeaders: true: Envia cabeçalho de autenticação básica com username:password
   • If IsCredentialsInHeaders: false: Envia credenciais no corpo do POST

2. Extrair token usando JwtTokenJsonPath ou do cabeçalho de resposta

3. Usar token em solicitações de API subsequentes com ApiKeyName cabeçalho

Propriedades:

Fluxo de autenticação:

1. Enviar credenciais para TokenEndpoint para obter o token JWT

   • If IsCredentialsInHeaders: true: Envia cabeçalho de autenticação básica com username:password
   • If IsCredentialsInHeaders: false: Envia credenciais no corpo do POST

2. Extrair token usando JwtTokenJsonPath ou do cabeçalho de resposta

3. Usar token em solicitações de API subsequentes com ApiKeyName cabeçalho

Solicitar configuração

A seção de solicitação define como o conector de dados CCF envia solicitações para sua fonte de dados, como o ponto de extremidade da API e com que frequência sondar esse ponto de extremidade.

Quando a API requer parâmetros complexos, use o queryParameters ou queryParametersTemplate que incluem algumas variáveis internas.

Exemplo de StartTimeAttributeName

Considere este exemplo:

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

A consulta enviada para o servidor remoto é: https://www.example.com?from={QueryTimeFormat}&until={QueryTimeFormat + QueryWindowInMin}

Exemplo de QueryTimeIntervalAttributeName

Considere este exemplo:

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

A consulta enviada para o servidor remoto é: https://www.example.com?interval=time:{QueryTimeFormat}..{QueryTimeFormat + QueryWindowInMin}

Exemplo do RateLimitConfig

Considere este exemplo:

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

Quando a resposta inclui cabeçalhos de limite de taxa, o conector pode usar esta informação para ajustar a sua taxa de pedido.

Exemplos de solicitação usando o Microsoft Graph como API de fonte de dados

Este exemplo consulta mensagens com um parâmetro de consulta de filtro. Para obter mais informações, consulte Parâmetros de consulta da API do 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 "
}

O exemplo anterior envia uma GET solicitação para https://graph.microsoft.com/v1.0/me/messages?filter=receivedDateTime gt {time of request} and receivedDateTime lt 2019-09-01T17:00:00.0000000. O carimbo de data/hora é atualizado para cada queryWindowInMin hora.

Os mesmos resultados são alcançados com este exemplo:

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

Outra opção é quando a fonte de dados espera 2 parâmetros de consulta, um para a hora de início e outro para a hora de término.

Exemplo:

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

Isso envia uma GET solicitação para https://graph.microsoft.com/me/calendarView?startDateTime=2019-09-01T09:00:00.0000000&endDateTime=2019-09-01T17:00:00.0000000

Para consultas complexas, use QueryParametersTemplate. Este próximo exemplo envia uma POST solicitação com parâmetros no corpo.

Exemplo:

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

Configuração de resposta

Defina o tratamento de resposta do seu conector de dados com os seguintes parâmetros:

Exemplos de configuração de resposta

Uma resposta do servidor com formato JSON é esperada, com os dados solicitados no valor da propriedade. O status da propriedade

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

A resposta esperada neste exemplo se prepara para um CSV sem cabeçalho.

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

Configuração de paginação

Quando a fonte de dados não pode enviar toda a carga útil de resposta de uma só vez, o conector de dados CCF precisa saber como receber partes dos dados nas páginas de resposta. Os tipos de paginação a escolher são:

Configurar LinkHeader ou PersistentLinkHeader

O tipo de paginação mais comum é quando uma API de fonte de dados do servidor fornece URLs para as páginas de dados seguintes e anteriores. Para obter mais informações sobre a especificação Link Header , consulte RFC 5988.

LinkHeader paginação significa que a resposta da API inclui:

• o cabeçalho de Link resposta HTTP
• ou um caminho JSON para recuperar o link do corpo da resposta.

PersistentLinkHeader A paginação tem as mesmas propriedades LinkHeaderdo , exceto que o cabeçalho do link persiste no armazenamento de back-end. Esta opção permite links de paginação entre janelas de consulta. Por exemplo, algumas APIs não suportam horários de início ou de término de consultas. Em vez disso, eles suportam um cursor do lado do servidor. Os tipos de página persistentes podem ser usados para lembrar o cursor do lado do servidor. Para obter mais informações, consulte O que é um cursor?.

Seguem-se alguns exemplos:

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

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

Configurar NextPageUrl

NextPageUrl paging significa que a resposta da API inclui um link complexo no corpo da resposta semelhante ao LinkHeader, mas a URL é incluída no corpo da resposta em vez do cabeçalho.

Exemplo:

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

Configurar NextPageToken ou PersistentToken

NextPageToken A paginação usa um token (um hash ou um cursor) que representa o estado da página atual. O token é incluído na resposta da API e o cliente o acrescenta à próxima solicitação para buscar a próxima página. Esse método é freqüentemente usado quando o servidor precisa manter o estado exato entre as solicitações.

PersistentToken A paginação usa um token que persiste no lado do servidor. O servidor se lembra do último token recuperado pelo cliente e fornece o próximo token em solicitações subsequentes. O cliente continua de onde parou, mesmo que faça novos pedidos mais tarde.

Exemplos:

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

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

Configurar deslocamento

Offset paginação especifica o número de páginas a serem ignoradas e um limite no número de eventos a serem recuperados por página na solicitação. Os clientes buscam um intervalo específico de itens do conjunto de dados.

Exemplo:

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

Configurar CountBasedPaging

CountBasedPaging Permite que o cliente especifique o número de itens a serem retornados na resposta. Isso é útil para APIs que suportam paginação com base em um parâmetro count como parte da carga útil de resposta.

Exemplo:

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

Configuração DCR

Exemplo de conector de dados CCF

Aqui está um exemplo de todos os componentes do conector de dados CCF JSON juntos.

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