Referencia del conector de datos restApiPoller para Codeless Connector Framework

Puede crear un conector de datos de RestApiPoller con codeless Connector Framework (CCF) mediante este artículo como complemento de la API REST de Microsoft Sentinel para conectores de datos documentos.

Cada conector de datos representa un connection específico 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 Crear un conector sin código para Microsoft Sentinel.

Creación o actualización de conectores de datos

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

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 del identificador URI

Para más información sobre la versión más reciente de la API, consulte Conectores de datos: creación o actualización de parámetros de URI.

Cuerpo de la solicitud

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

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

RestApiPoller

es un conector de datos CCF del 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

CcF admite los siguientes tipos de autenticación:

• Básico
• 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 inicio adicional. Este paso permite que los parámetros asignen un valor en función de la interacción del usuario con el conector. Para obtener más información, consulte Caracteres de escape de expresiones de plantilla.

Para permitir que las credenciales se escriban desde la interfaz de usuario, la sección requiere que escriba los parámetros deseados en . Para obtener más información, consulte Referencia de definiciones de conectores 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 :

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

Clave de API

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 siguiente encabezado: : .

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

En este ejemplo se usan los valores predeterminados y se produce el siguiente encabezado: : .

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

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

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 para un token de acceso.

Después de que el usuario vuelva 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 :

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

"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 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. Envíe credenciales para obtener el token JWT.

   • Si : envía un encabezado de autenticación básico con .
   • Si : envía credenciales en un cuerpo.

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

3. Use el token en las solicitudes de API posteriores con el encabezado .

Siga este flujo de autenticación:

1. Envíe credenciales para obtener el token JWT.

   • Si : envía un encabezado de autenticación básico con .
   • Si : envía credenciales en un cuerpo.

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

3. Use el token en las solicitudes de API posteriores con el encabezado .

   Nota:

   Limitaciones

   • Requiere autenticación de nombre de usuario y contraseña para la adquisición de tokens
   • No admite solicitudes de token basadas en claves de API
   • No admite la autenticación de encabezado personalizada (sin nombre de usuario y contraseña)

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 sondear ese punto de conexión).

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

Ejemplo de StartTimeAttributeName

Considere este ejemplo:

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

La consulta enviada al servidor remoto es: .

Ejemplo de QueryTimeIntervalAttributeName

Considere este ejemplo:

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

La consulta enviada al servidor remoto es: .

Ejemplo de RateLimitConfig

Considere este ejemplo:

.

"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 cabeceras de límite de velocidad, el conector puede usar esta información para ajustar su tasa de solicitud.

Solicitar ejemplos que usan Microsoft Graph como API de origen de datos

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

"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 solicitud a . La marca de tiempo se actualiza cada vez.

Con este ejemplo se obtienen 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 solicitud a .

Para consultas complejas, use . En este ejemplo se envía una 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 la propiedad. El estado de la propiedad de respuesta indica que se ingieren los datos solo si el valor es .

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

La respuesta esperada de este ejemplo se prepara para un 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 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 .

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

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

-type paging tiene las mismas propiedades que , excepto que el encabezado de vínculo persiste en el almacenamiento back-end. Esta opción permite paginar vínculos entre ventanas de consulta.

Por ejemplo, algunas API no admiten las horas de inicio o las horas de finalización de 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, consulte ¿Qué es un cursor?.

Estos son algunos ejemplos:

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

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

Configurar NextPageUrl

La paginación de tipo significa que la respuesta de la API incluye un vínculo complejo en el cuerpo de la respuesta similar a , 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\")}" 
}

Configurar NextPageToken o PersistentToken

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

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 las solicitudes posteriores. El cliente continúa donde se 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" 
}

Configurar desplazamiento

-type pagination especifica el número de páginas que se van a omitir y un límite en el número de eventos que se van a recuperar 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

La paginación de tipo permite al cliente especificar el número de elementos que se van a devolver 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": ["$"]
      }
   }
}