Mengindeks data dari Azure Cosmos DB menggunakan MongoDB API

Penting

Dukungan API MongoDB saat ini dalam pratinjau publik di Ketentuan Penggunaan tambahan. Saat ini, tidak ada dukungan SDK.

Dalam artikel ini, pelajari cara mengonfigurasi pengindeks yang mengimpor konten menggunakan MongoDB API dari Azure Cosmos DB.

Artikel ini melengkapi Buat pengindeks dengan informasi khusus untuk Cosmos DB MongoDB API. Ini menggunakan REST API untuk menunjukkan alur kerja tiga bagian yang umum untuk semua pengindeks: membuat sumber data, membuat indeks, membuat pengindeks. Ekstraksi data terjadi saat Anda mengirimkan permintaan Buat Pengindeks.

Karena terminologi dapat membingungkan, perlu dicatat bahwa pengindeksan Cosmos DB dan pengindeksan Cognitive Search adalah operasi yang berbeda. Pengindeksan di Cognitive Search membuat dan memuat indeks pencarian di layanan pencarian Anda.

Prasyarat

• Daftar untuk pratinjau untuk memberikan umpan balik dan mendapatkan bantuan dengan masalah apa pun yang Anda temui.

• Akun , database, koleksi, dan dokumen Azure Cosmos DB. Gunakan wilayah yang sama untuk Cognitive Search dan Cosmos DB untuk latensi yang lebih rendah dan untuk menghindari biaya bandwidth.

• Kebijakan pengindeksan otomatis pada koleksi Cosmos DB, diatur ke Konsisten. Ini adalah konfigurasi default. Pengindeksan malas tidak disarankan dan dapat mengakibatkan data hilang.

• Izin baca. String koneksi "akses penuh" menyertakan kunci yang memberikan akses ke konten, tetapi jika Anda menggunakan peran Azure, pastikan identitas terkelola layanan pencarian memiliki izin Peran Pembaca Akun Cosmos DB .

• Klien REST, seperti Postman atau Visual Studio Code dengan ekstensi untuk Azure Cognitive Search mengirim panggilan REST yang membuat sumber data, indeks, dan pengindeks.

Batasan

Ini adalah batasan fitur ini:

• Kueri kustom tidak didukung untuk menentukan himpunan data.

• Nama _ts kolom adalah kata khusus. Jika Anda memerlukan bidang ini, pertimbangkan solusi alternatif untuk mengisi indeks. Anda dapat menggunakan API pendorongan. Atau, Anda dapat menggunakan Azure Data Factory dengan indeks Azure Cognitive Search sebagai sink.

Menentukan sumber data

Definisi sumber data menentukan data untuk mengindeks, kredensial, dan kebijakan untuk mengidentifikasi perubahan dalam data. Sumber data didefinisikan sebagai sumber daya independen sehingga dapat digunakan oleh beberapa pengindeks.

Untuk panggilan ini, tentukan pratinjau versi REST API (2020-06-30-Preview atau 2021-04-30-Preview) untuk membuat sumber data yang terhubung menggunakan MongoDB API.

1. Buat atau perbarui sumber data untuk mengatur definisinya:

   POST https://[service name].search.windows.net/datasources?api-version=2021-04-30-Preview
   Content-Type: application/json
   api-key: [Search service admin key]
   {
     "name": "[my-cosmosdb-mongodb-ds]",
     "type": "cosmosdb",
     "credentials": {
       "connectionString": "AccountEndpoint=https://[cosmos-account-name].documents.azure.com;AccountKey=[cosmos-account-key];Database=[cosmos-database-name];ApiKind=MongoDb;"
     },
     "container": {
       "name": "[cosmos-db-collection]",
       "query": null
     },
     "dataChangeDetectionPolicy": {
       "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
       "highWaterMarkColumnName": "_ts"
     },
     "dataDeletionDetectionPolicy": null,
     "encryptionKey": null,
     "identity": null
   }
   

2. Atur "jenis" ke "cosmosdb" (diperlukan).

3. Atur "kredensial" ke string koneksi. Bagian berikutnya menjelaskan format yang didukung.

4. Atur "kontainer" ke koleksi. Properti "nama" diperlukan dan menentukan ID koleksi database yang akan diindeks. Untuk MONGODB API, "kueri" tidak didukung.

5. Atur "dataChangeDetectionPolicy" jika data volatil dan Anda ingin pengindeks hanya mengambil item baru dan yang diperbarui pada eksekusi berikutnya.

6. Atur "dataDeletionDetectionPolicy" jika Anda ingin menghapus dokumen pencarian dari indeks pencarian saat item sumber dihapus.

Kredensial dan string koneksi yang didukung

Pengindeks dapat tersambung ke koleksi menggunakan koneksi berikut. Untuk koneksi yang menargetkan MongoDB API, pastikan untuk menyertakan "ApiKind" dalam string koneksi.

Hindari nomor port di URL titik akhir. Jika Anda menyertakan nomor port, koneksi akan gagal.

String koneksi akses penuh
{ "connectionString" : "AccountEndpoint=https://<Cosmos DB account name>.documents.azure.com;AccountKey=<Cosmos DB auth key>;Database=<Cosmos DB database id>;ApiKind=MongoDb" }
Anda bisa mendapatkan kunci autentikasi Cosmos DB dari halaman akun Cosmos DB di portal Azure dengan memilih String Koneksi di panel navigasi kiri. Pastikan untuk menyalin Kata Sandi Utama dan mengganti nilai kunci autentikasi Cosmos DB dengannya.

String koneksi identitas terkelola
{ "connectionString" : "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.DocumentDB/databaseAccounts/<your cosmos db account name>/;(ApiKind=[api-kind];)" }
String koneksi ini tidak memerlukan kunci akun, tetapi Sebelumnya Anda harus mengonfigurasi layanan pencarian untuk terhubung menggunakan identitas terkelola dan membuat penetapan peran yang memberikan izin Peran Pembaca Akun Cosmos DB . Lihat Menyiapkan koneksi pengindeks ke database Cosmos DB menggunakan identitas terkelola untuk informasi selengkapnya.

Menambahkan bidang pencarian ke indeks

Dalam indeks pencarian, tambahkan bidang untuk menerima dokumen JSON sumber atau output proyeksi kueri kustom Anda. Pastikan bahwa skema indeks pencarian kompatibel dengan data sumber. Untuk konten di Cosmos DB, skema indeks pencarian Anda harus sesuai dengan item Azure Cosmos DB di sumber data Anda.

1. Membuat atau memperbarui indeks untuk menentukan bidang pencarian yang akan menyimpan data:

   POST https://[service name].search.windows.net/indexes?api-version=2020-06-30
   Content-Type: application/json
   api-key: [Search service admin key]
   
   {
       "name": "mysearchindex",
       "fields": [{
           "name": "doc_id",
           "type": "Edm.String",
           "key": true,
           "retrievable": true,
           "searchable": false
       }, {
           "name": "description",
           "type": "Edm.String",
           "filterable": false,
           "searchable": true,
           "sortable": false,
           "facetable": false,
           "suggestions": true
       }]
   }
   

2. Buat bidang kunci dokumen ("key": true). Untuk indeks pencarian berdasarkan koleksi MongoDB, kunci dokumen dapat berupa "doc_id", "rid", atau beberapa bidang string lain yang berisi nilai unik. Selama nama bidang dan jenis data sama di kedua sisi, tidak ada pemetaan bidang yang diperlukan.

   • "doc_id" mewakili "_id" untuk pengidentifikasi objek. Jika Anda menentukan bidang "doc_id" dalam indeks, pengindeks mengisinya dengan nilai pengidentifikasi objek.

   • "rid" adalah properti sistem di Cosmos DB. Jika Anda menentukan bidang "rid" dalam indeks, pengindeks mengisinya dengan nilai yang dikodekan base64 dari properti "rid".

   • Untuk bidang lain, bidang pencarian Anda harus memiliki nama yang sama seperti yang ditentukan dalam koleksi.

3. Buat bidang tambahan untuk konten yang lebih dapat dicari. Lihat Membuat indeks untuk detailnya.

Jenis data pemetaan

Jenis data JSON	Jenis bidang Cognitive Search
Bool	Edm.Boolean, Edm.String
Angka yang tampak seperti bilangan bulat	Edm.Int32, Edm.Int64, Edm.String
Angka yang tampak seperti titik apung	Edm.Double, Edm.String
String	Edm.String
Array jenis primitif seperti ["a", "b", "c"]	Kumpulan(Edm.String)
String yang tampak seperti tanggal	Edm.DateTimeOffset, Edm.String
Objek GeoJSON seperti { "type": "Point", "coordinates": [long, lat] }	Edm.GeographyPoint
Objek JSON yang lain	T/A

Mengonfigurasi dan menjalankan pengindeks Cosmos DB

Setelah indeks dan sumber data dibuat, Anda siap untuk membuat pengindeks. Konfigurasi pengindeks menentukan input, parameter, dan properti yang mengontrol perilaku run time.

1. Buat atau perbarui pengindeks dengan memberinya nama dan mereferensikan sumber data dan indeks target:

   POST https://[service name].search.windows.net/indexers?api-version=2020-06-30
   Content-Type: application/json
   api-key: [search service admin key]
   {
       "name" : "[my-cosmosdb-indexer]",
       "dataSourceName" : "[my-cosmosdb-mongodb-ds]",
       "targetIndexName" : "[my-search-index]",
       "disabled": null,
       "schedule": null,
       "parameters": {
           "batchSize": null,
           "maxFailedItems": 0,
           "maxFailedItemsPerBatch": 0,
           "base64EncodeKeys": false,
           "configuration": {}
           },
       "fieldMappings": [],
       "encryptionKey": null
   }
   

2. Tentukan pemetaan bidang jika ada perbedaan dalam nama atau jenis bidang, atau jika Anda memerlukan beberapa versi bidang sumber dalam indeks pencarian.

3. Lihat Membuat pengindeks untuk informasi selengkapnya tentang properti lain.

Pengindeks berjalan secara otomatis saat dibuat. Anda dapat mencegahnya dengan mengatur "dinonaktifkan" ke true. Untuk mengontrol eksekusi pengindeks, jalankan pengindeks sesuai permintaan atau letakkan sesuai jadwal.

Periksa status pengindeks

Untuk memantau status pengindeks dan riwayat eksekusi, kirim permintaan Dapatkan Status Pengindeks :

GET https://myservice.search.windows.net/indexers/myindexer/status?api-version=2020-06-30
  Content-Type: application/json  
  api-key: [admin key]

Respons mencakup status dan jumlah item yang diproses. Ini akan terlihat mirip dengan contoh berikut:

    {
        "status":"running",
        "lastResult": {
            "status":"success",
            "errorMessage":null,
            "startTime":"2022-02-21T00:23:24.957Z",
            "endTime":"2022-02-21T00:36:47.752Z",
            "errors":[],
            "itemsProcessed":1599501,
            "itemsFailed":0,
            "initialTrackingState":null,
            "finalTrackingState":null
        },
        "executionHistory":
        [
            {
                "status":"success",
                "errorMessage":null,
                "startTime":"2022-02-21T00:23:24.957Z",
                "endTime":"2022-02-21T00:36:47.752Z",
                "errors":[],
                "itemsProcessed":1599501,
                "itemsFailed":0,
                "initialTrackingState":null,
                "finalTrackingState":null
            },
            ... earlier history items
        ]
    }

Riwayat eksekusi berisi hingga 50 eksekusi yang terakhir selesai, yang diurutkan dalam urutan kronologis terbalik sehingga eksekusi terbaru lebih dulu.

Mengindeks dokumen baru dan yang diubah

Setelah pengindeks mengisi indeks pencarian sepenuhnya, Anda mungkin ingin pengindeks berikutnya berjalan untuk mengindeks secara bertahap hanya dokumen baru dan yang diubah dalam database Anda.

Untuk mengaktifkan pengindeksan inkremental, atur properti "dataChangeDetectionPolicy" dalam definisi sumber data Anda. Properti ini memberi tahu pengindeks mekanisme pelacakan perubahan mana yang digunakan pada data Anda.

Untuk pengindeks Cosmos DB, satu-satunya kebijakan yang HighWaterMarkChangeDetectionPolicy didukung adalah menggunakan _ts properti (tanda waktu) yang disediakan oleh Azure Cosmos DB.

Contoh berikut menunjukkan definisi sumber data dengan kebijakan deteksi perubahan:

"dataChangeDetectionPolicy": {
    "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
"  highWaterMarkColumnName": "_ts"
},

Mengindeks dokumen yang telah dihapus

Saat baris dihapus dari kumpulan, Anda biasanya juga ingin menghapus baris tersebut dari indeks pencarian. Tujuan kebijakan deteksi perubahan data adalah untuk mengidentifikasi item data yang diubah secara efisien. Saat ini, satu-satunya kebijakan yang didukung adalah Soft Delete kebijakan (penghapusan ditandai dengan bendera semacam), yang ditentukan dalam definisi sumber data sebagai berikut:

"dataDeletionDetectionPolicy"": {
    "@odata.type" : "#Microsoft.Azure.Search.SoftDeleteColumnDeletionDetectionPolicy",
    "softDeleteColumnName" : "the property that specifies whether a document was deleted",
    "softDeleteMarkerValue" : "the value that identifies a document as deleted"
}

Jika Anda menggunakan kueri kustom, pastikan properti yang direferensikan oleh softDeleteColumnName diproyeksikan oleh kueri.

Contoh berikut membuat sumber data dengan kebijakan penghapusan secara lunak:

POST https://[service name].search.windows.net/datasources?api-version=2020-06-30
Content-Type: application/json
api-key: [Search service admin key]

{
    "name": ["my-cosmosdb-mongodb-ds]",
    "type": "cosmosdb",
    "credentials": {
        "connectionString": "AccountEndpoint=https://[cosmos-account-name].documents.azure.com;AccountKey=[cosmos-account-key];Database=[cosmos-database-name];ApiKind=MongoDB"
    },
    "container": { "name": "[my-cosmos-collection]" },
    "dataChangeDetectionPolicy": {
        "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
        "highWaterMarkColumnName": "_ts"
    },
    "dataDeletionDetectionPolicy": {
        "@odata.type": "#Microsoft.Azure.Search.SoftDeleteColumnDeletionDetectionPolicy",
        "softDeleteColumnName": "isDeleted",
        "softDeleteMarkerValue": "true"
    }
}

Langkah berikutnya

Anda sekarang dapat mengontrol bagaimana Anda menjalankan pengindeks, memantau status, atau menjadwalkan eksekusi pengindeks. Artikel berikut berlaku untuk pengindeks yang menarik konten dari Azure Cosmos DB:

• Siapkan koneksi pengindeks ke database Cosmos DB dengan menggunakan identitas terkelola
• Indeks kumpulan data besar
• Akses pengindeks ke konten yang dilindungi oleh fitur keamanan jaringan Azure