Referencia del conector de datos RestApiPoller para Codeless Connector Framework

Puede crear un RestApiPoller conector de datos con Codeless Connector Framework (CCF) mediante este artículo como complemento a la MICROSOFT SENTINEL API REST para los documentos de conectores de datos.

Cada conector de datos representa una conexión específica de un conector de datos Microsoft Sentinel. Un conector de datos puede tener varias conexiones, que capturan datos de distintos puntos de conexión. Puede completar la plantilla de implementación para el conector de datos CCF mediante la configuración JSON que se compila con este artículo.

Para obtener más información, consulte Creación de un conector sin código para Microsoft Sentinel.

Creación o actualización de conectores de datos

Busque la versión más reciente de la API estable o en versión preliminar haciendo referencia a las create operaciones o update en los documentos de la API REST. La diferencia entre las create operaciones y update es que update requiere el etag valor .

PUT método:

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 obtener más información sobre la versión más reciente de la API, consulte Conectores de datos: crear o actualizar parámetros de URI.

Cuerpo de la solicitud

El cuerpo de la solicitud para un RestApiPoller conector de datos CCF tiene la siguiente estructura:

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

RestApiPoller

RestApiPoller es un conector de datos CCF de sondeo de API que puede usar para personalizar las cargas de paginación, autorización y solicitud/respuesta para el origen de datos.

Configuración de autenticación

El CCF admite los siguientes tipos de autenticación:

• Basic
• Clave de API
• OAuth2
• JWT

Como procedimiento recomendado, use parámetros en la sección de autenticación en lugar de credenciales de codificación rígida. Para obtener más información, consulte Protección de la entrada confidencial.

Para crear la plantilla de implementación, que también usa parámetros, debe escapar los parámetros de esta sección con un elemento de inicio [adicional. Este paso permite a los parámetros asignar un valor en función de la interacción del usuario con el conector. Para obtener más información, vea Caracteres de escape de expresiones de plantilla.

Para permitir que las credenciales se escriban desde la interfaz de usuario, la connectorUIConfig sección requiere que escriba los parámetros deseados en instructions. Para obtener más información, vea Referencia de definiciones de conector de datos para Codeless Connector Framework.

Autenticación básica

Este es un ejemplo de autenticación básica que usa parámetros definidos en connectorUIconfig:

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

Clave de API

APIKey ejemplos de autenticación:

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

El resultado de este ejemplo es el secreto definido a partir de la entrada del usuario enviada en el encabezado siguiente: X-MyApp-Auth-Header: Bearer apikey.

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

En este ejemplo se usan los valores predeterminados y se da como resultado el encabezado siguiente: Authorizationtoken 123123123.

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

Dado que ApiKeyName se establece explícitamente en "", el resultado es el encabezado siguiente: Authorization: 123123123.

OAuth2

Codeless Connector Framework admite la concesión de código de autorización de OAuth 2.0 y las credenciales de cliente. Los clientes confidenciales y públicos usan el tipo de concesión de código de autorización para intercambiar un código de autorización por un token de acceso.

Una vez que el usuario vuelve al cliente a través de la dirección URL de redireccionamiento, la aplicación obtendrá el código de autorización de la dirección URL y lo usará para solicitar un token de acceso.

Puede usar el flujo de código de autenticación para capturar datos en nombre de los permisos de un usuario. Puede usar credenciales de cliente para capturar datos con permisos de aplicación. El servidor de datos concede acceso a la aplicación. Dado que no hay ningún usuario en el flujo de credenciales de cliente, no se necesita ningún punto de conexión de autorización, solo un punto de conexión de token.

Este es un ejemplo del tipo de concesión de 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"
}

Este es un ejemplo del tipo de concesión de 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

La autenticación de JSON Web Token (JWT) admite la obtención de tokens a través de credenciales de nombre de usuario y contraseña y su uso para las solicitudes de API.

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

Credenciales en el cuerpo post (valor predeterminado)

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

Credenciales en encabezados (autenticación 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
}

Credenciales en encabezados (token de usuario)

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

Siga este flujo de autenticación:

1. Enviar credenciales a TokenEndpoint para obtener el token JWT, cuando se usa userName y password, IsCredentialsInHeaders se usa para determinar dónde colocar las credenciales en la solicitud.

   • Si IsCredentialsInHeaders: true: envía un encabezado de autenticación básico con username:password.
   • If IsCredentialsInHeaders: false: envía credenciales en un POST cuerpo.

2. Extraiga el token mediante JwtTokenJsonPath o desde el encabezado de respuesta.

3. El encabezado Authorization de los tokens JWT es una constante y siempre será "Authorization".

Configuración de la solicitud

La sección de solicitud define cómo el conector de datos CCF envía solicitudes al origen de datos (por ejemplo, el punto de conexión de API y la frecuencia con la que se sondea ese punto de conexión).

Cuando la API requiera parámetros complejos, use queryParameters o queryParametersTemplate. Estos comandos incluyen algunas variables integradas.

Ejemplo de StartTimeAttributeName

Tenga en cuenta este ejemplo:

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

La consulta enviada al servidor remoto es: https://www.example.com?from={QueryTimeFormat}&until={QueryTimeFormat + QueryWindowInMin}.

Ejemplo de QueryTimeIntervalAttributeName

Tenga en cuenta este ejemplo:

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

La consulta enviada al servidor remoto es: https://www.example.com?interval=time:{QueryTimeFormat}..{QueryTimeFormat + QueryWindowInMin}.

Ejemplo de RateLimitConfig

Tenga en cuenta este ejemplo:

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

Cuando la respuesta incluye encabezados de límite de velocidad, el conector puede usar esta información para ajustar su tasa de solicitudes.

Ejemplos de solicitud que usan Microsoft Graph como API de origen de datos

En este ejemplo se consultan los mensajes con un parámetro de consulta de filtro. Para obtener más información, consulte Parámetros de consulta de Microsoft Graph API.

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

En el ejemplo anterior se envía una GET solicitud a https://graph.microsoft.com/v1.0/me/messages?filter=receivedDateTime gt {time of request} and receivedDateTime lt 2019-09-01T17:00:00.0000000. La marca de tiempo se actualiza para cada queryWindowInMin vez.

Con este ejemplo se logran los mismos resultados:

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

Hay otra opción para situaciones en las que el origen de datos espera dos parámetros de consulta (uno para la hora de inicio y otro para la hora de finalización).

Ejemplo:

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

Esta opción envía una GET solicitud a https://graph.microsoft.com/me/calendarView?startDateTime=2019-09-01T09:00:00.0000000&endDateTime=2019-09-01T17:00:00.0000000.

Para consultas complejas, use QueryParametersTemplate. En este ejemplo se envía una POST solicitud con parámetros en el cuerpo:

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

Configuración de respuesta

Defina cómo controla el conector de datos las respuestas mediante los parámetros siguientes:

Ejemplos de configuración de respuesta

Se espera una respuesta del servidor en formato JSON. La respuesta tiene los datos solicitados en el valor de propiedad. El estado de la propiedad response indica que se ingieren los datos solo si el valor es success.

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

La respuesta esperada en este ejemplo se prepara para un ARCHIVO CSV sin encabezado.

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

Configuración de paginación

Cuando el origen de datos no puede enviar toda la carga de respuesta a la vez, el conector de datos CCF debe saber cómo recibir partes de los datos en las páginas de respuesta. Los tipos de paginación entre los que elegir son:

Configuración de LinkHeader o PersistentLinkHeader

El tipo de paginación más común es cuando una API de origen de datos de servidor proporciona direcciones URL a las páginas de datos siguientes y anteriores. Para obtener más información sobre la especificación de encabezado de vínculo , vea RFC 5988.

LinkHeader paginación significa que la respuesta de la API incluye:

• Encabezado de Link respuesta HTTP.
• Ruta de acceso JSON para recuperar el vínculo del cuerpo de la respuesta.

PersistentLinkHeaderLa paginación de tipo -tiene las mismas propiedades que LinkHeader, excepto que el encabezado de vínculo persiste en el almacenamiento back-end. Esta opción habilita los vínculos de paginación en las ventanas de consulta.

Por ejemplo, algunas API no admiten las horas de inicio ni las horas de finalización de las consultas. En su lugar, admiten un cursor del lado servidor. Puede usar tipos de página persistentes para recordar el cursor del lado servidor. Para obtener más información, vea ¿Qué es un cursor?.

Estos son algunos ejemplos:

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

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

Configuración de NextPageUrl

NextPageUrl-type paging significa que la respuesta de la API incluye un vínculo complejo en el cuerpo de la respuesta similar a LinkHeader, pero la dirección URL se incluye en el cuerpo de la respuesta en lugar del encabezado.

Ejemplo:

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

Configuración de NextPageToken o PersistentToken

NextPageToken-type pagination usa un token (un hash o un cursor) que representa el estado de la página actual. El token se incluye en la respuesta de API y el cliente lo anexa a la siguiente solicitud para capturar la página siguiente. Este método se usa a menudo cuando el servidor necesita mantener el estado exacto entre las solicitudes.

PersistentToken la paginación usa un token que conserva el lado servidor. El servidor recuerda el último token que recuperó el cliente y proporciona el siguiente token en solicitudes posteriores. El cliente continúa donde lo dejó, incluso si realiza nuevas solicitudes más adelante.

Ejemplos:

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

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

Configuración del desplazamiento

Offset-type pagination especifica el número de páginas que se omitirán y un límite en el número de eventos que se recuperarán por página en la solicitud. Los clientes capturan un intervalo específico de elementos del conjunto de datos.

Ejemplo:

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

Configuración de CountBasedPaging

CountBasedPaging-type pagination permite al cliente especificar el número de elementos que se devolverán en la respuesta. Esta capacidad es útil para las API que admiten la paginación en función de un parámetro count como parte de la carga de respuesta.

Ejemplo:

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

Configuración de DCR

Conector de datos CCF de ejemplo

Este es un ejemplo de todos los componentes del JSON del conector de datos 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": ["$"]
      }
   }
}