Uaktualnianie do najnowszego interfejsu API REST w usłudze Azure AI Search

Artykuł
11/19/2024

Ten artykuł umożliwia migrowanie wywołań płaszczyzny danych do nowszych wersji interfejsów API REST wyszukiwania.

2024-07-01 jest najnowszą stabilną wersją.
2024-11-01-preview jest najnowszą wersją interfejsu API w wersji zapoznawczej.

Instrukcje uaktualniania koncentrują się na zmianach kodu, które umożliwiają przechodzenie zmian powodujących niezgodność z poprzednich wersji, tak aby istniejący kod był uruchamiany tak samo jak poprzednio, ale w nowszej wersji interfejsu 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 Przykłady kodu wektorowego i Co nowego.

Zalecamy uaktualnienie wersji interfejsu API z rzędu, pracy z każdą wersją do czasu uzyskania najnowszej wersji.

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.

Uwaga

Dokumentacja referencyjna interfejsu API REST jest teraz wersjonowana. W przypadku zawartości specyficznej dla wersji otwórz stronę referencyjną, a następnie użyj selektora znajdującego się po prawej stronie, powyżej spisu treści, aby wybrać wersję.

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 powodującej niezgodność. Zmiany powodujące niezgodność należy rozwiązać, jeśli obiekty docelowe 2023-07-10-preview kodu dla wektorów, 2020-06-01-preview klasyfikator semantyczny oraz 2019-05-06 przestarzałe umiejętności i obejścia.
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

Przejrzyj informacje o wersji dla każdej wersji interfejsu API.
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 struktury wywołania REST, zobacz Szybki start: korzystanie z interfejsu REST.

Jeśli używasz zestawu Azure SDK, te pakiety są przeznaczone dla określonych wersji interfejsu API REST. Aktualizacje pakietów mogą zbiegać się z aktualizacją interfejsu API REST, ale każdy zestaw SDK jest oparty na własnym harmonogramie wydania, który jest dostarczany niezależnie od wersji interfejsu API REST usługi Azure AI Search. Sprawdź dziennik zmian pakietu SDK, aby ustalić, czy wersja pakietu jest przeznaczona dla najnowszej wersji interfejsu API REST.
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.

Zmiana powodująca niezgodność dla 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 niezgodność, jeśli kod podrzędny 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 zarządzania.
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.

Zmiana powodująca niezgodność dla klasyfikatora semantycznego

Ranga semantyczna jest ogólnie dostępna w systemie 2023-11-01. Poniżej przedstawiono zmiany powodujące niezgodność dla semantycznego rangatora z wcześniejszych wersji:

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. do modeli semantycznych hostowanych przez firmę Microsoft wykonane semantyczne klasyfikatora języka niezależnego od języka, skutecznie likwidując queryLanguage właściwość. W kodzie nie ma żadnych zmian powodujących niezgodność, ale właściwość jest ignorowana.

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

Uaktualnianie do wersji 2024-11-01-preview

2024-11-01-preview ponowne zapisywanie zapytań, umiejętność układu dokumentu, bezklucze rozliczenia na potrzeby przetwarzania umiejętności, tryb analizowania języka Markdown i opcje ponownego pisania dla skompresowanych wektorów.

W przypadku uaktualniania z 2024-09-01-previewprogramu możesz użyć nowych interfejsów API w wersji zapoznawczej bez zmian w istniejącym kodzie.

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

Zamienia na rerankWithOriginalVectorsenableRescoring
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 osadzania tekstu-3, ukierunkowane filtrowanie wektorów dla zapytań hybrydowych, szczegóły podscoreu wektorów na potrzeby debugowania i fragmentowania tokenu dla umiejętności dzielenia tekstu.

W przypadku uaktualniania z 2024-05-01-previewprogramu możesz użyć nowych interfejsów API w wersji zapoznawczej bez zmian w istniejącym kodzie.

Uaktualnianie do wersji 2024-07-01

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

Nie ma żadnych zmian powodujących niezgodność w przypadku uaktualnienia z 2024-05-01-preview do stabilnego. 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 indeks OneLake, obsługę wektorów binarnych i obsługę większej liczby modeli osadzania.

W przypadku uaktualniania z 2024-03-01-previewprogramu umiejętności AzureOpenAIEmbedding wymaga teraz właściwości nazwy i wymiarów modelu.

Wyszukaj bazę kodu pod kątem odwołań azureOpenAIEmbedding .
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-previewprogramu nie ma żadnych zmian powodujących niezgodność. Istnieje jednak jedna różnica między zachowaniem: w przypadku 2023-11-01 i nowszych podglądów vectorFilterMode domyślne zmieniono filtr z postfiltru na wstępnie filtr dla wyrażeń filtru.

Wyszukaj bazę kodu pod kątem vectorFilterMode odwołań.
Jeśli właściwość jest jawnie ustawiona, nie jest wymagana żadna akcja. Jeśli użyto wartości domyślnej, należy pamiętać, że nowe domyślne zachowanie polega na filtrowaniu przed wykonaniem zapytania. Jeśli chcesz filtrować po kwerendzie, jawnie ustaw vectorFilterMode opcję postfiltru, 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ólnie dostępne: semantyczny rangą, indeks wektorowy i obsługa zapytań.

Nie ma żadnych zmian powodujących niezgodność z 2023-10-01-previewelementu , ale istnieje wiele zmian powodujących niezgodność z 2023-07-01-preview na 2023-11-01. Aby uzyskać więcej informacji, zobacz 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ą zapoznawcza, która umożliwia dodanie wbudowanych fragmentów i wektoryzacji danych podczas indeksowania i 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 uaktualnieniu indeksu należy użyć 2024-05-01-preview polecenia lub nowszego, 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 pozycji Migruj wybierz pozycję 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 mapujący 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.

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

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ż zmień 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"
      }
    ]
  }

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 aspektów, ani używać analizatorów, normaliatorów ani 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"
  }

Wywołaj metodę Utwórz lub Zaktualizuj indeks , aby opublikować zmiany.

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 kindelement , 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 filtr postfiltr, niezależnie od sposobu ustawiania 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 przerywa działanie 2020-06-30 i nowsze, jeśli kod zawiera następujące funkcje:

Wszystkie Edm.Date literały (data składająca się z dnia miesiąca, 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 typu, która kończy częściowo określony termin wejściowy.
Typy złożone zapewniają natywną obsługę danych obiektów strukturalnych w indeksie wyszukiwania.
Tryby analizowania JsonLines, część indeksowania obiektów blob platformy Azure, tworzy jeden dokument wyszukiwania dla jednostki JSON oddzielonej nową linią.
Wzbogacanie sztucznej inteligencji zapewnia indeksowanie korzystające z aparatów wzbogacania sztucznej inteligencji usług Azure AI.

Zmiany powodujące niezgodność

Kod napisany we wcześniejszej wersji interfejsu API jest przerywany 2019-05-06 i nowszy, jeśli zawiera on następujące funkcje:

Właściwość type dla usługi Azure Cosmos DB. W przypadku indeksatorów przeznaczonych dla źródła danych interfejsu API NoSQL dla usługi Azure Cosmos DB zmień wartość "type": "documentdb" na "type": "cosmosdb".
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.
W odpowiedzi nie są już zwracane parametry połączenia źródła danych. Od wersji 2019-05-06 interfejsu API i 2019-05-06-Preview nowszych interfejs API źródła danych nie zwraca już parametry połączenia w odpowiedzi na każdą operację 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.
Umiejętność poznawcza rozpoznawania jednostek została wycofana. W przypadku wywołania umiejętności rozpoznawania jednostek nazw 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.

Uaktualnianie 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, których 2019-05-06 należy pamiętać:

Limity głębokości pól podrzędnych i liczby kolekcji złożonych na indeks zostały obniżone. Jeśli utworzono indeksy przekraczające te limity przy użyciu wersji interfejsu API w wersji zapoznawczej, 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 kod używa złożonych typów ze starszymi wersjami interfejsu API w wersji zapoznawczej, może być używany format 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:

Wykonaj żądanie GET, aby pobrać indeks. Jeśli jest już w nowym formacie, wszystko jest gotowe.
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.
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.