Zaktualizuj się do najnowszego interfejsu API REST w usłudze Azure AI Search

Użyj tego artykułu, aby przeprowadzić migrację do nowszych wersji interfejsów API REST usługi wyszukiwania i interfejsów API REST zarządzania wyszukiwaniem na potrzeby operacji płaszczyzny danych i płaszczyzny sterowania .

Poniżej przedstawiono najnowsze wersje interfejsów API REST:

Instrukcje uaktualniania koncentrują się na zmianach kodu, które umożliwiają radzenie sobie z niezgodnościami z poprzednich wersji, tak aby istniejący kod działał tak jak wcześniej, ale na nowszej wersji API. Gdy kod jest w porządku roboczym, możesz zdecydować, czy wdrażać nowsze funkcje. Aby dowiedzieć się więcej o nowych funkcjach, zobacz Co nowego.

Zalecamy aktualizację wersji interfejsu API po kolei, przechodząc przez każdą wersję do najnowszej.

2023-07-01-preview był pierwszym interfejsem API REST obsługującym wektory. Nie używaj tej wersji interfejsu API. Jest ona teraz przestarzała i natychmiast należy przeprowadzić migrację do stabilnych lub nowszych interfejsów API REST w wersji zapoznawczej.

Kiedy należy uaktualnić

Usługa Azure AI Search przerywa zgodność z poprzednimi wersjami w ostateczności. Uaktualnienie jest konieczne, gdy:

• Kod odwołuje się do wycofanej lub nieobsługiwanej wersji interfejsu API i podlega co najmniej jednej zmianie, która może zakłócić działanie. Musisz rozwiązać zmiany powodujące niezgodność, jeśli Twój kod celuje w 2025-11-01-preview odnalezienie agentów, 2025-05-01-preview dla agentów wiedzy, 2023-07-10-preview dla wektorów, 2020-06-01-preview dla klasyfikatora semantycznego oraz 2019-05-06 dla przestarzałych umiejętności i obejść.

• Kod kończy się niepowodzeniem, gdy nierozpoznane właściwości są zwracane w odpowiedzi interfejsu API. Najlepszym rozwiązaniem jest ignorowanie właściwości, których nie rozumie.

• Kod utrwala żądania interfejsu API i próbuje ponownie wysłać je do nowej wersji interfejsu API. Na przykład może się to zdarzyć, jeśli aplikacja będzie utrwalać tokeny kontynuacji zwracane z interfejsu API wyszukiwania (aby uzyskać więcej informacji, poszukaj @search.nextPageParameters w dokumentacji interfejsu API wyszukiwania).

Jak przeprowadzić uaktualnianie

1. Jeśli uaktualniasz wersję płaszczyzny danych, zapoznaj się z informacjami o wersji dla nowej wersji interfejsu API.

2. api-version Zaktualizuj parametr określony w nagłówku żądania do nowszej wersji.

   W kodzie aplikacji, który wykonuje bezpośrednie wywołania interfejsów API REST, wyszukaj wszystkie wystąpienia istniejącej wersji, a następnie zastąp ją nową wersją. Aby uzyskać więcej informacji na temat tworzenia struktury wywołania REST, zobacz Szybki start: wyszukiwanie pełnotekstowe przy użyciu interfejsu REST.

   Jeśli używasz zestawu Azure SDK, każdy pakiet jest przeznaczony dla określonej wersji interfejsu API REST. Aby określić, która wersja interfejsu API REST obsługuje pakiet, przejrzyj jego dziennik zmian. Zaktualizuj do najnowszej wersji pakietu, aby uzyskać dostęp do najnowszych funkcji i ulepszeń interfejsu API.

3. Jeśli uaktualniasz wersję płaszczyzny danych, przejrzyj zmiany powodujące niezgodność udokumentowane w tym artykule i zaimplementuj obejścia. Zacznij od wersji używanej przez kod i rozwiąż wszelkie zmiany powodujące niezgodność dla każdej nowszej wersji interfejsu API, dopóki nie uzyskasz najnowszej stabilnej wersji lub wersji zapoznawczej.

Zmiany powodujące niezgodność

Następujące zmiany dotyczą operacji na danych.

Zmiany niekompatybilne dotyczące agentowego pobierania

Najnowsze 2025-11-01-preview refaktoryzacje interfejsów API dla agentów wiedzy (baz), źródeł wiedzy i akcji pobierania. Najnowsza wersja 2025-11-01-preview zmienia nazwę agentów wiedzy na bazy wiedzy oraz przemieszcza kilka właściwości. Kilka właściwości jest zastępowanych lub przenoszonych do innych obiektów.

Aby uzyskać pomoc dotyczącą zmian powodujących niezgodność, zobacz Migrowanie kodu pobierania agenta.

Istotne zmiany dla agentów wiedzy

Agenci wiedzy zostali wprowadzeni w systemie 2025-05-01-preview. W 2025-08-01-preview, targetIndexes został zastąpiony nowym obiektem źródła wiedzy, a defaultMaxDocsForReranker został zastąpiony innymi interfejsami API. W systemie 2025-11-01-preview wprowadzono więcej zmian powodujących niekompatybilność.

Aby uzyskać pomoc dotyczącą zmian powodujących niezgodność, zobacz Migrowanie kodu pobierania agenta.

Istotne zmiany kodu klienta, który odczytuje informacje o połączeniu

Od 29 marca 2024 r. i dotyczy wszystkich obsługiwanych interfejsów API REST:

• Zestaw umiejętności GET, indeks GET i indeksator GET nie zwracają już kluczy ani właściwości połączenia w odpowiedzi. Jest to zmiana powodująca problemy z kompatybilnością, jeśli kod zależny odczytuje klucze lub połączenia (dane poufne) z odpowiedzi GET.

• Jeśli musisz pobrać klucze interfejsu API administratora lub zapytania dla usługi wyszukiwania, użyj interfejsów API REST usługi Search Management.

• Jeśli musisz pobrać parametry połączenia innego zasobu platformy Azure, takiego jak Azure Storage lub Azure Cosmos DB, skorzystaj z interfejsów API tego zasobu i opublikowanych wskazówek, aby uzyskać informacje.

Istotne zmiany dla narzędzia do rangowania semantycznego

Ranking semantyczny stał się ogólnie dostępny w 2023-11-01. Są to zmiany niekompatybilne z wcześniejszymi wersjami:

• We wszystkich wersjach po 2020-06-01-preview: semanticConfiguration zastępuje searchFields jako mechanizm określania pól, które mają być używane do klasyfikacji L2.

• W przypadku wszystkich wersji interfejsu API aktualizacje z 14 lipca 2023 r. dla modeli semantycznych hostowanych przez firmę Microsoft uczyniły klasyfikator semantyczny niezależnym od języka, skutecznie likwidując właściwość queryLanguage. W kodzie nie ma żadnych zmian powodujących niezgodność, ale właściwość jest ignorowana.

Zobacz Migrowanie z wersji próbnej, aby przenieść kod do użycia semanticConfiguration.

Uaktualnienia warstwy danych

Wskazówki dotyczące uaktualniania zakładają uaktualnienie z najnowszej poprzedniej wersji. Jeśli twój kod jest oparty na starej wersji interfejsu API, zalecamy uaktualnienie do każdej kolejnej wersji, aby przejść do najnowszej wersji.

Uaktualnianie do wersji 2025-11-01-preview

2025-11-01-preview wprowadza następujące zmiany naruszające zgodność związane z pozyskiwaniem agenta zgodnie z implementacją w 2025-08-01-preview.

• Zamienia element agents na knowledgebases. Kilka właściwości związanych ze źródłami wiedzy przeniesiono z definicji bazy wiedzy i do akcji pobierania.
• Właściwości źródła wiedzy zostały zrefaktoryzowane, implementując nowy obiekt ingestionParameters dla źródeł wiedzy, które generują rurkę indeksującą.

Aby uzyskać więcej informacji na temat zmian i migracji kodu, zobacz Zmiany łamiące zgodność w wersji 2025-11-01-preview i Jak przeprowadzić migrację.

W przypadku wszystkich innych istniejących interfejsów API nie ma żadnych zmian zachowania. Możesz zamienić nową wersję interfejsu API, a kod działa tak samo jak poprzednio.

Uaktualnianie do wersji 2025-09-01

2025-09-01 jest najnowszą stabilną wersją interfejsu API REST i zapewnia ogólną dostępność indeksatora OneLake, funkcji analizy układu dokumentu oraz innych interfejsów API.

Nie ma żadnych zmian powodujących niezgodność, jeśli uaktualniasz program 2024-07-01 i nie korzystasz z żadnych funkcji w wersji zapoznawczej. Aby użyć nowej stabilnej wersji, zmień wersję interfejsu API i przetestuj kod.

Uaktualnianie do wersji 2025-08-01-preview

2025-08-01-preview wprowadza następujące zmiany powodujące niezgodność dla agentów wiedzy utworzonych przy użyciu polecenia 2025-05-01-preview:

• Zamienia element targetIndexes na knowledgeSources.
• Usuwa bez zamiany defaultMaxDocsForReranker .

W przeciwnym razie nie ma żadnych zmian zachowania w istniejących interfejsach API. Możesz zamienić nową wersję interfejsu API, a kod działa tak samo jak poprzednio.

Uaktualnianie do wersji 2025-05-01-preview

2025-05-01-preview udostępnia nowe funkcje, ale nie ma żadnych zmian zachowania w istniejących interfejsach API. Możesz zamienić nową wersję interfejsu API, a kod działa tak samo jak poprzednio.

Uaktualnianie do wersji 2025-03-01-preview

2025-03-01-preview udostępnia nowe funkcje, ale nie ma żadnych zmian zachowania w istniejących interfejsach API. Możesz zamienić nową wersję interfejsu API, a kod działa tak samo jak poprzednio.

Uaktualnianie do wersji 2024-11-01-preview

2024-11-01-preview przepisywanie zapytań, funkcja układu dokumentu, rozliczanie bez użycia kluczy w przetwarzaniu funkcji, tryb analizowania Markdown oraz opcje rekalkulacji dla skompresowanych wektorów.

Jeśli aktualizujesz z 2024-09-01-preview, możesz zamienić na nową wersję interfejsu API, a twój kod będzie działał tak samo jak wcześniej.

Jednak nowa wersja wprowadza zmiany składni w pliku vectorSearch.compressions:

• Zamienia rerankWithOriginalVectors na enableRescoring
• Przenosi defaultOversampling do nowego rescoringOptions obiektu właściwości

Zgodność z poprzednimi wersjami jest zachowywana z powodu wewnętrznego mapowania interfejsu API, ale zalecamy zmianę składni w przypadku wdrożenia nowej wersji zapoznawczej. Aby uzyskać porównanie składni, zobacz Kompresowanie wektorów przy użyciu kwantyzacji skalarnej lub binarnej.

Uaktualnianie do wersji 2024-09-01-preview

2024-09-01-preview Dodaje kompresję Matryoshka Representation Learning (MRL) dla modeli text-embedding-3, ukierunkowane filtrowanie wektorów dla zapytań hybrydowych, szczegóły podscoreu wektorów na potrzeby debugowania oraz podział tokenów dla umiejętności dzielenia tekstu.

Jeśli aktualizujesz z 2024-05-01-preview, możesz zamienić na nową wersję interfejsu API, a twój kod będzie działał tak samo jak wcześniej.

Uaktualnianie do wersji 2024-07-01

2024-07-01 jest wydaniem ogólnym. Dawne funkcje w wersji zapoznawczej są teraz ogólnie dostępne: zintegrowane fragmentowanie i wektoryzacja (funkcja dzielenia tekstu, funkcja AzureOpenAIEmbedding), wektoryzator zapytań oparty na AzureOpenAIEmbedding, kompresja wektorów (kwantyzacja skalarna, kwantyzacja binarna, przechowywane właściwości, wąskie typy danych).

Nie ma żadnych istotnych zmian, jeśli zaktualizujesz z 2024-05-01-preview do stabilnej wersji. Aby użyć nowej stabilnej wersji, zmień wersję interfejsu API i przetestuj kod.

Zmiany powodujące niezgodność występują w przypadku uaktualniania bezpośrednio z programu 2023-11-01. Wykonaj kroki opisane dla każdej nowszej wersji zapoznawczej, aby przeprowadzić migrację z 2023-11-01 do 2024-07-01programu .

Uaktualnianie do wersji 2024-05-01-preview

2024-05-01-preview Dodaje indekser dla Microsoft OneLake, wektorów binarnych i innych modeli embedowania.

W przypadku uaktualniania z 2024-03-01-preview, usługa AzureOpenAIEmbedding wymaga teraz właściwości nazwy modelu i wymiarów.

1. Przeszukaj bazę kodu w poszukiwaniu referencji do AzureOpenAIEmbedding.

2. Ustaw modelName wartość "text-embedding-ada-002" i ustaw wartość dimensions "1536".

Uaktualnianie do wersji 2024-03-01-preview

2024-03-01-preview Dodaje wąskie typy danych, kwantyzację skalarną i opcje magazynu wektorów.

W przypadku uaktualniania z 2023-10-01-preview nie ma żadnych zmian, które powodują niezgodność. Istnieje jednak jedna różnica między sposobem działania: w przypadku 2023-11-01 i nowszych podglądów domyślne ustawienie vectorFilterMode zmieniło się z postfiltru na prefiltr dla wyrażeń filtrujących.

1. Wyszukaj bazę kodu pod kątem vectorFilterMode odwołań.

2. Jeśli właściwość jest jawnie ustawiona, nie jest wymagana żadna akcja. Jeśli opierasz się na wartości domyślnej, nowe domyślne zachowanie polega na filtrowaniu przed wykonaniem zapytania. Jeśli chcesz filtrować po kwerendzie, wyraźnie ustaw vectorFilterMode na 'postfilter', aby zachować stare zachowanie.

Uaktualnianie do wersji 2023-11-01

2023-11-01 jest wydaniem ogólnym. Poprzednie funkcje w wersji zapoznawczej są teraz ogólnodostępne: semantyczny ranker i obsługa wektorów.

Nie ma żadnych zmian powodujących niezgodność z 2023-10-01-preview, ale istnieje wiele zmian powodujących niezgodność między 2023-07-01-preview a 2023-11-01. Aby uzyskać więcej informacji, zobacz sekcję Uaktualnianie z wersji 2023-07-01-preview.

Aby użyć nowej stabilnej wersji, zmień wersję interfejsu API i przetestuj kod.

Uaktualnianie do wersji 2023-10-01-preview

2023-10-01-preview była pierwszą wersją zapoznawczą, która umożliwia dodanie wbudowanego podziału danych na fragmenty i wektoryzacji podczas indeksowania oraz wbudowanej wektoryzacji zapytań. Obsługuje również indeksowanie wektorów i zapytania z poprzedniej wersji.

Jeśli uaktualniasz poprzednią wersję, w następnej sekcji przedstawiono kroki.

Uaktualnianie z wersji 2023-07-01-preview

Nie używaj tej wersji interfejsu API. Implementuje on składnię zapytania wektorowego, która jest niezgodna z dowolną nowszą wersją interfejsu API.

2023-07-01-preview jest teraz przestarzały, więc nie należy bazować nowego kodu na tej wersji ani nie należy uaktualniać do tej wersji w żadnych okolicznościach. W tej sekcji opisano ścieżkę migracji z 2023-07-01-preview do nowszej wersji interfejsu API.

Uaktualnianie portalu dla indeksów wektorów

Witryna Azure Portal obsługuje ścieżkę uaktualnienia jednym kliknięciem dla 2023-07-01-preview indeksów. Wykrywa pola wektorów i udostępnia przycisk Migruj.

• Ścieżka migracji to od 2023-07-01-preview do 2024-05-01-preview.
• Aktualizacje są ograniczone do definicji pól wektorowych i konfiguracji algorytmów wyszukiwania wektorów.
• Aktualizacje są jednokierunkowe. Nie można cofnąć uaktualnienia. Po zaktualizowaniu indeksu należy użyć 2024-05-01-preview lub nowszej wersji, aby wykonać zapytanie dotyczące indeksu.

Nie ma migracji portalu do uaktualniania składni zapytań wektorowych. Zobacz Uaktualnienia kodu, aby uzyskać informacje o zmianach składni zapytań.

Przed wybraniem opcji Migruj, wybierz opcję Edytuj kod JSON, aby najpierw przejrzeć zaktualizowany schemat. Należy znaleźć schemat zgodny ze zmianami opisanymi w sekcji uaktualniania kodu. Migracja portalu obsługuje tylko indeksy z jedną konfiguracją algorytmu wyszukiwania wektorowego. Tworzy domyślny profil, który mapuje na algorytm wyszukiwania wektorowego 2023-07-01-preview. Indeksy z wieloma konfiguracjami wyszukiwania wektorowego wymagają migracji ręcznej.

Uaktualnianie kodu dla indeksów wektorów i zapytań

Obsługa wyszukiwania wektorowego została wprowadzona w sekcji Tworzenie lub aktualizowanie indeksu (2023-07-01-preview).

Uaktualnienie z 2023-07-01-preview do nowszej stabilnej lub zapoznawczej wersji wymaga:

• Zmiana nazwy i restrukturyzacja konfiguracji wektora w indeksie
• Ponowne zapisywanie zapytań wektorowych

Skorzystaj z instrukcji w tej sekcji, aby przeprowadzić migrację pól wektorów, konfiguracji i zapytań z programu 2023-07-01-preview.

1. Wywołaj metodę Pobierz indeks , aby pobrać istniejącą definicję.

2. Zmodyfikuj konfigurację wyszukiwania wektorowego. 2023-11-01 i nowsze wersje przedstawiają koncepcję profilów wektorów, które łączą konfiguracje związane z wektorami pod jedną nazwą. Nowsze wersje również zmieniają nazwę algorithmConfigurations na algorithms.

   • Zmień nazwę algorithmConfigurations na algorithms. Jest to tylko zmiana nazwy tablicy. Zawartość jest zgodna z poprzednimi wersjami. Oznacza to, że można użyć istniejących parametrów konfiguracji HNSW.

   • Dodaj profileselement , podając nazwę i konfigurację algorytmu dla każdego z nich.

   Przed migracją (2023-07-01-preview):

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

   Po migracji (2023-11-01):

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

3. Zmodyfikuj definicje pól wektorów, zastępując ciąg vectorSearchConfiguration ciągiem vectorSearchProfile. Upewnij się, że nazwa profilu jest rozpoznawana jako nowa definicja profilu wektorowego, a nie nazwa konfiguracji algorytmu. Inne właściwości pola wektorowego pozostają niezmienione. Na przykład nie można ich filtrować, sortować ani nadawać im cech facetingu, ani używać analizatorów, normalizatorów czy map synonimów.

   Przed (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"
     }
   

   Po (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. Wywołaj metodę Utwórz lub Zaktualizuj indeks , aby opublikować zmiany.

5. Zmodyfikuj wyszukiwanie POST , aby zmienić składnię zapytania. Ta zmiana interfejsu API umożliwia obsługę typów zapytań wektorów polimorficznych.

   • Zmień nazwę vectors na vectorQueries.
   • Dla każdego zapytania wektorowego dodaj element kind, ustawiając go na vector.
   • Dla każdego zapytania wektorowego zmień nazwę value na vector.
   • Opcjonalnie dodaj vectorFilterMode , jeśli używasz wyrażeń filtru. Wartość domyślna to wstępne filtrowanie indeksów utworzonych po 2023-10-01. Indeksy utworzone przed tą datą obsługują tylko postfiltr, niezależnie od ustawienia trybu filtrowania.

   Przed (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"
   }
   

   Po (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"
   }
   

Te kroki umożliwiają ukończenie migracji do 2023-11-01 stabilnej wersji interfejsu API lub nowszych wersji interfejsu API w wersji zapoznawczej.

Uaktualnianie do wersji 2020-06-30

W tej wersji istnieje jedna zmiana powodująca niezgodność i kilka różnic behawioralnych. Ogólnie dostępne funkcje obejmują:

• Magazyn wiedzy, trwały magazyn wzbogaconej zawartości utworzonej za pomocą zestawów umiejętności utworzonych na potrzeby analizy podrzędnej i przetwarzania za pośrednictwem innych aplikacji. Magazyn wiedzy jest tworzony za pomocą interfejsów API REST usługi Azure AI Search, ale znajduje się w usłudze Azure Storage.

Zmiana powodująca niezgodność

Kod napisany w starszych wersjach interfejsu API przestaje działać na 2020-06-30 i nowszych wersjach, jeśli kod zawiera następującą funkcjonalność:

• Wszystkie Edm.Date literały (data składająca się z roku-miesiąca-dnia, na przykład 2020-12-12) w wyrażeniach filtru muszą być zgodne z formatem Edm.DateTimeOffset : 2020-12-12T00:00:00Z. Ta zmiana była konieczna do obsługi błędnych lub nieoczekiwanych wyników zapytania z powodu różnic w strefie czasowej.

Zmiany zachowania

• Algorytm klasyfikacji BM25 zastępuje poprzedni algorytm klasyfikacji nowszą technologią. Usługi utworzone po 2019 r. automatycznie używają tego algorytmu. W przypadku starszych usług należy ustawić parametry, aby używać nowego algorytmu.

• Uporządkowane wyniki dla wartości null zostały zmienione w tej wersji, a wartości null są wyświetlane jako pierwsze, jeśli sortowanie to asc i ostatnie, jeśli sortowanie to desc. Jeśli napisaliśmy kod do obsługi sposobu sortowania wartości null, należy pamiętać o tej zmianie.

Uaktualnianie do wersji 2019-05-06

Funkcje, które stały się ogólnie dostępne w tej wersji interfejsu API, obejmują:

• Autouzupełnianie to funkcja podpowiedzi, która kończy częściowo wprowadzone wyrażenie.
• Typy złożone zapewniają natywną obsługę danych obiektów strukturalnych w indeksie wyszukiwania.
• Tryby analizowania JsonLines, będące częścią indeksowania obiektów blob platformy Azure, tworzą jeden dokument wyszukiwania dla każdej jednostki JSON, oddzielanej nową linią.
• Wzbogacanie AI zapewnia indeksowanie, które korzysta z silników wzbogacania AI narzędzi Foundry Tools.

Zmiany powodujące niezgodność

Kod napisany we wcześniejszej wersji interfejsu API przestaje działać na 2019-05-06 i późniejszych wersjach, jeśli zawiera następującą funkcjonalność:

1. Właściwość type dla usługi Azure Cosmos DB. W przypadku indeksatorów dla źródła danych Azure Cosmos DB dla interfejsu API NoSQL zmień "type": "documentdb" na "type": "cosmosdb".

2. Jeśli obsługa błędów indeksatora zawiera odwołania do status właściwości, należy ją usunąć. Usunięto stan z odpowiedzi na błąd, ponieważ nie dostarczał przydatnych informacji.

3. W odpowiedzi nie są już zwracane parametry połączenia źródła danych. Od wersji 2019-05-06 i 2019-05-06-Preview interfejsu API, interfejs API źródła danych nie zwraca już ciągów połączeń w odpowiedziach żadnej operacji REST. W poprzednich wersjach interfejsu API w przypadku źródeł danych utworzonych przy użyciu funkcji POST usługa Azure AI Search zwróciła 201, a następnie odpowiedź OData, która zawierała parametry połączenia w postaci zwykłego tekstu.

4. Umiejętność kognitywna rozpoznawania nazwanych jednostek została wycofana. W przypadku wywołania umiejętności rozpoznawania nazw jednostek w kodzie, wywołanie zakończy się niepowodzeniem. Funkcja zamiany to umiejętność rozpoznawania jednostek (V3). Postępuj zgodnie z zaleceniami w temacie Przestarzałe umiejętności , aby przeprowadzić migrację do obsługiwanej umiejętności.

Aktualizacja typów złożonych

Wersja 2019-05-06 interfejsu API dodała formalną obsługę typów złożonych. Jeśli kod zaimplementował poprzednie zalecenia dotyczące równoważności typu złożonego w wersji 2017-11-11-Preview lub 2016-09-01-Preview, istnieją pewne nowe i zmienione limity, poczynając od wersji 2019-05-06, o których należy pamiętać.

• Limity głębokości pól podrzędnych i liczby kolekcji złożonych dla indeksu zostały obniżone. Jeśli utworzono indeksy, które przekraczają te limity przy użyciu wersji zapoznawczej interfejsu API, próba zaktualizowania lub ponownego utworzenia ich przy użyciu wersji 2019-05-06 interfejsu API zakończy się niepowodzeniem. Jeśli znajdziesz się w tej sytuacji, musisz przeprojektować schemat, aby dopasować go do nowych limitów, a następnie ponownie skompilować indeks.

• Istnieje nowy limit rozpoczynający się od wersji 2019-05-06 interfejsu API dla liczby elementów złożonych kolekcji na dokument. Jeśli utworzono indeksy z dokumentami, które przekraczają te limity przy użyciu wersji zapoznawczej interfejsu API-versions, każda próba ponownego indeksowania tych danych przy użyciu interfejsu API-version 2019-05-06 zakończy się niepowodzeniem. Jeśli znajdziesz się w tej sytuacji, musisz zmniejszyć liczbę złożonych elementów kolekcji na dokument przed ponownym indeksowaniem danych.

Aby uzyskać więcej informacji, zobacz Limity usługi dla usługi Azure AI Search.

Jak uaktualnić starą strukturę typu złożonego

Jeśli Twój kod używa złożonych typów z jednej z wcześniejszych wersji zapoznawczych interfejsu API, możesz używać formatu definicji indeksu, który wygląda następująco:

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

Nowszy format przypominający drzewo do definiowania pól indeksu został wprowadzony w wersji 2017-11-11-Previewinterfejsu API . W nowym formacie każde pole złożone ma kolekcję pól, w której są zdefiniowane jego pola podrzędne. W interfejsie API w wersji 2019-05-06 ten nowy format jest używany wyłącznie i próba utworzenia lub zaktualizowania indeksu przy użyciu starego formatu zakończy się niepowodzeniem. Jeśli masz indeksy utworzone przy użyciu starego formatu, musisz użyć wersji 2017-11-11-Preview interfejsu API, aby zaktualizować je do nowego formatu, zanim będzie można nimi zarządzać przy użyciu interfejsu API w wersji 2019-05-06.

Indeksy płaskie można zaktualizować do nowego formatu, wykonując następujące kroki przy użyciu wersji 2017-11-11-Previewinterfejsu API:

1. Wykonaj żądanie GET, aby pobrać indeks. Jeśli jest już w nowym formacie, wszystko jest gotowe.

2. Przetłumacz indeks z formatu płaskiego na nowy format. Musisz napisać kod dla tego zadania, ponieważ w momencie pisania tego tekstu nie ma dostępnego przykładowego kodu.

3. Wykonaj żądanie PUT, aby zaktualizować indeks do nowego formatu. Unikaj zmiany innych szczegółów indeksu, takich jak możliwość wyszukiwania/filtrowanie pól, ponieważ zmiany wpływające na fizyczne wyrażenie istniejącego indeksu nie są dozwolone przez interfejs API indeksu aktualizacji.

Uaktualnienia płaszczyzny sterowania

Dotyczy:2014-07-31-Preview , 2015-02-28i 2015-08-19

Żądanie listQueryKeys GET w starszych wersjach interfejsu API usługi Search Management jest teraz przestarzałe. Zalecamy migrację do najnowszej stabilnej wersji interfejsu listQueryKeysAPI płaszczyzny sterowania, aby używać żądania POST.

1. W istniejącym kodzie zmień api-version parametr na najnowszą wersję (2025-05-01).

2. Zmień ramkę żądania z GET na :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. Jeśli używasz zestawu Azure SDK, zaleca się uaktualnienie do najnowszej wersji.

Następne kroki

Zapoznaj się z dokumentacją referencyjną interfejsu API REST wyszukiwania. Jeśli wystąpią problemy, poproś nas o pomoc w witrynie Stack Overflow lub skontaktuj się z pomocą techniczną.