Inserire dati da Azure Cosmos DB in Azure Esplora dati

Azure Esplora dati supporta l'inserimentodati da Azure Cosmos DB per NoSql usando un feed di modifiche. La connessione dati del feed di modifiche di Cosmos DB è una pipeline di inserimento in ascolto del feed di modifiche di Cosmos DB e inserisce i dati nella tabella Esplora dati. Il feed di modifiche è in ascolto dei documenti nuovi e aggiornati, ma non registra le eliminazioni. Per informazioni generali sull'inserimento dati in Azure Esplora dati, vedere Panoramica dell'inserimento di dati in Azure Esplora dati.

Ogni connessione dati è in ascolto di un contenitore Cosmos DB specifico e inserisce i dati in una tabella specificata (più di una connessione può inserire in una singola tabella). Il metodo di inserimento supporta l'inserimento in streaming (se abilitato) e l'inserimento in coda.

I due scenari principali per l'uso della connessione dati del feed di modifiche di Cosmos DB sono:

• Replica di un contenitore Cosmos DB a scopo analitico. Per altre informazioni, vedere Ottenere le versioni più recenti dei documenti di Azure Cosmos DB.
• Analisi delle modifiche al documento in un contenitore Cosmos DB. Per maggiori informazioni, consultare Considerazioni.

Questo articolo illustra come configurare una connessione ai dati del feed di modifiche di Cosmos DB per inserire dati in Azure Esplora dati con Identità gestita di sistema. Esaminare le considerazioni prima di iniziare.

Per configurare un connettore, seguire questa procedura:

Passaggio 1: Scegliere una tabella Esplora dati di Azure e configurarne il mapping delle tabelle

Passaggio 2: Creare una connessione dati di Cosmos DB

Passaggio 3: Testare la connessione dati

Prerequisiti

• Una sottoscrizione di Azure. Creare un account Azure gratuito.
• Un cluster e un database di Esplora dati di Azure. Creare un cluster e un database.
• Contenitore da un account Cosmos DB per NoSQL.
• Se l'account Cosmos DB blocca l'accesso alla rete, ad esempio usando un endpoint privato, è necessario creare un endpoint privato gestito per l'account Cosmos DB. Questa operazione è necessaria per il cluster per richiamare l'API del feed di modifiche.

Passaggio 1: Scegliere una tabella Esplora dati di Azure e configurarne il mapping delle tabelle

Prima di creare una connessione dati, creare una tabella in cui archiviare i dati inseriti e applicare un mapping corrispondente allo schema nel contenitore Cosmos DB di origine. Se lo scenario richiede più di un semplice mapping dei campi, è possibile usare i criteri di aggiornamento per trasformare e mappare i dati inseriti dal feed di modifiche.

Di seguito è illustrato uno schema di esempio di un elemento nel contenitore 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
}

Usare la procedura seguente per creare una tabella e applicare un mapping di tabella:

1. Nell'interfaccia utente Web di Azure Esplora dati selezionare Query dal menu di spostamento a sinistra e quindi selezionare il database in cui si vuole creare la tabella.

2. Eseguire il comando seguente per creare una tabella denominata TestTable.

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

3. Eseguire il comando seguente per creare il mapping della tabella.

   Il comando esegue il mapping delle proprietà personalizzate da un documento JSON di Cosmos DB alle colonne nella tabella TestTable , come indicato di seguito:

   Proprietà di Cosmos DB	Colonna tabella	Trasformazione
   id	ID.	None
   name	Nome	None
   _Ts	_ts	None
   _Ts	_Timestamp	DateTimeFromUnixSeconds Usa per trasformare_ts (secondi UNIX) in _timestamp (datetime))

   Nota

   È consigliabile usare le colonne timestamp seguenti:

   • _ts: usare questa colonna per riconciliare i dati con Cosmos DB.
   • _timestamp: usare questa colonna per eseguire filtri temporali efficienti nelle query Kusto. Per altre informazioni, vedere Procedura consigliata per le query.

   .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"}
   ]
   ```
   

Trasformare ed eseguire il mapping dei dati con i criteri di aggiornamento

Se lo scenario richiede più di un semplice mapping dei campi, è possibile usare i criteri di aggiornamento per trasformare e mappare i dati inseriti dal feed di modifiche.

I criteri di aggiornamento sono un modo per trasformare i dati durante l'inserimento nella tabella. Vengono scritti in Linguaggio di query Kusto e vengono eseguiti nella pipeline di inserimento. Possono essere usati per trasformare i dati da un inserimento di feed di modifiche di Cosmos DB, ad esempio negli scenari seguenti:

• I documenti contengono matrici che sarebbero più facili da eseguire se vengono trasformate in più righe usando l'operatore mv-expand .
• Si desidera filtrare i documenti. Ad esempio, è possibile filtrare i documenti in base al tipo usando l'operatore where .
• È presente una logica complessa che non può essere rappresentata in un mapping di tabella.

Per informazioni su come creare e gestire i criteri di aggiornamento, vedere Panoramica dei criteri di aggiornamento.

Passaggio 2: Creare una connessione dati di Cosmos DB

Per creare il connettore dati, è possibile usare i metodi seguenti:

Azure portal

1. Nella portale di Azure passare alla pagina di panoramica del cluster e quindi selezionare la scheda Attività iniziali.

2. Nel riquadro Inserimentodati selezionare >dati Cosmos DB.

   

3. Nel riquadro Crea connessione dati di Cosmos DB compilare il modulo con le informazioni nella tabella:

   

   Campo	Descrizione
   Nome database	Scegliere il database di Azure Esplora dati in cui inserire i dati.
   Nome connessione dati	Specificare un nome per la connessione dati.
   Abbonamento	Selezionare la sottoscrizione che contiene l'account NoSQL di Cosmos DB.
   Account Cosmos DB	Scegliere l'account Cosmos DB da cui inserire i dati.
   Database SQL	Scegliere il database Cosmos DB da cui inserire i dati.
   Contenitore SQL	Scegliere il contenitore Cosmos DB da cui inserire i dati.
   Nome tabella	Specificare il nome della tabella Esplora dati di Azure a cui inserire i dati.
   Nome mapping	Facoltativamente, specificare il nome del mapping da usare per la connessione dati.

4. Facoltativamente, nella sezione Impostazioni avanzate eseguire le operazioni seguenti:

   1. Specificare la data di inizio del recupero eventi. Questo è l'ora da cui il connettore inizierà l'inserimento dei dati. Se non si specifica un'ora, il connettore avvierà l'inserimento dei dati dal momento in cui si crea la connessione dati. Il formato di data consigliato è lo standard UTC ISO 8601, specificato come segue: yyyy-MM-ddTHH:mm:ss.fffffffZ.

   2. Selezionare Assegnata dall'utente e quindi selezionare l'identità. Per impostazione predefinita, l'identità gestita assegnata dal sistema viene usata dalla connessione. Se necessario, è possibile usare un'identità assegnata dall'utente .

      

5. Selezionare Crea per creare la connessione dati.

Modello ARM

Usare il modello di Resource Manager di esempio seguente come base per creare un modello di connessione dati personalizzato e quindi distribuirlo nella portale di Azure.

Per configurare la connessione a Cosmos DB:

1. Configurare un'identità gestita dal sistema per l'autenticazione della connessione cosmos DB.

   1. Nell'interfaccia utente Web di Azure Esplora dati selezionare Query dal menu di spostamento a sinistra e quindi selezionare il cluster o il database per la connessione dati.

2. Concedere l'autorizzazione di connessione dati per accedere all'account Cosmos DB. Fornire l'accesso alla connessione dati a Cosmos DB consente di accedere e recuperare dati dal database. È necessario l'ID entità del cluster, disponibile nella portale di Azure. Per altre informazioni, vedere Configurare le identità gestite per il cluster.

   Nota

   • La procedura seguente assegna questi ruoli all'ID entità:
     • Lettore dati predefinito di Cosmos DB
       • Non è possibile assegnare il ruolo lettore dati predefinito di Cosmos DB usando la funzionalità di assegnazione di ruolo portale di Azure.
     • Ruolo Lettore dell'account Cosmos DB

   Usare una delle opzioni seguenti per concedere l'accesso all'account Cosmos DB:

   • Concedere l'accesso usando l'interfaccia della riga di comando di Azure: eseguire il comando dell'interfaccia della riga di comando usando le informazioni nella tabella seguente per sostituire i segnaposto con i valori appropriati:

     az cosmosdb sql role assignment create --account-name <CosmosDbAccountName> --resource-group <CosmosDbResourceGroup> --role-definition-id 00000000-0000-0000-0000-000000000001 --principal-id <ClusterPrincipalId> --scope "/"
     
     az role assignment create --role fbdf93bf-df7d-467e-a4d2-9458aa1360c8 --assignee <ClusterPrincipalId> --scope <CosmosDBAccountResourceId>
     

     Segnaposto	Descrizione
     <CosmosDBAccountName>	Nome dell'account Cosmos DB.
     <CosmosDBResourceGroup>	Nome del gruppo di risorse che contiene l'account Cosmos DB.
     <CosmosDBAccountResourceId>	ID risorsa di Azure (a partire da subscriptions/) dell'account Cosmos DB.
     <ClusterPrincipalId>	ID principale dell'identità gestita assegnata al cluster. L'ID principale del cluster è disponibile nella portale di Azure. Per altre informazioni, vedere Configurare le identità gestite per il cluster.

   • Concedere l'accesso usando un modello di Resource Manager: distribuire il modello seguente nel gruppo di risorse dell'account Cosmos DB:

     {
         "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
         "contentVersion": "1.0.0.0",
         "parameters": {
             "clusterPrincipalId": {
                 "type": "string",
                 "metadata": { "description": "The principle ID of your cluster." }
             },
             "cosmosDbAccount": {
                 "type": "string",
                 "metadata": { "description": "The name of your Cosmos DB account." }
             },
             "cosmosDbAccountResourceId": {
                 "type": "string",
                 "metadata": { "description": "The resource ID of your Cosmos DB account." }
             }
         },
         "variables": {
             "cosmosDataReader": "00000000-0000-0000-0000-000000000001",
             "dataRoleDefinitionId": "[format('/subscriptions/{0}/resourceGroups/{1}/providers/Microsoft.DocumentDB/databaseAccounts/{2}/sqlRoleDefinitions/{3}', subscription().subscriptionId, resourceGroup().name, parameters('cosmosDbAccount'), variables('cosmosDataReader'))]",
             "roleAssignmentId": "[guid(parameters('cosmosDbAccountResourceId'), parameters('clusterPrincipalId'))]",
             "rbacRoleDefinitionId": "[format('/subscriptions/{0}/providers/Microsoft.Authorization/roleDefinitions/{1}', subscription().subscriptionId, 'fbdf93bf-df7d-467e-a4d2-9458aa1360c8')]"
         },
         "resources": [
             {
                 "type": "Microsoft.DocumentDB/databaseAccounts/sqlRoleAssignments",
                 "apiVersion": "2022-08-15",
                 "name": "[concat(parameters('cosmosDbAccount'), '/', guid(parameters('clusterPrincipalId'), parameters('cosmosDbAccount')))]",
                 "properties": {
                     "principalId": "[parameters('clusterPrincipalId')]",
                     "roleDefinitionId": "[variables('dataRoleDefinitionId')]",
                     "scope": "[resourceId('Microsoft.DocumentDB/databaseAccounts', parameters('cosmosDbAccount'))]"
                 }
             },
             {
                 "type": "Microsoft.Authorization/roleAssignments",
                 "apiVersion": "2022-04-01",
                 "name": "[variables('roleAssignmentId')]",
                 "scope": "[format('Microsoft.DocumentDb/databaseAccounts/{0}', parameters('cosmosDbAccount'))]",
                 "properties": {
                     "description": "Giving RBAC reader on Cosmos DB",
                     "principalId": "[parameters('clusterPrincipalId')]",
                     "principalType": "ServicePrincipal",
                     "roleDefinitionId": "[variables('rbacRoleDefinitionId')]"
                 }
             }
         ]
     }
     

3. Distribuire il modello di Resource Manager seguente per creare una connessione dati di Cosmos DB. Sostituire i segnaposto con i valori appropriati.

   {
     "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
     "contentVersion": "1.0.0.0",
     "parameters": {
       "kustoClusterName": {
         "type": "string",
         "metadata": { "description": "Kusto Cluster name" }
       },
       "kustoDbName": {
         "type": "string",
         "metadata": { "description": "Kusto Database name" }
       },
       "kustoConnectionName": {
         "type": "string",
         "metadata": { "description": "Kusto Database connection name" }
       },
       "kustoLocation": {
         "type": "string",
         "metadata": { "description": "Location (Azure Region) of the Kusto cluster" }
       },
       "kustoTable": {
         "type": "string",
         "metadata": { "description": "Kusto Table name where to ingest data" }
       },
       "kustoMappingRuleName": {
         "type": "string",
         "defaultValue": "",
         "metadata": { "description": "Mapping name of the Kusto Table (if omitted, default mapping is applied)" }
       },
       "managedIdentityResourceId": {
         "type": "string",
         "metadata": { "description": "ARM resource ID of the managed identity (cluster resource ID for system or user identity)" }
       },
       "cosmosDbAccountResourceId": {
         "type": "string",
         "metadata": { "description": "ARM resource ID of Cosoms DB account" }
       },
       "cosmosDbDatabase": {
         "type": "string",
         "metadata": { "description": "Cosmos DB Database name" }
       },
       "cosmosDbContainer": {
         "type": "string",
         "metadata": { "description": "Cosmos DB container name" }
       },
       "retrievalStartDate": {
         "type": "string",
         "defaultValue": "",
         "metadata": { "description": "Date-time at which to start the data retrieval; default: 'now' if not provided. Recommended format: yyyy-MM-ddTHH:mm:ss.fffffffZ" }
       }
     },
     "variables": { },
     "resources": [{
       "type": "Microsoft.Kusto/Clusters/Databases/DataConnections",
       "apiVersion": "2022-11-11",
       "name": "[concat(parameters('kustoClusterName'), '/', parameters('kustoDbName'), '/', parameters('kustoConnectionName'))]",
       "location": "[parameters('kustoLocation')]",
       "kind": "CosmosDb",
       "properties": {
         "tableName": "[parameters('kustoTable')]",
         "mappingRuleName": "[parameters('kustoMappingRuleName')]",
         "managedIdentityResourceId": "[parameters('managedIdentityResourceId')]",
         "cosmosDbAccountResourceId": "[parameters('cosmosDbAccountResourceId')]",
         "cosmosDbDatabase": "[parameters('cosmosDbDatabase')]",
         "cosmosDbContainer": "[parameters('cosmosDbContainer')]",
         "retrievalStartDate": "[parameters('retrievalStartDate')]"
       }
     }]
   }
   

Passaggio 3: Testare la connessione dati

1. Nel contenitore Cosmos DB inserire il documento seguente:

   {
       "name":"Cousteau"
   }
   

2. Nell'interfaccia utente Web di Azure Esplora dati eseguire la query seguente:

   TestTable
   

   Il set di risultati sarà simile all’immagine seguente:

   

Nota

Azure Esplora dati dispone di criteri di aggregazione (invio in batch) per l'inserimento dati in coda progettato per ottimizzare il processo di inserimento. I criteri di invio in batch predefiniti sono configurati per bloccare un batch una volta soddisfatta una delle condizioni seguenti per il batch: un tempo massimo di ritardo di 5 minuti, dimensioni totali di un GB o 1000 BLOB. Di conseguenza, è possibile che si verifichi una latenza. Per altre informazioni vedere Criteri di invio in batch. Per ridurre la latenza, configurare la tabella per supportare lo streaming. Vedere Criteri di streaming.

Considerazioni

Le considerazioni seguenti si applicano al feed di modifiche di Cosmos DB:

• Il feed di modifiche non espone gli eventi di eliminazione .

  Il feed di modifiche di Cosmos DB include solo documenti nuovi e aggiornati. Se è necessario conoscere i documenti eliminati, è possibile configurare il feed usando un marcatore soft per contrassegnare un documento di Cosmos DB come eliminato. Viene aggiunta una proprietà per aggiornare gli eventi che indicano se un documento è stato eliminato. È quindi possibile usare l'operatore where nelle query per filtrarli.

  Ad esempio, se si esegue il mapping della proprietà eliminata a una colonna di tabella denominata IsDeleted, è possibile filtrare i documenti eliminati con la query seguente:

  TestTable
  | where not(IsDeleted)
  

• Il feed di modifiche espone solo l'aggiornamento più recente di un documento.

  Per comprendere la ramificazione della seconda considerazione, esaminare lo scenario seguente:

  Un contenitore Cosmos DB contiene documenti A e B. Le modifiche apportate a una proprietà denominata foo sono illustrate nella tabella seguente:

  ID documento	Foo proprietà	Event	Timestamp del documento (_ts)
  Un	Rosso	Creazione	10
  G	Blu	Creazione	20
  Un	Orange	Update	30
  A	Rosa	Aggiornamento	40
  G	Viola	Update	50
  Un	Carminio	Update	50
  G	NeonBlue	Update	70

  L'API del feed di modifiche viene eseguita dal connettore dati a intervalli regolari, in genere ogni pochi secondi. Ogni poll contiene modifiche apportate nel contenitore tra le chiamate, ma solo la versione più recente della modifica per documento.

  Per illustrare il problema, considerare una sequenza di chiamate API con timestamp 15, 35, 55 e 75 , come illustrato nella tabella seguente:

  Timestamp chiamata API	ID documento	Foo proprietà	Timestamp del documento (_ts)
  15	Un	Rosso	10
  35	G	Blu	20
  35	Un	Orange	30
  55	G	Viola	50
  55	Un	Carminio	60
  75	G	NeonBlue	70

  Confrontando i risultati dell'API con l'elenco delle modifiche apportate nel documento di Cosmos DB, si noterà che non corrispondono. L'evento di aggiornamento al documento A, evidenziato nella tabella delle modifiche al timestamp 40, non viene visualizzato nei risultati della chiamata API.

  Per comprendere il motivo per cui l'evento non viene visualizzato, verranno esaminate le modifiche apportate al documento A tra le chiamate API ai timestamp 35 e 55. Tra queste due chiamate, documento A modificato due volte, come indicato di seguito:

  ID documento	Foo proprietà	Event	Timestamp del documento (_ts)
  Un	Rosa	Update	40
  Un	Carminio	Update	50

  Quando viene eseguita la chiamata API al timestamp 55, l'API del feed di modifiche restituisce la versione più recente del documento. In questo caso, la versione più recente del documento A è l'aggiornamento al timestamp 50, che è l'aggiornamento alla proprietà foo da Pink a Esegue.

  A causa di questo scenario, il connettore dati potrebbe perdere alcune modifiche intermedie al documento. Ad esempio, alcuni eventi potrebbero non essere rilevati se il servizio connessione dati è inattivo per alcuni minuti o se la frequenza di modifica del documento è superiore alla frequenza di polling dell'API. Tuttavia, viene acquisito lo stato più recente di ogni documento.

• L'eliminazione e la ricreazione di un contenitore Cosmos DB non sono supportate

  Azure Esplora dati tiene traccia del feed di modifiche eseguendo il checkpoint della "posizione" in cui si trova nel feed. Questa operazione viene eseguita usando il token di continuazione in ogni partizione fisica del contenitore. Quando un contenitore viene eliminato/ricreato, il token di continuazione non è valido e non viene reimpostato. In questo caso, è necessario eliminare e ricreare la connessione dati.

Stimare i costi

Quanto influisce sull'uso della connessione dati di Cosmos DB sull'utilizzo delle unità richiesta (UR) del contenitore Cosmos DB?

Il connettore richiama l'API feed di modifiche di Cosmos DB in ogni partizione fisica del contenitore, fino a una volta al secondo. I costi seguenti sono associati a queste chiamate:

Costo	Descrizione
Costi fissi	I costi fissi sono circa 2 UR per partizione fisica ogni secondo.
Costi variabili	I costi variabili sono circa il 2% delle UR usate per scrivere documenti, anche se questo può variare a seconda dello scenario. Ad esempio, se si scrivono 100 documenti in un contenitore Cosmos DB, il costo di scrittura di tali documenti è di 1.000 UR. Il costo corrispondente per l'uso del connettore per leggere il documento è circa il 2% del costo per scriverli, circa 20 UR.

Contenuto correlato

• Ottenere le versioni più recenti dei documenti di Azure Cosmos DB
• Panoramica di Linguaggio di query Kusto (KQL)