Inserire dati da Azure Cosmos DB in Azure Esplora dati

Azure Esplora dati supporta l'inserimento di dati 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 che ascolta il 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 dei 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 (quando abilitato) e l'inserimento in coda.

In questo articolo si apprenderà come configurare una connessione dati del feed di modifiche di Cosmos DB per inserire i 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 configurare 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.
• Un 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 all'account Cosmos DB. Questo è necessario per il cluster per richiamare l'API del feed di modifiche.

Passaggio 1: Scegliere una tabella Esplora dati di Azure e configurare 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 viene 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
}

Seguire questa procedura per creare una tabella e applicare un mapping di tabelle:

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:

   Cosmos DB, proprietà	Colonna della tabella	Trasformazione
   id	ID	Nessuno
   nome	NOME	Nessuno
   _ts	_ts	Nessuno
   _ts	_Timestamp	DateTimeFromUnixSeconds Usa per trasformare_ts (secondi UNIX) per _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 Procedure consigliate 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 e mappare i 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 del feed di modifiche di Cosmos DB, ad esempio negli scenari seguenti:

• I documenti contengono matrici che sarebbero più facili da eseguire per eseguire query se vengono trasformati 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 .
• È disponibile una logica complessa che non può essere rappresentata in un mapping di tabelle.

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

È possibile usare i metodi seguenti per creare il connettore dati:

Azure portal

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

2. Nel riquadro Inserimento dati selezionare Crea connessione> datiCosmos 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 Esplora dati di Azure in cui si desidera inserire i dati.
   Data connection name (Nome connessione dati)	Specificare un nome per la connessione dati.
   Sottoscrizione	Selezionare la sottoscrizione contenente l'account NoSQL di Cosmos DB.
   Account Cosmos DB	Scegliere l'account Cosmos DB da cui si desidera inserire i dati.
   Database SQL	Scegliere il database Cosmos DB da cui si desidera inserire i dati.
   Contenitore SQL	Scegliere il contenitore Cosmos DB da cui si desidera inserire i dati.
   Nome tabella	Specificare il nome della tabella di Azure Esplora dati a cui si desidera 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 è il momento in cui il connettore inizierà ad inserire i dati. Se non si specifica una volta, il connettore inizierà ad inserire i 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 Utente assegnato 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 arm di esempio seguente come base per la creazione di un modello di connessione dati personalizzato e quindi distribuirlo nella portale di Azure.

Per configurare la connessione 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. È possibile trovare l'ID principio del cluster nel 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 dovrebbe essere simile all'immagine seguente:

   

Nota

Azure Esplora dati dispone di un criterio di aggregazione (invio in batch) per l'inserimento dei 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. Pertanto, è 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:

  Document ID	Foo proprietà	Evento	Timestamp del documento (_ts)
  A	Red	Creazione	10
  B	Blu	Creazione	20
  Una	Orange	Aggiornamento	30
  A	Rosa	Aggiornamento	40
  B	Viola	Aggiornamento	50
  Una	Quindi,	Aggiornamento	50
  B	NeonBlue	Aggiornamento	70

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

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

  Timestamp chiamata API	Document ID	Foo proprietà	Timestamp del documento (_ts)
  15	A	Red	10
  35	B	Blu	20
  35	Una	Orange	30
  55	B	Viola	50
  55	Una	Quindi,	60
  75	B	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 perché 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, il documento A è cambiato due volte, come indicato di seguito:

  Document ID	Foo proprietà	Evento	Timestamp del documento (_ts)
  Una	Rosa	Aggiornamento	40
  Una	Quindi,	Aggiornamento	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 di connessione dati è inattivo per alcuni minuti o se la frequenza delle modifiche al 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: è 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:

Costi	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 ciò può variare a seconda dello scenario. Ad esempio, se si scrivono 100 documenti in un contenitore Cosmos DB, il costo della scrittura di tali documenti è 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.

Contenuti correlati

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