Azure Cosmos DB'den Azure Veri Gezgini'a veri alma

Azure Veri Gezgini, değişiklik akışı kullanarak NoSql için Azure Cosmos DB'denveri alımını destekler. Cosmos DB değişiklik akışı veri bağlantısı, Cosmos DB değişiklik akışınızı dinleyen ve verileri Veri Gezgini tablonuza alan bir alma işlem hattıdır. Değişiklik akışı yeni ve güncelleştirilmiş belgeleri dinler ancak silmeleri günlüğe kaydetmez. Azure Veri Gezgini'da veri alımı hakkında genel bilgi için bkz. Azure Veri Gezgini veri alımına genel bakış.

Her veri bağlantısı belirli bir Cosmos DB kapsayıcısını dinler ve verileri belirli bir tabloya alır (tek bir tabloda birden fazla bağlantı alabilir). Alma yöntemi, akış alımını (etkinleştirildiğinde) ve kuyruğa alınmış alımı destekler.

Bu makalede, Sistem Tarafından Yönetilen Kimlik ile Verileri Azure Veri Gezgini almak için Cosmos DB değişiklik akışı veri bağlantısı ayarlamayı öğreneceksiniz. Başlamadan önce dikkat edilmesi gereken noktaları gözden geçirin.

Bağlayıcıyı ayarlamak için aşağıdaki adımları kullanın:

1. Adım: Bir Azure Veri Gezgini tablosu seçin ve tablo eşlemesini yapılandırın

2. Adım: Cosmos DB veri bağlantısı oluşturma

3. Adım: Veri bağlantısını test edin

Önkoşullar

• Azure aboneliği. Ücretsiz bir Azure hesabı oluşturun.
• Azure Veri Gezgini kümesi ve veritabanı. Küme ve veritabanı oluşturma.
• NoSQL için Cosmos DB hesabından bir kapsayıcı.
• Cosmos DB hesabınız örneğin özel uç nokta kullanarak ağ erişimini engelliyorsa, Cosmos DB hesabına yönetilen bir özel uç nokta oluşturmanız gerekir. Kümenizin değişiklik akışı API'sini çağırması için bu gereklidir.

1. Adım: Bir Azure Veri Gezgini tablosu seçin ve tablo eşlemesini yapılandırın

Veri bağlantısı oluşturmadan önce, alınan verileri depoladığınız bir tablo oluşturun ve kaynak Cosmos DB kapsayıcısında şemayla eşleşen bir eşleme uygulayın. Senaryonuz basit bir alan eşlemesinden fazlasını gerektiriyorsa, değişiklik akışınızdan alınan verileri dönüştürmek ve eşlemek için güncelleştirme ilkelerini kullanabilirsiniz.

Aşağıda Cosmos DB kapsayıcısında bir öğenin örnek şeması gösterilmektedir:

{
    "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
}

Tablo oluşturmak ve tablo eşlemesi uygulamak için aşağıdaki adımları kullanın:

1. Azure Veri Gezgini web kullanıcı arabiriminde, sol gezinti menüsünde Sorgu'yu seçin ve ardından tabloyu oluşturmak istediğiniz veritabanını seçin.

2. TestTable adlı bir tablo oluşturmak için aşağıdaki komutu çalıştırın.

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

3. Tablo eşlemesini oluşturmak için aşağıdaki komutu çalıştırın.

   Komut, cosmos DB JSON belgesindeki özel özellikleri TestTable tablosundaki sütunlara aşağıdaki gibi eşler:

   Cosmos DB özelliği	Tablo sütunu	Dönüşüm
   id	Id	Hiçbiri
   Adı	Name	Hiçbiri
   _Ts	_ts	Hiçbiri
   _Ts	_Zaman damgası	dönüştürme_ts (UNIX saniye) _timestamp (datetime)) için kullanır DateTimeFromUnixSeconds

   Not

   Aşağıdaki zaman damgası sütunlarını kullanmanızı öneririz:

   • _ts: Verileri Cosmos DB ile mutabık hale getirmek için bu sütunu kullanın.
   • _timestamp: Kusto sorgularınızda verimli zaman filtreleri çalıştırmak için bu sütunu kullanın. Daha fazla bilgi için bkz. Sorgu en iyi yöntemi.

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

Güncelleştirme ilkeleriyle verileri dönüştürme ve eşleme

Senaryonuz basit bir alan eşlemesinden fazlasını gerektiriyorsa, değişiklik akışınızdan alınan verileri dönüştürmek ve eşlemek için güncelleştirme ilkelerini kullanabilirsiniz.

Güncelleştirme ilkeleri , tablonuza alınan verileri dönüştürmenin bir yoludur. Bunlar Kusto Sorgu Dili yazılır ve alım işlem hattında çalıştırılır. Cosmos DB değişiklik akışı alımından verileri dönüştürmek için kullanılabilirler, örneğin aşağıdaki senaryolarda:

• Belgeleriniz, işleci kullanılarak mv-expand birden çok satırda dönüştürülürse sorgulanması daha kolay olan diziler içerir.
• Belgeleri filtrelemek istiyorsunuz. Örneğin, işlecini kullanarak belgeleri türe where göre filtreleyebilirsiniz.
• Tablo eşlemesinde temsil edilmeyecek karmaşık mantığınız var.

Güncelleştirme ilkeleri oluşturma ve yönetme hakkında bilgi için bkz . Güncelleştirme ilkesine genel bakış.

2. Adım: Cosmos DB veri bağlantısı oluşturma

Veri bağlayıcısını oluşturmak için aşağıdaki yöntemleri kullanabilirsiniz:

Azure portalı

1. Azure portal kümenize genel bakış sayfasına gidin ve Başlarken sekmesini seçin.

2. Veri alımı kutucuğunda Veri bağlantısı> oluşturCosmos DB'yi seçin.

   

3. Cosmos DB Veri bağlantısı oluştur bölmesinde formu tablodaki bilgilerle doldurun:

   

   Alan	Açıklama
   Veritabanı adı	Verileri almak istediğiniz Azure Veri Gezgini veritabanını seçin.
   Veri bağlantısı adı	Veri bağlantısı için bir ad belirtin.
   Abonelik	Cosmos DB NoSQL hesabınızı içeren aboneliği seçin.
   Cosmos DB hesabı	Veri almak istediğiniz Cosmos DB hesabını seçin.
   SQL veritabanı	Veri almak istediğiniz Cosmos DB veritabanını seçin.
   SQL kapsayıcısı	Veri almak istediğiniz Cosmos DB kapsayıcısını seçin.
   Tablo adı	Verileri almak istediğiniz Azure Veri Gezgini tablo adını belirtin.
   Eşleme adı	İsteğe bağlı olarak, veri bağlantısı için kullanılacak eşleme adını belirtin.

4. İsteğe bağlı olarak, Gelişmiş ayarlar bölümünde aşağıdakileri yapın:

   1. Olay alma başlangıç tarihini belirtin. Bu, bağlayıcının verileri almaya başlayacağı zamandır. Saat belirtmezseniz bağlayıcı, veri bağlantısını oluşturduğunuz zamandan itibaren verileri almaya başlar. Önerilen tarih biçimi ISO 8601 UTC standardıdır ve şu şekilde belirtilir: yyyy-MM-ddTHH:mm:ss.fffffffZ.

   2. Kullanıcı tarafından atanan'ı ve ardından kimliği seçin. Varsayılan olarak, bağlantı tarafından Sistem tarafından atanan yönetilen kimlik kullanılır. Gerekirse, Kullanıcı tarafından atanan bir kimlik kullanabilirsiniz.

      

5. Veri bağlantısını oluşturmak için Oluştur'u seçin.

ARM şablonu

Kendi veri bağlantısı şablonunuzu oluşturmak için temel olarak aşağıdaki örnek ARM şablonunu kullanın ve Azure portal dağıtın.

Cosmos DB bağlantınızı yapılandırmak için:

1. Cosmos DB bağlantı kimlik doğrulamanız için Sistem Tarafından Yönetilen Kimlik yapılandırma.

   1. Azure Veri Gezgini web kullanıcı arabiriminde, sol gezinti menüsünde Sorgu'yu seçin ve ardından veri bağlantısı için kümeyi veya veritabanını seçin.

2. Cosmos DB hesabınıza erişmek için veri bağlantısı izni verin. Cosmos DB'nize veri bağlantısı erişimi sağlamak, veritabanınızdan verilere erişmesini ve bunları almasını sağlar. Kümenizin Azure portal bulabileceğiniz asıl kimliğine ihtiyacınız olacaktır. Daha fazla bilgi için bkz . Kümeniz için yönetilen kimlikleri yapılandırma.

   Not

   • Aşağıdaki adımlar bu rolleri asıl kimliğine atar:
     • Cosmos DB Yerleşik Veri Okuyucusu
       • Azure portal Rol Atama özelliğini kullanarak Cosmos DB Yerleşik Veri Okuyucusu rolünü atayamazsınız.
     • Cosmos DB Hesap OkuyucuSu Rolü

   Cosmos DB hesabınıza erişim vermek için aşağıdaki seçeneklerden birini kullanın:

   • Azure CLI kullanarak erişim izni verme: Yer tutucuları uygun değerlerle değiştirmek için aşağıdaki tabloda yer alan bilgileri kullanarak CLI komutunu çalıştırın:

     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>
     

     Yer tutucu	Description
     <CosmosDBAccountName>	Cosmos DB hesabınızın adı.
     <CosmosDBResourceGroup>	Cosmos DB hesabınızı içeren kaynak grubunun adı.
     <CosmosDBAccountResourceId>	Cosmos DB hesabınızın Azure kaynak kimliği (ile subscriptions/başlayarak).
     <ClusterPrincipalId>	Kümenize atanan yönetilen kimliğin asıl kimliği. Kümenizin ilke kimliğini Azure portal bulabilirsiniz. Daha fazla bilgi için bkz . Kümeniz için yönetilen kimlikleri yapılandırma.

   • ARM Şablonu kullanarak erişim izni verme: Cosmos DB hesabı kaynak grubunda aşağıdaki şablonu dağıtın:

     {
         "$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. Cosmos DB veri bağlantısı oluşturmak için aşağıdaki ARM şablonunu dağıtın. Yer tutucuları uygun değerlerle değiştirin.

   {
     "$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')]"
       }
     }]
   }
   

3. Adım: Veri bağlantısını test etme

1. Cosmos DB kapsayıcısında aşağıdaki belgeyi ekleyin:

   {
       "name":"Cousteau"
   }
   

2. Azure Veri Gezgini web kullanıcı arabiriminde aşağıdaki sorguyu çalıştırın:

   TestTable
   

   Sonuç kümesi aşağıdaki görüntüye benzemelidir:

   

Not

Azure Veri Gezgini, alım işlemini iyileştirmek için tasarlanmış kuyruğa alınmış veri alımı için bir toplama (toplu işlem) ilkesine sahiptir. Varsayılan toplu işlem ilkesi, toplu iş için aşağıdaki koşullardan biri geçerli olduğunda toplu işlemi mühürlemesi için yapılandırılır: en fazla 5 dakika gecikme süresi, toplam boyut bir GB veya 1000 blob. Bu nedenle, bir gecikmeyle karşılaşabilirsiniz. Daha fazla bilgi için bkz. toplu işlem ilkesi. Gecikme süresini azaltmak için tablonuzu akışı destekleyecek şekilde yapılandırın. Bkz . akış ilkesi.

Dikkat edilmesi gerekenler

Cosmos DB değişiklik akışı için aşağıdaki noktalar geçerlidir:

• Değişiklik akışı silme olaylarını kullanıma sunmaz.

  Cosmos DB değişiklik akışı yalnızca yeni ve güncelleştirilmiş belgeleri içerir. Silinen belgeler hakkında bilgi sahibi olmanız gerekiyorsa, bir Cosmos DB belgesini silinmiş olarak işaretlemek için akışınızı geçici işaret kullanarak yapılandırabilirsiniz. Bir belgenin silinip silinmediğini belirten güncelleştirme olaylarına bir özellik eklenir. Ardından sorgularınızda işlecini where kullanarak bunları filtreleyebilirsiniz.

  Örneğin, silinen özelliği IsDeleted adlı bir tablo sütunuyla eşlerseniz, silinen belgeleri aşağıdaki sorguyla filtreleyebilirsiniz:

  TestTable
  | where not(IsDeleted)
  

• Değişiklik akışı yalnızca belgenin en son güncelleştirmesini kullanıma sunar.

  İkinci değerlendirmenin ne kadar önemli olduğunu anlamak için aşağıdaki senaryoyu inceleyin:

  Cosmos DB kapsayıcısı A ve B belgelerini içerir. foo adlı bir özellikte yapılan değişiklikler aşağıdaki tabloda gösterilmiştir:

  Belge Kimliği	Özellik foo	Olay	Belge zaman damgası (_ts)
  A	Red	Oluşturma	10
  B	Mavi	Oluşturma	20
  A	Orange	Güncelleştir	30
  A	Pembe	Güncelleştirme	40
  B	Menekşe	Güncelleştir	50
  A	Carmine	Güncelleştir	50
  B	NeonBlue	Güncelleştir	70

  Değişiklik akışı API'sini veri bağlayıcısı düzenli aralıklarla (genellikle birkaç saniyede bir) yoklar. Her yoklama, kapsayıcıda çağrılar arasında gerçekleşen değişiklikleri içerir , ancak belge başına yalnızca en son değişiklik sürümünü içerir.

  Sorunu göstermek için, aşağıdaki tabloda gösterildiği gibi 15, 35, 55 ve 75 zaman damgalarına sahip bir DIZI API çağrısını göz önünde bulundurun:

  API Çağrı Zaman Damgası	Belge Kimliği	Özellik foo	Belge zaman damgası (_ts)
  15	A	Red	10
  35	B	Mavi	20
  35	A	Orange	30
  55	B	Menekşe	50
  55	A	Carmine	60
  75	B	NeonBlue	70

  API sonuçlarını Cosmos DB belgesinde yapılan değişikliklerin listesiyle karşılaştırdığınızda bunların eşleşmediğini fark edeceksiniz. Değişiklik tablosunda zaman damgası 40'ta vurgulanan A belgesine güncelleştirme olayı, API çağrısının sonuçlarında görünmez.

  Olayın neden görünmediği anlamak için 35 ve 55 zaman damgalarında API çağrıları arasında A belgesinde yapılan değişiklikleri inceleyeceğiz. Bu iki çağrı arasında , A belgesi aşağıdaki gibi iki kez değiştirildi:

  Belge Kimliği	Özellik foo	Olay	Belge zaman damgası (_ts)
  A	Pembe	Güncelleştir	40
  A	Carmine	Güncelleştir	50

  55 numaralı zaman damgasında API çağrısı yapıldığında, değişiklik akışı API'si belgenin en son sürümünü döndürür. Bu durumda, A belgesinin en son sürümü, Pink'denCarmine'ekadar olan özellik foo güncelleştirmesi olan zaman damgası 50'deki güncelleştirmedir.

  Bu senaryo nedeniyle veri bağlayıcısı bazı ara belge değişikliklerini kaçırabilir. Örneğin, veri bağlantısı hizmeti birkaç dakika kapalı kalırsa veya belge değişiklikleri sıklığı API yoklama sıklığından daha yüksekse bazı olaylar kaçırılabilir. Ancak, her belgenin en son durumu yakalanır.

• Cosmos DB kapsayıcısı silme ve yeniden oluşturma desteklenmez

  Azure Veri Gezgini, akışta bulunduğu "konumu" denetleyerek değişiklik akışını izler. Bu işlem kapsayıcının her fiziksel bölümünde devamlılık belirteci kullanılarak gerçekleştirilir. Kapsayıcı silindiğinde/yeniden oluşturulduğunda, bu devamlılık belirteci geçersizdir ve sıfırlanmaz: veri bağlantısını silmeniz ve yeniden oluşturmanız gerekir.

Tahmini maliyet

Cosmos DB veri bağlantısını kullanmak Cosmos DB kapsayıcınızın İstek Birimleri (RU) kullanımını ne kadar etkiler?

Bağlayıcı, kapsayıcınızın her fiziksel bölümünde Cosmos DB Değişiklik Akışı API'sini saniyede bire kadar çağırır. Aşağıdaki maliyetler bu çağrılarla ilişkilendirilir:

Maliyet	Description
Sabit maliyetler	Sabit maliyetler her saniye fiziksel bölüm başına yaklaşık 2 RU'dur.
Değişken maliyetler	Değişken maliyetler belge yazmak için kullanılan RU'ların yaklaşık %2'sine eşittir, ancak bu durum senaryonuza bağlı olarak farklılık gösterebilir. Örneğin, Cosmos DB kapsayıcısına 100 belge yazarsanız, bu belgeleri yazmanın maliyeti 1.000 RU'dur. Bağlayıcıyı bu belgeyi okumak için kullanmanın karşılık gelen maliyeti, bunları yazma maliyetinin yaklaşık %2'si, yaklaşık 20 RU'dur.

İlgili içerik

• Azure Cosmos DB belgelerinin en son sürümlerini alma
• Kusto Sorgu Dili'ne (KQL) genel bakış