Memindahkan data ke dan dari Azure Cosmos DB menggunakan Azure Data Factory

  • Artikel
  • 10 menit untuk membaca

Catatan

Artikel ini berlaku untuk versi 1 dari Azure Data Factory. Jika Anda menggunakan versi layanan Azure Data Factory saat ini, lihat Konektor Azure Cosmos DB di V2.

Artikel ini menjelaskan cara menggunakan Aktivitas Salin di Azure Data Factory untuk memindahkan data ke/dari Microsoft Azure Cosmos DB (SQL API). Ini dibuat pada artikel Aktivitas Pergerakan Data, yang menyajikan ikhtisar umum pergerakan data dengan aktivitas salin.

Anda dapat menyalin data dari penyimpanan data sumber yang didukung ke Azure Cosmos DB atau dari Azure Cosmos DB ke penyimpanan data sink yang didukung. Untuk daftar penyimpanan data yang didukung sebagai sumber atau sink oleh aktivitas salin, lihat tabel Penyimpanan data yang didukung.

Penting

Konektor Microsoft Azure Cosmos DB hanya mendukung SQL API.

Untuk menyalin data apa adanya ke/dari file JSON atau koleksi Cosmos DB lainnya, lihat Impor/Ekspor dokumen JSON.

Memulai

Anda dapat membuat alur dengan aktivitas salin yang memindahkan data ke/dari Microsoft Azure Cosmos DB dengan menggunakan alat/API yang berbeda.

Cara termudah untuk membuat alur adalah menggunakan Wizard Salin. Lihat Tutorial: Membuat alur menggunakan Wizard Salin untuk panduan singkat tentang membuat alur menggunakan Wizard Salin data.

Anda juga dapat menggunakan alat berikut untuk membuat pipeline: Visual Studio, Azure PowerShell, template Azure Resource Manager, .NET API, dan REST API. Lihat Tutorial aktivitas penyalinan untuk instruksi langkah demi langkah guna membuat alur dengan aktivitas penyalinan.

Baik Anda menggunakan alat atau API, Anda melakukan langkah-langkah berikut untuk membuat alur yang memindahkan data dari penyimpanan data sumber ke penyimpanan data sink:

  1. Buat layanan tertaut untuk menautkan penyimpanan data input dan output ke pabrik data Anda.
  2. Buat kumpulan data untuk mewakili data input dan output untuk operasi salin.
  3. Buat jalur dengan aktivitas salinan yang mengambil set data sebagai input dan set data sebagai output.

Saat Anda menggunakan wizard, definisi JSON untuk entitas Data Factory ini (layanan tertaut, himpunan data, dan alur) secara otomatis dibuat untuk Anda. Saat Anda menggunakan alat/API (kecuali .NET API), Anda menentukan entitas Data Factory ini dengan menggunakan format JSON. Untuk sampel dengan definisi JSON untuk entitas Data Factory yang digunakan untuk menyalin data ke/dari Microsoft Azure Cosmos DB, lihat bagian contoh JSON dari artikel ini.

Bagian berikut memberikan detail tentang properti JSON yang digunakan untuk menentukan entitas Azure Data Factory khusus untuk Microsoft Azure Cosmos DB:

Properti layanan tertaut

Tabel berikut memberikan deskripsi untuk elemen JSON khusus untuk layanan tertaut Microsoft Azure Cosmos DB.

Properti Deskripsi Diperlukan
jenis Properti jenis harus diatur ke: DocumentDb Ya
connectionString Tentukan informasi yang diperlukan untuk menyambungkan ke database Azure Cosmos DB. Ya

Contoh:

{
  "name": "CosmosDbLinkedService",
  "properties": {
    "type": "DocumentDb",
    "typeProperties": {
      "connectionString": "AccountEndpoint=<EndpointUrl>;AccountKey=<AccessKey>;Database=<Database>"
    }
  }
}

Properti himpunan data

Untuk daftar lengkap bagian & properti yang tersedia untuk menentukan himpunan data, lihat artikel Membuat himpunan data. Bagian-bagian seperti struktur, ketersediaan, dan kebijakan himpunan data JSON mirip untuk semua jenis himpunan data (Azure SQL, blob Azure, tabel Azure, dll.).

Bagian typeProperties berbeda untuk setiap jenis himpunan data dan menyediakan informasi tentang lokasi data di penyimpanan data. Bagian typeProperties untuk himpunan data jenis DocumentDbCollection memiliki properti berikut.

Properti Deskripsi Diperlukan
collectionName Nama koleksi dokumen Cosmos DB. Ya

Contoh:

{
  "name": "PersonCosmosDbTable",
  "properties": {
    "type": "DocumentDbCollection",
    "linkedServiceName": "CosmosDbLinkedService",
    "typeProperties": {
      "collectionName": "Person"
    },
    "external": true,
    "availability": {
      "frequency": "Day",
      "interval": 1
    }
  }
}

Skema oleh Data Factory

Untuk penyimpanan data bebas skema seperti Azure Cosmos DB, layanan Data Factory menyimpulkan skema dengan salah satu cara berikut:

  1. Jika Anda menentukan struktur data dengan menggunakan properti struktur dalam definisi himpunan data, layanan Azure Data Factory menghormati struktur ini sebagai skema. Dalam hal ini, jika baris tidak berisi nilai untuk kolom, nilai kosong akan disediakan untuk itu.
  2. Jika Anda tidak menentukan struktur data dengan menggunakan properti struktur dalam definisi himpunan data, layanan Azure Data Factory menghormati struktur ini sebagai skema. Dalam hal ini, jika baris pertama tidak berisi skema lengkap, beberapa kolom akan hilang dalam hasil operasi salin.

Oleh karena itu, untuk sumber data bebas skema, praktik terbaik adalah menentukan struktur data menggunakan properti struktur.

Properti aktivitas salin

Untuk daftar lengkap bagian & properti yang tersedia untuk menentukan aktivitas, lihat artikel Membuat Alur. Properti seperti nama, deskripsi, tabel input dan output, dan kebijakan tersedia untuk semua jenis aktivitas.

Catatan

Aktivitas Salin hanya membutuhkan satu input dan hanya menghasilkan satu output.

Properti yang tersedia di bagian typeProperties aktivitas di sisi lain bervariasi menurut setiap jenis aktivitas dan jika aktivitas Salin bervariasi tergantung pada jenis sumber dan sink.

Dalam kasus Aktivitas Salin ketika sumber berjenis DocumentDbCollectionSource properti berikut ini tersedia di bagian typeProperties:

Properti Deskripsi Nilai yang diizinkan Diperlukan
kueri Tentukan kueri untuk membaca data. String kueri yang didukung oleh Azure Cosmos DB.

Contoh: SELECT c.BusinessEntityID, c.PersonType, c.NameStyle, c.Title, c.Name.First AS FirstName, c.Name.Last AS LastName, c.Suffix, c.EmailPromotion FROM c WHERE c.ModifiedDate > \"2009-01-01T00:00:00\"		 Tidak

Jika tidak ditentukan, pernyataan SQL yang dijalankan: select <columns defined in structure> from mycollection
nestingSeparator Karakter khusus untuk menunjukkan bahwa dokumen ditumpuk Karakter apapun.

Azure Cosmos DB adalah penyimpanan NoSQL untuk dokumen JSON, di mana struktur bersarang diizinkan. Azure Data Factory memungkinkan pengguna untuk menunjukkan hierarki melalui nestingSeparator, yaitu "." dalam contoh di atas. Dengan pemisah, aktivitas salin akan menghasilkan objek "Nama" dengan tiga elemen anak Pertama, Tengah dan Terakhir, menurut "Name.First", "Name.Middle" dan "Name.Last" dalam definisi tabel.		 Tidak

DocumentDbCollectionSink mendukung properti berikut:

Properti Deskripsi Nilai yang diizinkan Diperlukan
nestingSeparator Karakter khusus dalam nama kolom sumber untuk menunjukkan bahwa dokumen bertumpuk diperlukan.

Misalnya di atas: Name.First dalam tabel output menghasilkan struktur JSON berikut dalam dokumen Cosmos DB:

"Nama": {
"Pertama": "John"
},		 Karakter yang digunakan untuk memisahkan tingkat bersarang.

Nilai defaultnya adalah . (titik).		 Karakter yang digunakan untuk memisahkan tingkat bersarang.

Nilai defaultnya adalah . (titik).
writeBatchSize Jumlah permintaan paralel ke layanan Azure Cosmos DB untuk membuat dokumen.

Anda dapat menyempurnakan kinerja saat menyalin data ke/dari Cosmos DB dengan menggunakan properti ini. Anda dapat mengharapkan kinerja yang lebih baik ketika Anda meningkatkan writeBatchSize karena permintaan yang lebih paralel ke Cosmos DB dikirim. Namun Anda harus menghindari throttling yang dapat melemparkan pesan kesalahan: "Tingkat permintaan besar".

Throttling diputuskan oleh sejumlah faktor, termasuk ukuran dokumen, jumlah istilah dalam dokumen, kebijakan pengindeksan pengumpulan target, dll. Untuk operasi salin, Anda dapat menggunakan koleksi yang lebih baik (misalnya S3) untuk memiliki throughput terbanyak yang tersedia (2.500 unit permintaan/detik).		 Bilangan bulat Tidak (default: 5)
writeBatchTimeout Tunggu waktu hingga operasi penyisipan batch selesai sebelum waktu habis. timespan

Contoh: "00:30:00" (30 menit).		 Tidak

Impor/Ekspor dokumen JSON

Menggunakan konektor Cosmos DB ini, Anda dapat dengan mudah

  • Impor dokumen JSON dari berbagai sumber ke Cosmos DB, termasuk Azure Blob, Azure Data Lake, Sistem File lokal, atau penyimpanan berbasis file lainnya yang didukung oleh Azure Data Factory.
  • Ekspor dokumen JSON dari koleksi Cosmos DB ke berbagai penyimpanan berbasis file.
  • Migrasi data antara dua koleksi Cosmos DB apa adanya.

Untuk mencapai salinan skema-agnostik seperti itu,

  • Saat menggunakan wizard salin, centang opsi "Ekspor apa adanya ke file JSON atau koleksi Cosmos DB" .
  • Saat menggunakan pengeditan JSON, jangan tentukan bagian "struktur" di properti himpunan data Cosmos DB atau "nestingSeparator" pada sumber/sink Cosmos DB dalam aktivitas salin. Untuk mengimpor dari/mengekspor ke file JSON, di himpunan data penyimpanan file tentukan jenis format sebagai "JsonFormat", konfigurasi "filePattern" dan lewati pengaturan format lainnya, lihat bagian format JSON pada detail.

Contoh JSON

Contoh berikut ini menyediakan sampel JSON yang bisa Anda gunakan untuk membuat alur dengan menggunakan Visual Studio atau Azure PowerShell. Mereka menunjukkan cara menyalin data ke dan dari Microsoft Azure Cosmos DB dan Azure Blob Storage. Namun, data dapat disalin langsung dari salah satu sumber ke salah satu alur yang dinyatakan di sini menggunakan Aktivitas Salin di Azure Data Factory.

Contoh: Menyalin data dari Azure Cosmos DB ke Azure Blob

Contoh di bawah ini menunjukkan:

  1. Layanan tertaut jenis DocumentDb.
  2. Layanan tertaut jenis AzureStorage.
  3. Sebuah input himpunan data jenis DocumentDbCollection.
  4. Sebuah output himpunan data jenis AzureBlob.
  5. Sebuah alur dengan Aktivitas Salin yang menggunakan DocumentDbCollectionSource dan BlobSink.

Sampel menyalin data di Azure Cosmos DB ke Azure Blob. Properti JSON yang digunakan dalam sampel ini dijelaskan dalam beberapa bagian setelah sampel.

Layanan tertaut Azure Cosmos DB:

{
  "name": "CosmosDbLinkedService",
  "properties": {
    "type": "DocumentDb",
    "typeProperties": {
      "connectionString": "AccountEndpoint=<EndpointUrl>;AccountKey=<AccessKey>;Database=<Database>"
    }
  }
}

Layanan tertaut di Azure Blob Storage:

{
  "name": "StorageLinkedService",
  "properties": {
    "type": "AzureStorage",
    "typeProperties": {
      "connectionString": "DefaultEndpointsProtocol=https;AccountName=<accountname>;AccountKey=<accountkey>"
    }
  }
}

himpunan data input DB Dokumen Azure:

Sampel mengasumsikan Anda memiliki koleksi bernama Person pada Azure Cosmos DB database.

Pengaturan "eksternal": "true" dan menentukan informasi kebijakan externalData layanan Azure Data Factory bahwa tabel berada di luar Data Factory dan tidak dihasilkan oleh aktivitas di Data Factory.

{
  "name": "PersonCosmosDbTable",
  "properties": {
    "type": "DocumentDbCollection",
    "linkedServiceName": "CosmosDbLinkedService",
    "typeProperties": {
      "collectionName": "Person"
    },
    "external": true,
    "availability": {
      "frequency": "Day",
      "interval": 1
    }
  }
}

himpunan data output Azure Blob:

Data disalin ke blob baru setiap jam dengan alur untuk blob yang mencerminkan tanggal tertentu dengan granularitas jam.

{
  "name": "PersonBlobTableOut",
  "properties": {
    "type": "AzureBlob",
    "linkedServiceName": "StorageLinkedService",
    "typeProperties": {
      "folderPath": "docdb",
      "format": {
        "type": "TextFormat",
        "columnDelimiter": ",",
        "nullValue": "NULL"
      }
    },
    "availability": {
      "frequency": "Day",
      "interval": 1
    }
  }
}

Contoh dokumen JSON dalam koleksi Person dalam database Cosmos DB:

{
  "PersonId": 2,
  "Name": {
    "First": "Jane",
    "Middle": "",
    "Last": "Doe"
  }
}

Cosmos DB mendukung kueri dokumen menggunakan SQL seperti sintaks atas dokumen JSON hierarkis.

Contoh:

SELECT Person.PersonId, Person.Name.First AS FirstName, Person.Name.Middle as MiddleName, Person.Name.Last AS LastName FROM Person

Saluran pipa berikut menyalin data dari kumpulan Orang di database Azure Cosmos DB ke blob Azure. Sebagai bagian dari aktivitas salin, himpunan data input dan output telah ditentukan.

{
  "name": "DocDbToBlobPipeline",
  "properties": {
    "activities": [
      {
        "type": "Copy",
        "typeProperties": {
          "source": {
            "type": "DocumentDbCollectionSource",
            "query": "SELECT Person.Id, Person.Name.First AS FirstName, Person.Name.Middle as MiddleName, Person.Name.Last AS LastName FROM Person",
            "nestingSeparator": "."
          },
          "sink": {
            "type": "BlobSink",
            "blobWriterAddHeader": true,
            "writeBatchSize": 1000,
            "writeBatchTimeout": "00:00:59"
          }
        },
        "inputs": [
          {
            "name": "PersonCosmosDbTable"
          }
        ],
        "outputs": [
          {
            "name": "PersonBlobTableOut"
          }
        ],
        "policy": {
          "concurrency": 1
        },
        "name": "CopyFromDocDbToBlob"
      }
    ],
    "start": "2015-04-01T00:00:00Z",
    "end": "2015-04-02T00:00:00Z"
  }
}

Contoh: Menyalin data dari Azure Blob ke Azure Cosmos DB

Contoh di bawah ini menunjukkan:

  1. Layanan tertaut jenis DocumentDb.
  2. Layanan tertaut jenis AzureStorage.
  3. Sebuah input himpunan data jenis AzureBlob.
  4. himpunan data output jenis DocumentDbCollection.
  5. alur dengan Copy Activity yang menggunakan BlobSource dan DocumentDbCollectionSink.

Sampel menyalin data di Azure Blob ke Azure Cosmos DB. Properti JSON yang digunakan dalam sampel ini dijelaskan dalam beberapa bagian setelah sampel.

Layanan tertaut di Azure Blob Storage:

{
  "name": "StorageLinkedService",
  "properties": {
    "type": "AzureStorage",
    "typeProperties": {
      "connectionString": "DefaultEndpointsProtocol=https;AccountName=<accountname>;AccountKey=<accountkey>"
    }
  }
}

Layanan tertaut Azure Cosmos DB:

{
  "name": "CosmosDbLinkedService",
  "properties": {
    "type": "DocumentDb",
    "typeProperties": {
      "connectionString": "AccountEndpoint=<EndpointUrl>;AccountKey=<AccessKey>;Database=<Database>"
    }
  }
}

himpunan data input Azure Blob:

{
  "name": "PersonBlobTableIn",
  "properties": {
    "structure": [
      {
        "name": "Id",
        "type": "Int"
      },
      {
        "name": "FirstName",
        "type": "String"
      },
      {
        "name": "MiddleName",
        "type": "String"
      },
      {
        "name": "LastName",
        "type": "String"
      }
    ],
    "type": "AzureBlob",
    "linkedServiceName": "StorageLinkedService",
    "typeProperties": {
      "fileName": "input.csv",
      "folderPath": "docdb",
      "format": {
        "type": "TextFormat",
        "columnDelimiter": ",",
        "nullValue": "NULL"
      }
    },
    "external": true,
    "availability": {
      "frequency": "Day",
      "interval": 1
    }
  }
}

himpunan data output Azure Cosmos DB:

Sampel menyalin data ke koleksi bernama "Orang".

{
  "name": "PersonCosmosDbTableOut",
  "properties": {
    "structure": [
      {
        "name": "Id",
        "type": "Int"
      },
      {
        "name": "Name.First",
        "type": "String"
      },
      {
        "name": "Name.Middle",
        "type": "String"
      },
      {
        "name": "Name.Last",
        "type": "String"
      }
    ],
    "type": "DocumentDbCollection",
    "linkedServiceName": "CosmosDbLinkedService",
    "typeProperties": {
      "collectionName": "Person"
    },
    "availability": {
      "frequency": "Day",
      "interval": 1
    }
  }
}

alur berikut menyalin data dari Azure Blob ke pengumpulan Person di Cosmos DB. Sebagai bagian dari aktivitas salin, himpunan data input dan output telah ditentukan.

{
  "name": "BlobToDocDbPipeline",
  "properties": {
    "activities": [
      {
        "type": "Copy",
        "typeProperties": {
          "source": {
            "type": "BlobSource"
          },
          "sink": {
            "type": "DocumentDbCollectionSink",
            "nestingSeparator": ".",
            "writeBatchSize": 2,
            "writeBatchTimeout": "00:00:00"
          },
          "translator": {
              "type": "TabularTranslator",
              "ColumnMappings": "FirstName: Name.First, MiddleName: Name.Middle, LastName: Name.Last, BusinessEntityID: BusinessEntityID, PersonType: PersonType, NameStyle: NameStyle, Title: Title, Suffix: Suffix, EmailPromotion: EmailPromotion, rowguid: rowguid, ModifiedDate: ModifiedDate"
          }
        },
        "inputs": [
          {
            "name": "PersonBlobTableIn"
          }
        ],
        "outputs": [
          {
            "name": "PersonCosmosDbTableOut"
          }
        ],
        "policy": {
          "concurrency": 1
        },
        "name": "CopyFromBlobToDocDb"
      }
    ],
    "start": "2015-04-14T00:00:00Z",
    "end": "2015-04-15T00:00:00Z"
  }
}

Jika contoh input blob adalah sebagai

1,John,,Doe

Kemudian output JSON di Cosmos DB akan sebagai:

{
  "Id": 1,
  "Name": {
    "First": "John",
    "Middle": null,
    "Last": "Doe"
  },
  "id": "a5e8595c-62ec-4554-a118-3940f4ff70b6"
}

Azure Cosmos DB adalah penyimpanan NoSQL untuk dokumen JSON, di mana struktur bersarang diizinkan. Azure Data Factory memungkinkan pengguna untuk menunjukkan hierarki melalui nestingSeparator, yang merupakan "." dalam contoh ini. Dengan pemisah, aktivitas salin akan menghasilkan objek "Nama" dengan tiga elemen anak Pertama, Tengah dan Terakhir, menurut "Name.First", "Name.Middle" dan "Name.Last" dalam definisi tabel.

Lampiran

  1. Pertanyaan: Apakah Aktivitas Salin mendukung pembaruan rekaman yang sudah ada?

    Jawaban: Tidak.

  2. Pertanyaan: Bagaimana percobaan kembali salinan ke Azure Cosmos DB menghadapi catatan yang sudah disalin?

    Jawaban: Jika rekaman memiliki bidang "ID" dan operasi salin mencoba menyisipkan rekaman dengan ID yang sama, operasi salin melempar kesalahan.

  3. Pertanyaan: Apakah Azure Data Factory mendukung jangkauan atau partisi data berbasis hash?

    Jawaban: Tidak.

  4. Pertanyaan: Bisakah saya menentukan lebih dari satu koleksi Azure Cosmos DB untuk tabel?

    Jawaban: Tidak. Hanya satu koleksi yang dapat ditentukan saat ini.

Kinerja dan Penyetelan

Lihat Performa Aktivitas Penyalinan & Panduan Pengaturan untuk mempelajari tentang faktor utama yang memengaruhi performa perpindahan data (Aktivitas Penyalinan) di Azure Data Factory dan berbagai cara untuk mengoptimalkannya.