Tingkatkan ke REST API terbaru di Pencarian Azure AI

Gunakan artikel ini untuk bermigrasi ke versi API REST Layanan Pencarian yang lebih baru dan REST API Manajemen Pencarian untuk bidang data dan operasi sarana kontrol .

Berikut adalah versi terbaru REST API:

Operasi yang ditargetkan REST API Status
Bidang data 2026-04-01 Stabil
Bidang data 2026-05-01-preview Tinjauan
Pesawat Kontrol 2025-05-01 Stabil
Pesawat Kontrol 2026-03-01-preview Tinjauan

Instruksi peningkatan berfokus pada perubahan kode yang membuat Anda melalui perubahan menerobos dari versi sebelumnya sehingga kode yang ada berjalan sama seperti sebelumnya, tetapi pada versi API yang lebih baru. Setelah kode Anda berfungsi dengan baik, Anda dapat memutuskan apakah akan mengadopsi fitur yang lebih baru. Untuk mempelajari selengkapnya tentang fitur baru, lihat Yang baru di Pencarian Azure AI.

Sebaiknya Anda meningkatkan versi API secara berurutan, bekerja melalui setiap versi hingga sampai ke versi terbaru.

2023-07-01-preview adalah REST API pertama untuk dukungan vektor. Jangan gunakan versi API ini. Sekarang tidak digunakan lagi dan Anda harus segera bermigrasi ke REST API pratinjau yang stabil atau lebih baru.

Catatan

Dokumen referensi REST API sekarang diberi versi. Untuk konten khusus versi, buka halaman referensi lalu gunakan pemilih yang terletak di atas daftar isi, untuk memilih versi Anda.

Kapan harus memutakhirkan

Pencarian Azure AI memutus kompatibilitas ke belakang sebagai upaya terakhir. Peningkatan diperlukan ketika:

  • Kode Anda mereferensikan versi API yang dihentikan atau tidak didukung dan tunduk pada satu atau beberapa perubahan yang melanggar.

  • Kode Anda gagal saat properti yang tidak dikenal dikembalikan dalam respons API. Sebagai praktik terbaik, aplikasi Anda harus mengabaikan properti yang tidak dipahaminya.

  • Kode Anda mempertahankan permintaan API dan mencoba mengirimnya kembali ke versi API baru. Misalnya, ini mungkin terjadi jika aplikasi Anda mempertahankan token kelanjutan yang dikembalikan dari SEARCH API (untuk informasi selengkapnya, cari @search.nextPageParameters di Referensi SEARCH API).

Cara melakukan upgrade

  1. Jika Anda meningkatkan versi sarana data, tinjau apa yang telah dirilis dalam versi API baru.

  2. api-version Perbarui parameter, yang ditentukan di header permintaan, ke versi yang lebih baru.

    Dalam kode aplikasi Anda yang melakukan panggilan langsung ke REST API, cari semua instans versi yang ada lalu ganti dengan versi baru. Untuk informasi selengkapnya tentang penataan panggilan REST, lihat Mulai Cepat: Pencarian teks lengkap menggunakan REST.

    Jika Anda menggunakan Azure SDK, setiap paket menargetkan versi REST API tertentu. Untuk menentukan versi REST API mana yang didukung paket Anda, tinjau log perubahannya. Perbarui ke versi paket terbaru untuk mengakses fitur terbaru dan peningkatan API.

  3. Jika Anda meningkatkan versi bidang data, periksa perubahan signifikan yang didokumentasikan dalam artikel ini dan terapkan solusi-solusi tersebut. Mulailah dengan versi yang digunakan oleh kode Anda dan atasi perubahan yang mengganggu untuk setiap versi API yang lebih baru sampai Anda mencapai rilis stabil atau pratinjau terbaru.

Memutus perubahan

Perubahan besar yang disebutkan berikut ini berlaku untuk operasi data.

Perubahan yang berdampak pada pengambilan agentik

2026-04-01 adalah versi REST API stabil pertama untuk pemulihan berbasis agen. Ini menyertakan perubahan yang memutus kompatibilitas berikut dari 2025-11-01-preview:

  • Sintesis jawaban, perencanaan kueri, dan upaya penalaran yang dapat dikonfigurasi dihapus. Pengambilan hanya mengembalikan konten ekstraktif dan berbasis fakta.

  • Perubahan bentuk permintaan ambil: messages digantikan oleh intents, dan beberapa parameter diganti namanya atau dihapus.

  • Penyaringan izin pada tingkat dokumen untuk sumber pengetahuan blob dan OneLake tidak didukung.

Untuk daftar lengkap perubahan tingkat properti dan langkah-langkah migrasi, lihat Memigrasikan kode pengambilan agenik Anda.

Perubahan yang mempengaruhi fungsi untuk agen pengetahuan

Agen pengetahuan diperkenalkan di 2025-05-01-preview. Di 2025-08-01-preview, targetIndexes diganti dengan objek sumber pengetahuan baru, dan defaultMaxDocsForReranker diganti dengan API lain. Perubahan besar lainnya diperkenalkan di 2025-11-01-preview.

Untuk daftar lengkap perubahan tingkat properti dan langkah-langkah migrasi, lihat Memigrasikan kode pengambilan agenik Anda.

Melanggar perubahan untuk kode klien yang membaca informasi koneksi

Berlaku mulai 29 Maret 2024 dan berlaku untuk semua REST API yang didukung:

  • GET Skillset, GET Index, dan GET Indexer tidak lagi mengembalikan kunci atau properti koneksi dalam respons. Ini adalah perubahan yang melanggar jika Anda memiliki kode hilir yang membaca kunci atau koneksi (data sensitif) dari respons GET.

  • Jika Anda perlu mengambil kunci API admin atau kueri untuk layanan pencarian Anda, gunakan REST API Manajemen Pencarian.

  • Jika Anda perlu mengambil string koneksi dari sumber daya Azure lain seperti Azure Storage atau Azure Cosmos DB, gunakan API sumber daya tersebut dan panduan yang diterbitkan untuk mendapatkan informasi.

Perubahan besar untuk pemeringkat semantik

Peringkat semantik sudah tersedia secara umum di 2023-11-01. Ini adalah perubahan yang merusak kompatibilitas dari rilis sebelumnya:

  • Di semua versi setelah 2020-06-01-preview: semanticConfiguration menggantikan searchFields sebagai mekanisme untuk menentukan bidang mana yang akan digunakan untuk peringkat L2.

  • Untuk semua versi API, pembaruan pada 14 Juli 2023 ke model semantik yang dihosting Microsoft membuat pemeringkat semantik yang tidak bergantung pada bahasa, secara efektif menghentikan properti queryLanguage. Tidak ada "breaking change" dalam kode, tetapi properti tersebut diabaikan.

Lihat Migrasi dari versi pratinjau untuk memigrasikan kode Anda menggunakan semanticConfiguration.

Peningkatan sarana data

Panduan peningkatan mengasumsikan peningkatan dari versi terbaru sebelumnya. Jika kode Anda didasarkan pada versi API lama, sebaiknya tingkatkan melalui setiap versi berturut-turut untuk masuk ke versi terbaru.

Tingkatkan ke versi 2026-05-01-preview

2026-05-01-preview menambahkan jenis sumber pengetahuan baru, parameter baru pada tindakan pengambilan, jenis konten pengindeks SharePoint baru dan opsi ACL, dan kemampuan lainnya.

Tidak ada perubahan yang merusak kompatibilitas pada level wire dari 2025-11-01-preview. Namun, jika Anda menggunakan SDK Python atau JavaScript untuk pengambilan berbasis agen, klien retrieve diubah namanya menjadi KnowledgeBaseRetrievalClient, dan retrieveKnowledge(...) diganti dengan retrieve(...). Untuk panduan migrasi SDK, lihat Memigrasikan kode retrieval agentik Anda.

Untuk semua API lain yang ada, tidak ada perubahan perilaku. Anda dapat bertukar di versi API baru, dan kode Anda berjalan sama seperti sebelumnya.

Tingkatkan ke 2026-04-01

2026-04-01 adalah versi REST API stabil terbaru. Ini mempromosikan pengambilan agenik, memilih sumber pengetahuan, dan beberapa keterampilan dan fitur untuk ketersediaan umum.

Sebelum Anda meng-upgrade, periksa apakah salah satu perubahan yang mengganggu berikut 2026-04-01 berlaku untuk kode Anda:

  • Enam properti dihapus dari definisi keterampilan GenAI Prompt: httpMethod, timeout, batchSize, degreeOfParallelism, httpHeaders, dan authResourceId. Hapus properti ini sebelum Anda memutakhirkan. Definisi yang masih menyertakan properti ini mengembalikan 400 Bad Request kesalahan.

  • Persetujuan penagihan khusus sekarang diperlukan untuk pengambilan Agentic. Jika saat ini Anda memiliki semanticSearch=standard, Anda harus secara eksplisit mengatur knowledgeRetrieval=standard sebelum memutakhirkan. Untuk informasi selengkapnya, lihat Aktifkan atau nonaktifkan penagihan pengambilan agentik.

  • Jika kode pengambilan agenik Anda menargetkan 2025-11-01-preview, 2026-04-01 menghapus beberapa kemampuan pratinjau dan menstandarkan pengambilan di sekitar input niat, output ekstraktif, dan penalaran minimal. Untuk informasi selengkapnya, lihat Memigrasikan kode pengambilan agenik Anda.

Untuk semua API lain yang ada, tidak ada perubahan perilaku. Anda dapat bertukar di versi API baru, dan kode Anda berjalan sama seperti sebelumnya.

Tingkatkan ke versi pratinjau 2025-11-01

2025-11-01-preview memperkenalkan perubahan mendasar berikut pada pengambilan agenik seperti diimplementasikan dalam 2025-08-01-preview.

  • agents Mengganti dengan knowledgebases. Beberapa properti yang terkait dengan sumber pengetahuan dipindahkan dari definisi basis pengetahuan ke aksi pengambilan.

  • Properti sumber pengetahuan direstruktur, menerapkan objek baru ingestionParameters untuk sumber pengetahuan yang menghasilkan alur kerja pengindeks.

Untuk daftar lengkap perubahan tingkat properti dan langkah-langkah migrasi, lihat Memigrasikan kode pengambilan agenik Anda.

Untuk semua API lain yang ada, tidak ada perubahan perilaku. Anda dapat bertukar di versi API baru, dan kode Anda berjalan sama seperti sebelumnya.

Tingkatkan ke 2025-09-01

2025-09-01 adalah versi REST API yang stabil yang menambahkan ketersediaan umum untuk pengindeks OneLake, keterampilan Tata Letak Dokumen, dan API lainnya.

Tidak ada perubahan yang merusak jika Anda memutakhirkan dari 2024-07-01 dan tidak menggunakan fitur pratinjau apa pun. Untuk menggunakan rilis stabil baru, ubah versi API dan uji kode Anda.

Tingkatkan versi ke versi pratinjau 2025-08-01

2025-08-01-preview memperkenalkan perubahan mencolok berikut pada agen pengetahuan yang dibuat menggunakan 2025-05-01-preview:

  • targetIndexes Mengganti dengan knowledgeSources.
  • Menghapus defaultMaxDocsForReranker tanpa penggantian.

Jika tidak, tidak ada perubahan perilaku pada API yang ada. Anda dapat bertukar di versi API baru, dan kode Anda berjalan sama seperti sebelumnya.

Memutakhirkan ke versi pratinjau 2025-05-01

2025-05-01-preview menyediakan fitur baru, tetapi tidak ada perubahan perilaku pada API yang ada. Anda dapat bertukar di versi API baru, dan kode Anda berjalan sama seperti sebelumnya.

Tingkatkan ke versi pratinjau 2025-03-01

2025-03-01-preview menyediakan fitur baru, tetapi tidak ada perubahan perilaku pada API yang ada. Anda dapat bertukar di versi API baru, dan kode Anda berjalan sama seperti sebelumnya.

Tingkatkan ke pratinjau 2024-11-01

2024-11-01-preview penulisan ulang kueri, keterampilan Tata Letak Dokumen, penagihan tanpa kunci untuk pemrosesan keterampilan, mode penguraian Markdown, dan opsi penilaian ulang untuk vektor terkompresi.

Jika Anda meningkatkan dari 2024-09-01-preview, Anda dapat menggantinya dengan versi API baru, dan kode Anda akan berjalan sama seperti sebelumnya.

Namun, versi baru memperkenalkan perubahan sintaksis pada vectorSearch.compressions:

  • rerankWithOriginalVectors Ganti denganenableRescoring
  • defaultOversampling Berpindah ke objek properti baru rescoringOptions

Kompatibilitas mundur dipertahankan karena pemetaan API internal, tetapi sebaiknya mengubah sintaks jika Anda menggunakan versi pratinjau baru. Untuk perbandingan sintaks, lihat Kompres vektor menggunakan skalar atau kuantisasi biner.

Perbarui ke versi pratinjau 2024-09-01

2024-09-01-preview menambahkan kompresi Matryoshka Representation Learning (MRL) untuk model text-embedding-3, pemfilteran vektor yang ditargetkan untuk kueri hibrid, detail subskore vektor untuk penelusuran kesalahan, dan potongan token untuk keterampilan Pemisahan Teks.

Jika Anda meningkatkan dari 2024-05-01-preview, Anda dapat menggantinya dengan versi API baru, dan kode Anda akan berjalan sama seperti sebelumnya.

Tingkatkan ke 2024-07-01

2024-07-01 adalah rilis umum. Fitur pratinjau sebelumnya sekarang tersedia secara umum: pemecahan dan vektorisasi terintegrasi (keterampilan Pemisahan Teks, keterampilan AzureOpenAIEmbedding), pemvektor kueri yang didasarkan pada AzureOpenAIEmbedding, kompresi vektor (kuantisasi skalar, kuantisasi biner, properti tersimpan, tipe data terbatas).

Tidak ada perubahan yang memengaruhi kompatibilitas jika Anda meningkatkan dari 2024-05-01-preview ke versi stabil. Untuk menggunakan rilis stabil baru, ubah versi API dan uji kode Anda.

Ada perubahan yang mengganggu kompatibilitas jika Anda meningkatkan langsung dari 2023-11-01. Ikuti langkah-langkah berikut untuk setiap pratinjau yang lebih baru untuk bermigrasi dari 2023-11-01 ke 2024-07-01.

Tingkatkan ke versi pratinjau 2024-05-01

2024-05-01-preview menambahkan pengindeks untuk Microsoft OneLake, vektor biner, dan model penyematan lainnya.

Jika Anda meningkatkan dari 2024-03-01-preview, fungsi AzureOpenAIEmbedding sekarang memerlukan nama model dan properti dimensi.

  1. Cari basis kode Anda untuk referensi AzureOpenAIEmbedding .

  2. Atur modelName ke "text-embedding-ada-002" dan atur dimensions ke "1536".

Tingkatkan ke versi pratinjau 2024-03-01

2024-03-01-preview menambahkan jenis data sempit, kuantisasi skalar, dan opsi penyimpanan vektor.

Jika Anda memutakhirkan dari 2023-10-01-preview, tidak ada perubahan signifikan. Namun, ada satu perbedaan perilaku: untuk pratinjau 2023-11-01 dan versi yang lebih baru, default vectorFilterMode diubah dari pascafilter menjadi prafilter untuk ekspresi filter.

  1. Cari referensi vectorFilterMode pada basis kode Anda.

  2. Jika properti diatur secara eksplisit, tidak ada tindakan yang diperlukan. Jika Anda mengandalkan nilai default, perilaku default baru adalah memfilter sebelum eksekusi kueri. Jika Anda ingin pemfilteran pasca-kueri, atur vectorFilterMode secara eksplisit ke postfilter untuk mempertahankan perilaku lama.

Tingkatkan ke 2023-11-01

2023-11-01 adalah rilis umum. Fitur pratinjau sebelumnya sekarang tersedia secara umum: peringkat semantik dan dukungan vektor.

Tidak ada perubahan yang memutus kompatibilitas dari 2023-10-01-preview, tetapi ada banyak perubahan yang memutus kompatibilitas dari 2023-07-01-preview ke 2023-11-01. Untuk informasi selengkapnya, lihat Peningkatan dari pratinjau 2023-07-01.

Untuk menggunakan rilis stabil baru, ubah versi API dan uji kode Anda.

Tingkatkan ke versi pratinjau 2023-10-01

2023-10-01-preview adalah versi pratinjau pertama yang menambahkan pemotongan dan vektorisasi data bawaan selama pengindeksan dan vektorisasi kueri bawaan. Ini juga mendukung pengindeksan vektor dan kueri dari versi sebelumnya.

Jika Anda memutakhirkan dari versi sebelumnya, bagian berikutnya memiliki langkah-langkahnya.

Peningkatan menjadi versi pratinjau mulai 2023-07-01

Jangan gunakan versi API ini. Ini menerapkan sintaks kueri vektor yang tidak kompatibel dengan versi API yang lebih baru.

2023-07-01-preview sekarang tidak digunakan lagi, jadi Anda tidak boleh mendasarkan kode baru pada versi ini, anda juga tidak boleh meningkatkan ke versi ini dalam keadaan apa pun. Bagian ini menjelaskan jalur migrasi dari 2023-07-01-preview ke versi API yang lebih baru.

Peningkatan portal untuk indeks vektor

Azure portal mendukung jalur peningkatan satu klik untuk indeks 2023-07-01-preview. Ini mendeteksi bidang vektor dan menyediakan tombol Migrasi .

  • Jalur migrasi dari 2023-07-01-preview ke 2024-05-01-preview.
  • Pembaruan terbatas pada definisi bidang vektor dan konfigurasi algoritma pencarian vektor.
  • Pembaruan bersifat satu arah. Anda tidak dapat membalikkan peningkatan. Setelah indeks dimutakhirkan, Anda harus menggunakan 2024-05-01-preview atau lebih baru untuk mengkueri indeks.

Tidak ada migrasi portal untuk meningkatkan sintaks kueri vektor. Lihat pembaruan kode untuk perubahan sintaksis kueri.

Sebelum memilih Migrasi, pilih Edit JSON untuk meninjau skema yang diperbarui terlebih dahulu. Anda harus menemukan skema yang sesuai dengan perubahan yang dijelaskan di bagian peningkatan kode . Migrasi portal hanya menangani indeks dengan satu konfigurasi algoritma pencarian vektor. Ini membuat profil bawaan yang memetakan ke 2023-07-01-preview algoritma pencarian vektor. Indeks dengan beberapa konfigurasi pencarian vektor memerlukan migrasi manual.

Peningkatan kode untuk indeks dan kueri vektor

Dukungan pencarian vektor diperkenalkan dalam Buat atau Perbarui Indeks (pratinjau 2023-07-01).

Meningkatkan dari 2023-07-01-preview ke versi stabil atau pratinjau yang lebih baru memerlukan:

  • Mengganti nama dan merestrukturisasi konfigurasi vektor dalam indeks
  • Menulis ulang kueri vektor Anda

Gunakan instruksi di bagian ini untuk memigrasikan bidang vektor, konfigurasi, dan kueri dari 2023-07-01-preview.

  1. Panggil Dapatkan Indeks untuk mengambil definisi yang ada.

  2. Ubah konfigurasi pencarian vektor. 2023-11-01 dan versi yang lebih baru memperkenalkan konsep profil vektor yang menggabungkan konfigurasi terkait vektor dengan satu nama. Versi yang lebih baru juga berganti nama algorithmConfigurations menjadi algorithms.

    • Ganti nama algorithmConfigurations menjadi algorithms. Ini hanya penggantian nama array. Konten kompatibel dengan versi sebelumnya. Ini berarti parameter konfigurasi HNSW Anda yang ada dapat digunakan.

    • Tambahkan profiles, berikan nama dan konfigurasi algoritma untuk masing-masing konfigurasi.

    Sebelum migrasi (pratinjau 2023-07-01):

      "vectorSearch": {
    "algorithmConfigurations": [
        {
            "name": "myHnswConfig",
            "kind": "hnsw",
            "hnswParameters": {
                "m": 4,
                "efConstruction": 400,
                "efSearch": 500,
                "metric": "cosine"
            }
        }
    ]}

    Setelah migrasi (2023-11-01):

      "vectorSearch": {
    "algorithms": [
      {
        "name": "myHnswConfig",
        "kind": "hnsw",
        "hnswParameters": {
          "m": 4,
          "efConstruction": 400,
          "efSearch": 500,
          "metric": "cosine"
        }
      }
    ],
    "profiles": [
      {
        "name": "myHnswProfile",
        "algorithm": "myHnswConfig"
      }
    ]
  }

  3. Ubah definisi bidang vektor, ganti vectorSearchConfiguration dengan vectorSearchProfile. Pastikan nama profil mengacu pada definisi profil vektor yang baru, dan bukan nama konfigurasi algoritma. Properti bidang vektor lainnya tetap tidak berubah. Misalnya, mereka tidak dapat difilter, tidak dapat diurutkan, tidak dapat diberi faset, maupun menggunakan penganalisis, normalizer, atau peta sinonim.

    Sebelum (2023-07-01-preview):

      {
      "name": "contentVector",
      "type": "Collection(Edm.Single)",
      "key": false,
      "searchable": true,
      "retrievable": true,
      "filterable": false,  
      "sortable": false,  
      "facetable": false,
      "analyzer": "",
      "searchAnalyzer": "",
      "indexAnalyzer": "",
      "normalizer": "",
      "synonymMaps": "", 
      "dimensions": 1536,
      "vectorSearchConfiguration": "myHnswConfig"
  }

    Setelah (2023-11-01):

      {
    "name": "contentVector",
    "type": "Collection(Edm.Single)",
    "searchable": true,
    "retrievable": true,
    "filterable": false,  
    "sortable": false,  
    "facetable": false,
    "analyzer": "",
    "searchAnalyzer": "",
    "indexAnalyzer": "",
    "normalizer": "",
    "synonymMaps": "", 
    "dimensions": 1536,
    "vectorSearchProfile": "myHnswProfile"
  }

  4. Panggil Buat atau Perbarui Indeks untuk memposting perubahan.

  5. Ubah Search POST untuk mengubah sintaks kueri. Perubahan API ini memungkinkan dukungan untuk jenis kueri vektor polimorfik.

    • Ganti nama vectors menjadi vectorQueries.
    • Untuk setiap kueri vektor, tambahkan kind, atur ke vector.
    • Untuk setiap kueri vektor, ganti nama value menjadi vector.
    • Secara opsional, tambahkan vectorFilterMode jika Anda menggunakan ekspresi filter. Defaultnya adalah prafilter untuk indeks yang dibuat setelah 2023-10-01. Indeks yang dibuat sebelum tanggal tersebut hanya mendukung postfilter, terlepas dari cara Anda mengatur mode filter.

    Sebelum (2023-07-01-preview):

    {
    "search": (this parameter is ignored in vector search),
    "vectors": [
      {
        "value": [
            0.103,
            0.0712,
            0.0852,
            0.1547,
            0.1183
        ],
        "fields": "contentVector",
        "k": 5
      }
    ],
    "select": "title, content, category"
}

    Setelah (2023-11-01):

    {
  "search": "(this parameter is ignored in vector search)",
  "vectorQueries": [
    {
      "kind": "vector",
      "vector": [
        0.103,
        0.0712,
        0.0852,
        0.1547,
        0.1183
      ],
      "fields": "contentVector",
      "k": 5
    }
  ],
  "vectorFilterMode": "preFilter",
  "select": "title, content, category"
}

Langkah-langkah ini menyelesaikan migrasi ke 2023-11-01 versi API yang stabil atau versi API pratinjau yang lebih baru.

Tingkatkan ke 2020-06-30

Dalam versi ini, ada satu perubahan besar dan beberapa perbedaan dalam perilaku. Fitur yang tersedia secara umum meliputi:

  • Penyimpanan pengetahuan, penyimpanan persisten konten yang diperkaya yang dibuat melalui set keterampilan, dibuat untuk analisis dan pemrosesan hilir melalui aplikasi lain. Penyimpanan pengetahuan dibuat melalui REST API Pencarian Azure AI tetapi berada di Azure Storage.

Perubahan signifikan

Kode yang ditulis untuk versi API yang lebih lama akan mengalami kerusakan pada 2020-06-30 dan versi yang lebih baru jika kode berisi fungsi berikut:

  • Dalam ekspresi penyaring, literal mana pun (tanggal yang terdiri dari tahun-bulan-hari, seperti Edm.Date) wajib mengikuti format 2020-12-12: Edm.DateTimeOffset. Perubahan ini diperlukan untuk menangani hasil kueri yang salah atau tidak terduga karena perbedaan zona waktu.

Perubahan perilaku

  • Algoritma peringkat BM25 menggantikan algoritma peringkat sebelumnya dengan teknologi yang lebih baru. Layanan yang dibuat setelah 2019 menggunakan algoritma ini secara otomatis. Untuk layanan lama, Anda harus mengatur parameter untuk menggunakan algoritma baru.

  • Hasil yang diurutkan untuk nilai null telah berubah dalam versi ini, dengan nilai null muncul terlebih dahulu jika pengurutan adalah asc dan terakhir jika pengurutan adalah desc. Jika Anda menulis kode untuk menangani bagaimana nilai null diurutkan, ketahui perubahan ini.

Perbarui ke 2019-05-06

Fitur yang tersedia secara umum dalam versi API ini meliputi:

  • Pelengkapan otomatis adalah fitur typeahead yang menyelesaikan input istilah yang ditentukan sebagian.
  • Jenis kompleks menyediakan dukungan asli untuk data objek terstruktur dalam indeks pencarian.
  • mode penguraian JsonLines, bagian dari pengindeksan Blob Azure, membuat satu dokumen pencarian per entitas JSON yang dipisahkan oleh baris baru.
  • Pengayaan AI menyediakan pengindeksan yang menggunakan mesin pengayaan AI dari Foundry Tools.

Memutus perubahan

Kode yang ditulis untuk versi API sebelumnya mengalami gangguan pada 2019-05-06 dan versi yang lebih baru jika mencakup fungsi berikut:

  1. Ketik properti untuk Azure Cosmos DB. Untuk pengindeks yang menargetkan Azure Cosmos DB untuk NoSQL API sumber data, ubah "type": "documentdb" menjadi "type": "cosmosdb".

  2. Jika penanganan kesalahan pengindeks Anda menyertakan referensi ke status properti , Anda harus menghapusnya. Kami menghapus status dari respons kesalahan karena tidak memberikan informasi yang berguna.

  3. String koneksi sumber data tidak lagi dikembalikan dalam respons. Dari versi 2019-05-06 API dan 2019-05-06-Preview seterusnya, API sumber data tidak lagi mengembalikan string koneksi dalam respons operasi REST apa pun. Dalam versi API sebelumnya, untuk sumber data yang dibuat menggunakan POST, Pencarian Azure AI mengembalikan 201 diikuti oleh respons OData, yang berisi string koneksi dalam teks biasa.

  4. Kemampuan kognitif Pengenalan Entitas Bernama dihentikan. Jika Anda memanggil keterampilan Pengenalan Entitas Nama dalam kode Anda, panggilan gagal. Fungsi penggantian adalah Keterampilan Pengenalan Entitas (V3). Ikuti rekomendasi dalam Keterampilan yang tidak digunakan lagi untuk bermigrasi ke keterampilan yang didukung.

Memutakhirkan jenis kompleks

Versi 2019-05-06 API menambahkan dukungan formal untuk jenis kompleks. Jika kode Anda menerapkan rekomendasi sebelumnya untuk kesetaraan jenis kompleks dalam Pratinjau 2017-11-11 atau Pratinjau 2016-09-01, ada beberapa batas baru dan berubah yang dimulai dalam versi 2019-05-06 yang perlu Anda ketahui:

  • Batasan kedalaman subbidang dan jumlah koleksi kompleks per indeks telah diturunkan. Jika Anda membuat indeks yang melebihi batas ini menggunakan versi api pratinjau, setiap upaya untuk memperbarui atau membuatnya kembali menggunakan versi 2019-05-06 API gagal. Jika Anda menemukan diri Anda dalam situasi ini, Anda perlu mendesain ulang skema Anda agar sesuai dalam batas baru lalu membangun kembali indeks Anda.

  • Ada batas baru mulai versi 2019-05-06 api pada jumlah elemen koleksi kompleks per dokumen. Jika Anda membuat indeks dengan dokumen yang melebihi batas ini menggunakan versi api pratinjau, setiap upaya untuk mengindeks ulang data tersebut menggunakan versi 2019-05-06 api gagal. Jika Anda menemukan diri Anda dalam situasi ini, Anda perlu mengurangi jumlah elemen pengumpulan kompleks per dokumen sebelum mengindeks ulang data Anda.

Untuk informasi selengkapnya, lihat batas Service untuk Pencarian Azure AI.

Cara meningkatkan struktur jenis kompleks lama

Jika kode Anda menggunakan jenis kompleks dengan salah satu versi API pratinjau yang lebih lama, Anda mungkin menggunakan format definisi indeks yang terlihat seperti ini:

{
  "name": "hotels",  
  "fields": [
    { "name": "HotelId", "type": "Edm.String", "key": true, "filterable": true },
    { "name": "HotelName", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": true, "facetable": false },
    { "name": "Description", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.microsoft" },
    { "name": "Description_fr", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "fr.microsoft" },
    { "name": "Category", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "sortable": false, "facetable": true, "analyzer": "tagsAnalyzer" },
    { "name": "ParkingIncluded", "type": "Edm.Boolean", "filterable": true, "sortable": true, "facetable": true },
    { "name": "LastRenovationDate", "type": "Edm.DateTimeOffset", "filterable": true, "sortable": true, "facetable": true },
    { "name": "Rating", "type": "Edm.Double", "filterable": true, "sortable": true, "facetable": true },
    { "name": "Address", "type": "Edm.ComplexType" },
    { "name": "Address/StreetAddress", "type": "Edm.String", "filterable": false, "sortable": false, "facetable": false, "searchable": true },
    { "name": "Address/City", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Address/StateProvince", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Address/PostalCode", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Address/Country", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Location", "type": "Edm.GeographyPoint", "filterable": true, "sortable": true },
    { "name": "Rooms", "type": "Collection(Edm.ComplexType)" }, 
    { "name": "Rooms/Description", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.lucene" },
    { "name": "Rooms/Description_fr", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "fr.lucene" },
    { "name": "Rooms/Type", "type": "Edm.String", "searchable": true },
    { "name": "Rooms/BaseRate", "type": "Edm.Double", "filterable": true, "facetable": true },
    { "name": "Rooms/BedOptions", "type": "Edm.String", "searchable": true },
    { "name": "Rooms/SleepsCount", "type": "Edm.Int32", "filterable": true, "facetable": true },
    { "name": "Rooms/SmokingAllowed", "type": "Edm.Boolean", "filterable": true, "facetable": true },
    { "name": "Rooms/Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "facetable": true, "analyzer": "tagsAnalyzer" }
  ]
}

Format seperti pohon yang lebih baru untuk menentukan bidang indeks diperkenalkan dalam versi 2017-11-11-PreviewAPI . Dalam format baru, setiap bidang kompleks memiliki kumpulan bidang tempat sub-bidangnya ditentukan. Dalam API versi 2019-05-06, format baru ini digunakan secara eksklusif dan mencoba membuat atau memperbarui indeks menggunakan format lama akan gagal. Jika Anda memiliki indeks yang dibuat menggunakan format lama, Anda harus menggunakan versi 2017-11-11-Preview API untuk memperbaruinya ke format baru sebelum dapat dikelola menggunakan API versi 2019-05-06.

Anda dapat memperbarui indeks datar ke format baru dengan langkah-langkah berikut menggunakan versi 2017-11-11-PreviewAPI :

  1. Lakukan permintaan GET untuk mengambil indeks Anda. Jika sudah dalam format baru, Anda sudah selesai.

  2. Terjemahkan indeks dari format datar ke format baru. Anda harus menulis kode untuk tugas ini karena tidak ada kode sampel yang tersedia pada saat penulisan ini.

  3. Lakukan permintaan PUT untuk memperbarui indeks ke format baru. Hindari mengubah detail indeks lainnya, seperti kemampuan pencarian/filterabilitas bidang, karena perubahan yang memengaruhi ekspresi fisik indeks yang ada tidak diizinkan oleh API Indeks Pembaruan.

Catatan

Tidak dimungkinkan untuk mengelola indeks yang dibuat dengan format "datar" lama dari portal Azure. Tingkatkan indeks Anda dari representasi "datar" ke representasi "pohon" sesegera mungkin.

Peningkatan sarana kontrol

Berlaku untuk:2014-07-31-Preview, 2015-02-28, dan 2015-08-19

Permintaan listQueryKeys GET pada versi SEARCH Management API yang lebih lama sekarang tidak digunakan lagi. Sebaiknya migrasikan ke versi API sarana kontrol stabil terbaru untuk menggunakan listQueryKeys permintaan POST.

  1. Dalam kode yang ada, ubah api-version parameter ke versi terbaru (2025-05-01).

  2. Reframe permintaan dari GET ke POST:

    POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Search/searchServices/{searchServiceName}/listQueryKeys?api-version=2025-05-01
Authorization: Bearer {{token}}

  3. Jika Anda menggunakan Azure SDK, disarankan agar Anda meningkatkan ke versi terbaru.

Langkah berikutnya

Tinjau dokumentasi referensi Search REST API. Jika Anda mengalami masalah, minta bantuan kami tentang Stack Overflow atau hubungi dukungan.

Referensi REST API layanan pencarian

  • Last updated on