Ingesta de datos de Azure Cosmos DB en Azure Data Explorer

  • Artículo

Azure Data Explorer admite la ingesta de datos de Azure Cosmos DB para NoSql mediante una fuente de cambios. La conexión de datos de fuente de cambios de Cosmos DB es una canalización de ingesta que escucha la fuente de cambios de Cosmos DB e ingiere los datos en la tabla de Data Explorer. La fuente de cambios escucha documentos nuevos y actualizados, pero no registra eliminaciones. Para obtener información general sobre la ingesta de datos en Azure Data Explorer, consulte Introducción a la ingesta de datos de Azure Data Explorer.

Cada conexión de datos escucha un contenedor de Cosmos DB específico e ingiere datos en una tabla especificada (más de una conexión puede ingerir en una sola tabla). El método de ingesta admite la ingesta de streaming (cuando está habilitada) y la ingesta en cola.

En este artículo, aprenderá a configurar una conexión de datos de fuente de cambios de Cosmos DB para ingerir datos en Azure Data Explorer con identidad administrada del sistema. Revise las consideraciones antes de empezar.

Siga estos pasos para configurar un conector:

Paso 1: Elegir una tabla de Azure Data Explorer y configurar su asignación de tablas

Paso 2: Creación de una conexión de datos de Cosmos DB

Paso 3: Probar la conexión de datos

Requisitos previos

Paso 1: Elegir una tabla de Azure Data Explorer y configurar su asignación de tablas

Antes de crear una conexión de datos, cree una tabla donde almacenará los datos ingeridos y aplicará una asignación que coincida con el esquema en el contenedor de Cosmos DB de origen. Si el escenario requiere más de una asignación simple de campos, puede usar directivas de actualización para transformar y asignar datos ingeridos desde la fuente de cambios.

A continuación se muestra un esquema de ejemplo de un elemento en el contenedor de Cosmos DB:

{
    "id": "17313a67-362b-494f-b948-e2a8e95e237e",
    "name": "Cousteau",
    "_rid": "pL0MAJ0Plo0CAAAAAAAAAA==",
    "_self": "dbs/pL0MAA==/colls/pL0MAJ0Plo0=/docs/pL0MAJ0Plo0CAAAAAAAAAA==/",
    "_etag": "\"000037fc-0000-0700-0000-626a44110000\"",
    "_attachments": "attachments/",
    "_ts": 1651131409
}

Siga estos pasos para crear una tabla y aplicar una asignación de tabla:

  1. En la interfaz de usuario web de Azure Data Explorer, en el menú de navegación izquierdo, seleccione Consulta y, a continuación, seleccione la base de datos donde desea crear la tabla.

  2. Ejecute el siguiente comando para crear una tabla denominada TestTable.

    .create table TestTable(Id:string, Name:string, _ts:long, _timestamp:datetime)

  3. Ejecute el siguiente comando para crear la asignación de tablas.

    El comando asigna propiedades personalizadas de un documento JSON de Cosmos DB a columnas de la tabla TestTable , como se indica a continuación:

    Propiedad de Cosmos DB Columna de tabla Transformación
    id Identificador None
    name Nombre None
    _Ts _ts None
    _Ts _Timestamp Usa DateTimeFromUnixSeconds para transformar_ts (segundos unix) para _timestamp (datetime))

    Nota

    Se recomienda usar las siguientes columnas de marca de tiempo:

    • _ts: use esta columna para conciliar los datos con Cosmos DB.
    • _timestamp: use esta columna para ejecutar filtros de tiempo eficaces en las consultas de Kusto. Para obtener más información, consulte Procedimiento recomendado de consulta.
    .create table TestTable ingestion json mapping "DocumentMapping"
```
[
    {"column":"Id","path":"$.id"},
    {"column":"Name","path":"$.name"},
    {"column":"_ts","path":"$._ts"},
    {"column":"_timestamp","path":"$._ts", "transform":"DateTimeFromUnixSeconds"}
]
```

Transformación y asignación de datos con directivas de actualización

Si el escenario requiere más de una asignación simple de campos, puede usar directivas de actualización para transformar y asignar datos ingeridos desde la fuente de cambios.

Las directivas de actualización son una manera de transformar los datos a medida que se ingieren en la tabla. Se escriben en Lenguaje de consulta Kusto y se ejecutan en la canalización de ingesta. Se pueden usar para transformar datos de una ingesta de fuente de cambios de Cosmos DB, como en los escenarios siguientes:

  • Los documentos contienen matrices que serían más fáciles de consultar si se transforman en varias filas mediante el mv-expand operador .
  • Desea filtrar los documentos. Por ejemplo, puede filtrar documentos por tipo mediante el where operador .
  • Tiene lógica compleja que no se puede representar en una asignación de tabla.

Para obtener información sobre cómo crear y administrar directivas de actualización, consulte Introducción a la directiva de actualización.

Paso 2: Creación de una conexión de datos de Cosmos DB

Puede usar los métodos siguientes para crear el conector de datos:

  1. En el Azure Portal, vaya a la página de información general del clúster y seleccione la pestaña Introducción.

  2. En el icono Ingesta de datos, seleccione Crear conexión> de datosde Cosmos DB.

    Captura de pantalla de la pestaña Introducción, en la que se muestra la opción Crear conexión de datos de Cosmos DB.

  3. En el panel Crear conexión de datos de Cosmos DB, rellene el formulario con la información de la tabla:

    Captura de pantalla del panel de conexión de datos, que muestra los campos de formulario con valores.

    Campo Descripción
    Nombre de la base de datos Elija la base de datos de Azure Data Explorer en la que desea ingerir datos.
    Nombre de la conexión de datos Especifique un nombre para la conexión de datos.
    Suscripción Seleccione la suscripción que contiene la cuenta noSQL de Cosmos DB.
    Cuenta de Cosmos DB Elija la cuenta de Cosmos DB desde la que desea ingerir datos.
    SQL database Elija la base de datos de Cosmos DB desde la que desea ingerir datos.
    Contenedor de SQL Elija el contenedor de Cosmos DB desde el que desea ingerir datos.
    Nombre de la tabla Especifique el nombre de la tabla de Azure Data Explorer al que desea ingerir datos.
    Nombre de asignación Opcionalmente, especifique el nombre de asignación que se usará para la conexión de datos.

  4. Opcionalmente, en la sección Configuración avanzada , haga lo siguiente:

    1. Especifique la fecha de inicio de recuperación de eventos. Esta es la hora a partir de la cual el conector comenzará a ingerir datos. Si no especifica una hora, el conector comenzará a ingerir datos desde el momento en que cree la conexión de datos. El formato de fecha recomendado es el estándar ISO 8601 UTC, especificado de la siguiente manera: yyyy-MM-ddTHH:mm:ss.fffffffZ.

    2. Seleccione Asignado por el usuario y, a continuación, seleccione la identidad. De forma predeterminada, la conexión usa la identidad administrada asignada por el sistema . Si es necesario, puede usar una identidad asignada por el usuario .

      Captura de pantalla del panel de conexión de datos, que muestra la configuración avanzada.

  5. Seleccione Crear para guardar la conexión de datos.

Paso 3: Probar la conexión de datos

  1. En el contenedor de Cosmos DB, inserte el siguiente documento:

    {
    "name":"Cousteau"
}

  2. En la interfaz de usuario web de Azure Data Explorer, ejecute la consulta siguiente:

    TestTable

    El conjunto de resultados debe tener un aspecto similar al de la siguiente imagen:

    Captura de pantalla del panel de resultados, que muestra el documento ingerido.

Nota

Azure Data Explorer tiene una directiva de agregación (procesamiento por lotes) para la ingesta de datos en cola diseñada para optimizar el proceso de ingesta. La directiva de procesamiento por lotes predeterminada se configura para sellar un lote una vez que se cumple una de las condiciones siguientes para el lote: un tiempo de retraso máximo de 5 minutos, el tamaño total de un GB o 1000 blobs. Por lo tanto, puede experimentar una latencia. Para obtener más información, consulte la directiva de procesamiento por lotes. Para reducir la latencia, configure la tabla para admitir el streaming. Consulte la directiva de streaming.

Consideraciones

Las consideraciones siguientes se aplican a la fuente de cambios de Cosmos DB:

  • La fuente de cambios no expone eventos de eliminación .

    La fuente de cambios de Cosmos DB solo incluye documentos nuevos y actualizados. Si necesita conocer los documentos eliminados, puede configurar su feed utilizando un marcador suave para marcar un documento de Cosmos DB como eliminado. Se agrega una propiedad para actualizar eventos que indican si se ha eliminado un documento. A continuación, puede usar el where operador en las consultas para filtrarlos.

    Por ejemplo, si asigna la propiedad eliminada a una columna de tabla denominada IsDeleted, puede filtrar los documentos eliminados con la consulta siguiente:

    TestTable
| where not(IsDeleted)

  • La fuente de cambios solo expone la actualización más reciente de un documento.

    Para comprender la ramificación de la segunda consideración, examine el siguiente escenario:

    Un contenedor de Cosmos DB contiene documentos A y B. Los cambios en una propiedad denominada foo se muestran en la tabla siguiente:

    Id. de documento Propiedad foo Evento Marca de tiempo del documento (_ts)
    A Rojo Creación 10
    N Azul Creación 20
    A Naranja Actualizar 30
    A Rosa Actualizar 40
    B Violeta Actualizar 50
    A Carmine Actualizar 50
    N NeonBlue Actualizar 70

    El conector de datos sondea la API de fuente de cambios a intervalos regulares, normalmente cada pocos segundos. Cada sondeo contiene cambios que se produjeron en el contenedor entre llamadas, pero solo la versión más reciente del cambio por documento.

    Para ilustrar el problema, considere una secuencia de llamadas API con marcas de tiempo 15, 35, 55 y 75 , como se muestra en la tabla siguiente:

    Marca de tiempo de llamada de API Id. de documento Propiedad foo Marca de tiempo del documento (_ts)
    15 A Rojo 10
    35 B Azul 20
    35 A Naranja 30
    55 B Violeta 50
    55 A Carmine 60
    75 B NeonBlue 70

    Al comparar los resultados de la API con la lista de cambios realizados en el documento de Cosmos DB, observará que no coinciden. El evento de actualización para documentar A, resaltado en la tabla de cambios en la marca de tiempo 40, no aparece en los resultados de la llamada API.

    Para comprender por qué el evento no aparece, examinaremos los cambios en el documento A entre las llamadas API en las marcas de tiempo 35 y 55. Entre estas dos llamadas, documente Un cambio dos veces, como se indica a continuación:

    Id. de documento Propiedad foo Evento Marca de tiempo del documento (_ts)
    A Rosa Actualizar 40
    A Carmine Actualizar 50

    Cuando se realiza la llamada API en la marca de tiempo 55, la API de fuente de cambios devuelve la versión más reciente del documento. En este caso, la versión más reciente del documento A es la actualización en la marca de tiempo 50, que es la actualización de la propiedad foo de Pink a Carmine.

    Debido a este escenario, el conector de datos puede perder algunos cambios intermedios en el documento. Por ejemplo, es posible que se pierdan algunos eventos si el servicio de conexión de datos está inactivo durante unos minutos, o si la frecuencia de cambios del documento es mayor que la frecuencia de sondeo de la API. Sin embargo, se captura el estado más reciente de cada documento.

  • No se admite la eliminación y recreación de un contenedor de Cosmos DB

    Azure Data Explorer realiza un seguimiento de la fuente de cambios comprobando la "posición" en la que se encuentra en la fuente. Esto se hace utilizando token de continuación en cada partición física del contenedor. Cuando se elimina/recrea un contenedor, esos token de continuación no son válidos y no se restablecen: debe eliminar y volver a crear la conexión de datos.

Estimación del costo

¿Cuánto afecta el uso de la conexión de datos de Cosmos DB a las unidades de solicitud (RU) del contenedor de Cosmos DB?

El conector invoca la API de fuente de cambios de Cosmos DB en cada partición física del contenedor, hasta una vez por segundo. Los siguientes costos están asociados a estas invocaciones:

Coste Descripción
Costos fijos Los costos fijos son aproximadamente 2 RU por partición física cada segundo.
Costos variables Los costos variables son aproximadamente el 2 % de las RU que se usan para escribir documentos, aunque esto puede variar en función de su escenario. Por ejemplo, si escribe 100 documentos en un contenedor de Cosmos DB, el costo de escribir esos documentos es de 1000 RU. El costo correspondiente para usar el conector para leer ese documento es aproximadamente el 2 % el costo de escribirlos, aproximadamente 20 RU.

Contenido relacionado