Ingerir dados do Azure Cosmos DB para o Azure Data Explorer

O Azure Data Explorer suporta a ingestão de dados do Azure Cosmos DB para NoSql com um feed de alterações. A ligação de dados do feed de alterações do Cosmos DB é um pipeline de ingestão que escuta o feed de alterações do Cosmos DB e ingere os dados na sua tabela de Data Explorer. O feed de alterações escuta documentos novos e atualizados, mas não regista eliminações. Para obter informações gerais sobre a ingestão de dados no Azure Data Explorer, veja Descrição geral da ingestão de dados do Azure Data Explorer.

Cada ligação de dados escuta um contentor específico do Cosmos DB e ingere dados numa tabela especificada (mais do que uma ligação pode ingerir numa única tabela). O método de ingestão suporta a ingestão de transmissão em fluxo (quando ativada) e a ingestão em fila.

Neste artigo, irá aprender a configurar uma ligação de dados de feed de alterações do Cosmos DB para ingerir dados no Azure Data Explorer com a Identidade Gerida do Sistema. Reveja as considerações antes de começar.

Utilize os seguintes passos para configurar um conector:

Passo 1: escolher uma tabela do Azure Data Explorer e configurar o mapeamento da tabela

Passo 2: Criar uma ligação de dados do Cosmos DB

Passo 3: testar a ligação de dados

Pré-requisitos

Passo 1: escolher uma tabela do Azure Data Explorer e configurar o mapeamento da tabela

Antes de criar uma ligação de dados, crie uma tabela onde irá armazenar os dados ingeridos e aplicar um mapeamento que corresponda ao esquema no contentor do Cosmos DB de origem. Se o seu cenário exigir mais do que um mapeamento simples de campos, pode utilizar políticas de atualização para transformar e mapear dados ingeridos a partir do feed de alterações.

O seguinte mostra um esquema de exemplo de um item no contentor do 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
}

Utilize os seguintes passos para criar uma tabela e aplicar um mapeamento de tabela:

  1. Na IU do Azure Data Explorer Web, no menu de navegação esquerdo, selecione Consulta e, em seguida, selecione a base de dados onde pretende criar a tabela.

  2. Execute o seguinte comando para criar uma tabela denominada TestTable.

    .create table TestTable(Id:string, Name:string, _ts:long, _timestamp:datetime)
    
  3. Execute o seguinte comando para criar o mapeamento da tabela.

    O comando mapeia propriedades personalizadas de um documento JSON do Cosmos DB para colunas na tabela TestTable , da seguinte forma:

    Propriedade cosmos DB Coluna de tabela Transformação
    id Id Nenhuma
    nome Name Nenhuma
    _ts _ts Nenhuma
    _ts _timestamp Utiliza DateTimeFromUnixSeconds para transformar_ts (segundos UNIX) para _timestamp (datetime))

    Nota

    Recomendamos que utilize as seguintes colunas de carimbo de data/hora:

    • _ts: utilize esta coluna para reconciliar dados com o Cosmos DB.
    • _timestamp: utilize esta coluna para executar filtros de tempo eficientes nas suas consultas kusto. Para obter mais informações, veja Melhores práticas 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"}
    ]
    ```
    

Transformar e mapear dados com políticas de atualização

Se o seu cenário exigir mais do que um mapeamento simples de campos, pode utilizar políticas de atualização para transformar e mapear dados ingeridos a partir do feed de alterações.

As políticas de atualização são uma forma de transformar dados à medida que são ingeridos na sua tabela. São escritas em Linguagem de Pesquisa Kusto e executadas no pipeline de ingestão. Podem ser utilizados para transformar dados de uma ingestão de feeds de alterações do Cosmos DB, como nos seguintes cenários:

  • Os seus documentos contêm matrizes que seriam mais fáceis de consultar se fossem transformados em múltiplas linhas com o mv-expand operador.
  • Quer filtrar documentos. Por exemplo, pode filtrar documentos por tipo com o where operador.
  • Tem uma lógica complexa que não pode ser representada num mapeamento de tabelas.

Para obter informações sobre como criar e gerir políticas de atualização, veja Descrição geral da política de atualização.

Passo 2: Criar uma ligação de dados do Cosmos DB

Pode utilizar os seguintes métodos para criar o conector de dados:

  1. No portal do Azure, aceda à página de descrição geral do cluster e, em seguida, selecione o separador Introdução.

  2. No mosaico Ingestão de dados, selecione Criar ligação> de dadosCosmos DB.

    Captura de ecrã a mostrar o separador Introdução, com a opção Criar ligação de dados do Cosmos DB.

  3. No painel Criar ligação de dados do Cosmos DB, preencha o formulário com as informações na tabela:

    Captura de ecrã do painel de ligação de dados a mostrar os campos de formulário com valores.

    Campo Descrição
    Nome da base de dados Selecione a base de dados do Azure Data Explorer na qual pretende ingerir dados.
    Nome da ligação de dados Especifique um nome para a ligação de dados.
    Subscrição Selecione a subscrição que contém a sua conta NoSQL do Cosmos DB.
    Conta do Cosmos DB Selecione a conta do Cosmos DB a partir da qual pretende ingerir dados.
    Base de dados SQL Escolha a base de dados do Cosmos DB a partir da qual pretende ingerir dados.
    Contentor SQL Escolha o contentor do Cosmos DB a partir do qual pretende ingerir dados.
    Nome da tabela Especifique o nome da tabela Data Explorer do Azure ao qual pretende ingerir dados.
    Nome do mapeamento Opcionalmente, especifique o nome de mapeamento a utilizar para a ligação de dados.
  4. Opcionalmente, na secção Definições avançadas , faça o seguinte:

    1. Especifique a data de início da obtenção de eventos. Este é o momento a partir do qual o conector começará a ingerir dados. Se não especificar uma hora, o conector começará a ingerir dados a partir do momento em que criar a ligação de dados. O formato de data recomendado é a norma ISO 8601 UTC, especificada da seguinte forma: yyyy-MM-ddTHH:mm:ss.fffffffZ.

    2. Selecione Atribuído pelo utilizador e, em seguida, selecione a identidade. Por Predefinição, a identidade gerida atribuída pelo sistema é utilizada pela ligação. Se necessário, pode utilizar uma identidade atribuída pelo utilizador .

      Captura de ecrã do painel de ligação de dados a mostrar as definições Avançar.

  5. Selecione Criar para colocar a ligação de dados em caixa.

Passo 3: testar a ligação de dados

  1. No contentor do Cosmos DB, insira o seguinte documento:

    {
        "name":"Cousteau"
    }
    
  2. Na IU do Azure Data Explorer Web, execute a seguinte consulta:

    TestTable
    

    O conjunto de resultados deve ter o seguinte aspeto:

    Captura de ecrã do painel de resultados a mostrar o documento ingerido.

Nota

O Azure Data Explorer tem uma política de agregação (batching) para ingestão de dados em fila concebida para otimizar o processo de ingestão. A política de criação de lotes predefinida é configurada para selar um lote quando uma das seguintes condições for verdadeira para o lote: um tempo de atraso máximo de 5 minutos, tamanho total de um GB ou 1000 blobs. Por conseguinte, poderá ter uma latência. Para obter mais informações, veja Política de criação de lotes. Para reduzir a latência, configure a tabela para suportar a transmissão em fluxo. Veja a política de transmissão em fluxo.

Considerações

As seguintes considerações aplicam-se ao feed de alterações do Cosmos DB:

  • O feed de alterações não expõe eventos de eliminação .

    O feed de alterações do Cosmos DB inclui apenas documentos novos e atualizados. Se precisar de saber mais sobre documentos eliminados, pode configurar o feed com um marcador suave para marcar um documento do Cosmos DB como eliminado. É adicionada uma propriedade para atualizar eventos que indicam se um documento foi eliminado. Em seguida, pode utilizar o where operador nas suas consultas para as filtrar.

    Por exemplo, se mapear a propriedade eliminada para uma coluna de tabela denominada IsDeleted, pode filtrar documentos eliminados com a seguinte consulta:

    TestTable
    | where not(IsDeleted)
    
  • O feed de alterações expõe apenas a atualização mais recente de um documento.

    Para compreender a ramificação da segunda consideração, examine o seguinte cenário:

    Um contentor do Cosmos DB contém os documentos A e B. As alterações a uma propriedade chamada foo são apresentadas na seguinte tabela:

    ID do Documento Foo de propriedade Evento Carimbo de data/hora do documento (_ts)
    A Vermelho Criação 10
    N Blue Criação 20
    A Laranja Atualizar 30
    A Cor-de-rosa Atualizar 40
    B Violeta Atualizar 50
    A Carmine Atualizar 50
    B NeonBlue Atualizar 70

    A API do feed de alterações é consultada pelo conector de dados em intervalos regulares, normalmente a cada poucos segundos. Cada inquérito contém alterações que ocorreram no contentor entre chamadas, mas apenas a versão mais recente da alteração por documento.

    Para ilustrar o problema, considere uma sequência de chamadas à API com carimbos de data/hora 15, 35, 55 e 75 , conforme mostrado na tabela seguinte:

    Carimbo de Data/Hora da Chamada da API ID do Documento Foo de propriedade Carimbo de data/hora do documento (_ts)
    15 A Vermelho 10
    35 B Blue 20
    35 A Laranja 30
    55 B Violeta 50
    55 A Carmine 60
    75 B Azul Néon 70

    Ao comparar os resultados da API com a lista de alterações efetuadas no documento do Cosmos DB, irá reparar que não correspondem. O evento de atualização para o documento A, realçado na tabela de alterações no carimbo de data/hora 40, não aparece nos resultados da chamada à API.

    Para compreender por que motivo o evento não aparece, vamos examinar as alterações ao documento A entre as chamadas à API nos carimbos de data/hora 35 e 55. Entre estas duas chamadas, o documento A foi alterado duas vezes, da seguinte forma:

    ID do Documento Foo de propriedade Evento Carimbo de data/hora do documento (_ts)
    A Cor-de-rosa Atualizar 40
    A Carmine Atualizar 50

    Quando a chamada à API no carimbo de data/hora 55 é efetuada, a API do feed de alterações devolve a versão mais recente do documento. Neste caso, a versão mais recente do documento A é a atualização no carimbo de data/hora 50, que é a atualização para a propriedade foo de Rosa para Carmine.

    Devido a este cenário, o conector de dados pode perder algumas alterações de documento intermédias. Por exemplo, alguns eventos podem ser perdidos se o serviço de ligação de dados estiver inativo durante alguns minutos ou se a frequência das alterações do documento for superior à frequência de consulta da API. No entanto, é capturado o estado mais recente de cada documento.

  • A eliminação e recriação de um contentor do Cosmos DB não é suportada

    O Azure Data Explorer controla o feed de alterações ao definir o ponto de verificação da "posição" em que se encontra no feed. Tal é feito com o token de continuação em cada partição física do contentor. Quando um contentor é eliminado/recriado, esses tokens de continuação são inválidos e não são repostos: tem de eliminar e recriar a ligação de dados.

Fazer uma estimativa dos custos

Quanto é que a utilização da ligação de dados do Cosmos DB afeta a utilização das Unidades de Pedido (RUs) do contentor do Cosmos DB?

O conector invoca a API do Feed de Alterações do Cosmos DB em cada partição física do contentor, até uma vez por segundo. Os seguintes custos estão associados a estas invocações:

Custo Description
Custos fixos Os custos fixos são cerca de 2 RUs por partição física a cada segundo.
Custos variáveis Os custos variáveis são cerca de 2% das RUs utilizadas para escrever documentos, embora isto possa variar consoante o seu cenário. Por exemplo, se escrever 100 documentos num contentor do Cosmos DB, o custo de escrever esses documentos é de 1000 RUs. O custo correspondente para utilizar o conector para ler esses documentos é cerca de 2% do custo de escrita, aproximadamente 20 RUs.