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

Para criar um RestApiPoller conector de dados com o CCF (Codeless Connector Framework), use essa referência como um suplemento para os documentos da API REST do Microsoft Sentinel para Conectores de Dados .

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 diferentes pontos de extremidade. A configuração JSON criada usando este documento de referência é usada para concluir o modelo de implantação do conector de dados CCF.

Para obter mais informações, confira 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 mais recente da API estável ou de visualização. A diferença entre a operação de criação e 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 do 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 da solicitação

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

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

RestApiPoller

RestApiPoller representa um conector de dados CCF do Poller da API em que você personaliza conteúdos de paginação, autorização e solicitação/resposta para sua fonte de dados.

Configuração de autenticação

O CCF dá suporte aos seguintes tipos de autenticação:

• Básico
• APIKey
• OAuth2
• JWT

Como prática recomendada, use parâmetros na seção auth em vez de credenciais codificadas. Para obter mais informações, consulte Proteger a 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 .[ 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 na interface do usuário, a connectorUIConfig seção requer instructions os parâmetros desejados. Para obter mais informações, consulte a referência de definições do conector de dados para o Codeless Connector Framework.

Autenticação básica

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

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

APIKey

Exemplos de autenticação APIKey:

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

Este exemplo resulta no segredo definido da entrada do usuário enviada no seguinte cabeçalho: X-MyApp-Auth-Header: Portador 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 é explicitamente definido como "", o resultado é o seguinte cabeçalho: Autorização: 123123123

OAuth2

O Codeless Connector Framework dá suporte à concessão de código de autorização do OAuth 2.0 e às credenciais do 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 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 endpoint de autorização é necessário, apenas um endpoint 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 JWT (Token Web JSON) dá suporte à obtenção de tokens por meio de credenciais de nome de usuário/senha e ao usá-los 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 obter o token JWT

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

2. Extrair token usando JwtTokenJsonPath ou de 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 obter o token JWT

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

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

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

Configuração de solicitaçã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 exigir parâmetros complexos, use o queryParameters ou queryParametersTemplate que inclui algumas variáveis integradas.

Exemplo de StartTimeAttributeName

Considere este exemplo:

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

A consulta enviada ao 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 ao 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 essas informações para ajustar sua taxa de solicitação.

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

Os mesmos resultados são obtidos 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. O 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 conector de dados com os seguintes parâmetros:

Exemplos de configuração de resposta

Uma resposta do servidor com o 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 todo o conteúdo de resposta de uma só vez, o conector de dados CCF precisa saber como receber partes dos dados em páginas de resposta. Os tipos de paginação a serem escolhidos 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 do cabeçalho do link, 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 LinkHeaderque , exceto que o cabeçalho do link persiste no armazenamento de back-end. Essa opção habilita links de paginação entre janelas de consulta. Por exemplo, algumas APIs não dão suporte a horários de início ou término de consulta. 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?.

Veja alguns exemplos:

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

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

Configurar NextPageUrl

NextPageUrl paginação significa que a resposta da API inclui um link complexo no corpo da resposta semelhante a 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 anexa à próxima solicitação para buscar a próxima página. Esse método geralmente é 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 lembra o ú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 novas solicitações posteriormente.

Exemplos:

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

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

Configurar deslocamento

Offset A 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 dão suporte à paginação com base em um parâmetro de contagem como parte do conteúdo de resposta.

Exemplo:

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

Configuração DCR

Conector de dados CCF de exemplo

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