Eseguire l'aggiornamento all'API REST più recente in Azure AI Search

Usare questo articolo per eseguire la migrazione alle versioni più recenti delle API REST del servizio di ricerca e alle API REST di gestione della ricerca per le operazioni del piano dati e del piano di controllo .

Di seguito sono riportate le versioni più recenti delle API REST:

Operazioni mirate REST API Stato
Piano di dati 2026-04-01 Stabile
Livello dati 2025-11-01-preview Anteprima
Piano di controllo 2025-05-01 Stabile
Piano di controllo 2026-03-01-preview Anteprima

Le istruzioni di aggiornamento sono incentrate sulle modifiche al codice necessarie per superare i cambiamenti che interrompono la compatibilità con le versioni precedenti, affinché il codice esistente venga eseguito allo stesso modo di prima, ma sulla versione più recente dell'API. Quando il codice è in ordine di lavoro, è possibile decidere se adottare funzionalità più recenti. Per altre informazioni sulle nuove funzionalità, vedere Novità di Azure AI Search.

È consigliabile aggiornare le versioni dell'API in successione, usando ogni versione fino a quando non si arriva alla versione più recente.

2023-07-01-preview è stata la prima API REST per il supporto vettoriale. Non usare questa versione dell'API. È ora deprecato ed è necessario eseguire immediatamente la migrazione alle API REST di anteprima stabili o più recenti.

Nota

La documentazione di riferimento dell'API REST è ora versionata. Per il contenuto specifico della versione, aprire una pagina di riferimento e quindi usare il selettore che si trova sopra il sommario per selezionare la versione.

Quando eseguire l'aggiornamento

Azure AI Search interrompe la compatibilità con le versioni precedenti come ultima risorsa. L'aggiornamento è necessario quando:

  • Il codice fa riferimento a una versione dell'API ritirata o non supportata ed è soggetto a una o più modifiche di rilievo.

  • Il codice ha esito negativo quando le proprietà non riconosciute vengono restituite in una risposta API. Come procedura consigliata, l'applicazione deve ignorare le proprietà che non riconosce.

  • Il codice rende persistenti le richieste API e tenta di inviarle nuovamente alla nuova versione dell'API. Ad esempio, questo problema può verificarsi se l'applicazione rende persistenti i token di continuazione restituiti dall'API di ricerca (per altre informazioni, cercare @search.nextPageParameters nella Guida di riferimento all'API di ricerca).

Come eseguire l'aggiornamento

  1. Se si sta aggiornando una versione del piano dati, esaminare cosa è stato rilasciato nella nuova versione dell'API.

  2. Aggiornare il api-version parametro, specificato nell'intestazione della richiesta, a una versione più recente.

    Nel codice dell'applicazione che effettua chiamate dirette alle API REST cercare tutte le istanze della versione esistente e quindi sostituirla con la nuova versione. Per altre informazioni sulla strutturazione di una chiamata REST, vedere Avvio rapido: Ricerca full-text con REST.

    Se si usa un Azure SDK, ogni pacchetto è destinato a una versione specifica dell'API REST. Per determinare la versione dell'API REST supportata dal pacchetto, esaminare il log delle modifiche. Eseguire l'aggiornamento alla versione più recente del pacchetto per accedere alle funzionalità e ai miglioramenti dell'API più recenti.

  3. Se si sta aggiornando una versione del piano dati, esaminare le modifiche di rilievo documentate in questo articolo e implementare le soluzioni alternative. Iniziare con la versione usata dal codice e risolvere eventuali modifiche di rilievo per ogni versione più recente dell'API fino a quando non si arriva alla versione stabile o di anteprima più recente.

Modifiche di rilievo

Le modifiche di rilievo seguenti si applicano alle operazioni sui dati.

Modifiche significative per il recupero agentico

2026-04-01 è la prima versione stabile dell'API REST per il recupero agentico. Introduce le seguenti modifiche significative a partire da 2025-11-01-preview:

  • La sintesi delle risposte, la pianificazione delle query e il ragionamento configurabile vengono rimossi. Il recupero restituisce solo contenuto estrattivo e fondato.

  • Modifica della forma della richiesta di recupero: messages viene sostituita da intentse diversi parametri vengono rinominati o rimossi.

  • Il filtro delle autorizzazioni a livello di documento per le origini di conoscenza blob e OneLake non è supportato.

Per l'elenco completo delle modifiche a livello di proprietà e dei passaggi di migrazione, vedere Eseguire la migrazione del codice di recupero agentico.

Cambiamenti radicali per gli agenti della conoscenza

Gli agenti di conoscenza sono stati introdotti in 2025-05-01-preview. In 2025-08-01-preview, targetIndexes è stato sostituito con un nuovo oggetto di origine conoscenza, ed defaultMaxDocsForReranker è stato sostituito con altre API. Sono stati introdotti più cambiamenti significativi in 2025-11-01-preview.

Per l'elenco completo delle modifiche a livello di proprietà e dei passaggi di migrazione, vedere Eseguire la migrazione del codice di recupero agentico.

Modifiche di rilievo per il codice client che legge le informazioni di connessione

A partire dal 29 marzo 2024 e applicabile a tutte le API REST supportate:

  • Get Skillset, GET Index e GET Indexer non restituiscono più chiavi o proprietà di connessione in una risposta. Si tratta di una modifica che causa un'interruzione se si dispone di codice downstream che legge chiavi o connessioni (dati sensibili) da una risposta GET.

  • Se è necessario recuperare chiavi API di amministrazione o query per il servizio di ricerca, usare le API REST di gestione della ricerca.

  • Se è necessario recuperare le stringhe di connessione di un'altra risorsa Azure, ad esempio Archiviazione di Azure o Azure Cosmos DB, usare le API di tale risorsa e indicazioni pubblicate per ottenere le informazioni.

Modifiche che interrompono la compatibilità per il ranker semantico

Il ranker semantico è diventato disponibile pubblicamente in 2023-11-01. Queste sono le modifiche sostanziali rispetto alle versioni precedenti:

  • In tutte le versioni dopo 2020-06-01-preview: semanticConfiguration sostituisce searchFields come meccanismo per specificare i campi da usare per la classificazione L2.

  • Per tutte le versioni dell'API, gli aggiornamenti del 14 luglio 2023 ai modelli semantici ospitati da Microsoft hanno reso il classificatore semantico indipendente dal linguaggio, eliminando di fatto la proprietà queryLanguage. Nel codice non è presente alcuna modifica che causa un'interruzione, ma la proprietà viene ignorata.

Vedi Eseguire la migrazione dalla versione di anteprima per trasferire il codice all'uso di semanticConfiguration.

Aggiornamenti del piano dati

Le indicazioni per l'aggiornamento presuppongono l'aggiornamento dalla versione precedente più recente. Se il codice è basato su una versione precedente dell'API, è consigliabile eseguire l'aggiornamento tramite ogni versione successiva per passare alla versione più recente.

Aggiornamento alla versione 2026-04-01

2026-04-01 è la versione più recente dell'API REST stabile. Promuove il recupero autonomo, seleziona le fonti di conoscenza e rende disponibili a tutti diverse competenze e funzionalità.

Prima di eseguire l'aggiornamento, controlla se una delle modifiche di rilievo seguenti 2026-04-01 si applicano al codice:

  • Sei proprietà vengono rimosse dalla definizione della competenza Prompt GenAI: httpMethod, timeout, batchSizedegreeOfParallelism, httpHeaders, e authResourceId. Rimuovere queste proprietà prima di eseguire l'aggiornamento. Le definizioni che includono ancora queste proprietà restituiscono un 400 Bad Request errore.

  • Il recupero tramite agente ora richiede il proprio consenso per la fatturazione. Se attualmente si dispone di semanticSearch=standard, è necessario impostare knowledgeRetrieval=standard esplicitamente prima di eseguire l'aggiornamento. Per ulteriori informazioni, vedere Abilitare o disabilitare la fatturazione agentica.

  • Se il codice di recupero agentico è destinato a 2025-11-01-preview, 2026-04-01 rimuove diverse funzionalità di anteprima e standardizza il recupero intorno all'input, all'output estrattovo e al ragionamento minimo. Per altre informazioni, vedere Eseguire la migrazione del codice di recupero agentico.

Per tutte le altre API esistenti, non sono presenti modifiche di comportamento. È possibile scambiare la nuova versione dell'API e il codice viene eseguito come in precedenza.

Aggiornamento alla versione 2025-11-01-preview

2025-11-01-preview introduce le modifiche di rilievo seguenti al recupero agentico come implementato in 2025-08-01-preview:

  • agents Sostituisce con knowledgebases. Diverse proprietà correlate alle origini delle informazioni sono state spostate dalla definizione della knowledge base e all'azione di recupero.

  • Le proprietà delle origini delle informazioni sono ristrutturate, con l'implementazione di un nuovo oggetto ingestionParameters per le origini delle informazioni che generano una pipeline dell'indicizzatore.

Per l'elenco completo delle modifiche a livello di proprietà e dei passaggi di migrazione, vedere Eseguire la migrazione del codice di recupero agentico.

Per tutte le altre API esistenti, non sono presenti modifiche di comportamento. È possibile scambiare la nuova versione dell'API e il codice viene eseguito come in precedenza.

Aggiornamento al 2025-09-01

2025-09-01 è una versione stabile dell'API REST che aggiunge la disponibilità pubblica per l'indicizzatore OneLake, la funzionalità Layout del documento e altre API.

Non vengono apportate modifiche di rilievo se si esegue l'aggiornamento da 2024-07-01 e non si usano funzionalità di anteprima. Per usare la nuova versione stabile, modificare la versione dell'API e testare il codice.

Eseguire l'aggiornamento alla versione 2025-08-01-preview

2025-08-01-preview introduce le seguenti modifiche di rilievo agli agenti della conoscenza creati tramite 2025-05-01-preview:

  • targetIndexes Sostituisce con knowledgeSources.
  • Rimuove defaultMaxDocsForReranker senza sostituzione.

In caso contrario, non sono presenti modifiche di comportamento nelle API esistenti. È possibile scambiare la nuova versione dell'API e il codice viene eseguito come in precedenza.

Eseguire l'aggiornamento alla versione 2025-05-01-preview

2025-05-01-preview fornisce nuove funzionalità, ma non sono presenti modifiche di comportamento nelle API esistenti. È possibile scambiare la nuova versione dell'API e il codice viene eseguito come in precedenza.

Eseguire l'aggiornamento alla versione 2025-03-01-preview

2025-03-01-preview fornisce nuove funzionalità, ma non sono presenti modifiche di comportamento nelle API esistenti. È possibile scambiare la nuova versione dell'API e il codice viene eseguito come in precedenza.

Aggiornamento alla versione 2024-11-01-preview

2024-11-01-preview riscrittura delle query, abilità "Layout documento", fatturazione senza chiave per l'elaborazione delle abilità, modalità di analisi Markdown e opzioni di rescoring per vettori compressi.

Se si esegue l'aggiornamento da 2024-09-01-preview, è possibile scambiare la nuova versione dell'API e il codice viene eseguito come in precedenza.

Tuttavia, la nuova versione introduce modifiche della sintassi a vectorSearch.compressions:

  • Sostituisce rerankWithOriginalVectors con enableRescoring
  • Passa defaultOversampling a un nuovo oggetto rescoringOptions di proprietà

La compatibilità con le versioni precedenti viene mantenuta a causa di un mapping interno dell'API, ma è consigliabile modificare la sintassi se si adotta la nuova versione di anteprima. Per un confronto della sintassi, vedere Comprimere i vettori usando la quantizzazione scalare o binaria.

Eseguire l'aggiornamento alla versione 2024-09-01-preview

2024-09-01-preview aggiunge la compressione di Matryoshka Representation Learning (MRL) per i modelli text-embedding-3, il filtro vettoriale mirato per le query ibride, i dettagli di sottopunteggio vettoriale per il debug e la suddivisione in blocchi di token per l'abilità Suddivisione del Testo.

Se si esegue l'aggiornamento da 2024-05-01-preview, è possibile scambiare la nuova versione dell'API e il codice viene eseguito come in precedenza.

Aggiornamento alla versione 2024-07-01

2024-07-01 è una versione generale. Le funzionalità di anteprima precedenti sono ora disponibili a livello generale: suddivisione in blocchi e vettorizzazione integrata (competenza suddivisione del testo, competenza AzureOpenAIEmbedding), vettore di query basato su AzureOpenAIEmbedding, compressione vettoriale (quantizzazione scalare, quantizzazione binaria, proprietà archiviata, tipi di dati ristretti).

Se si esegue l'aggiornamento da 2024-05-01-preview a stabile, non vengono apportate modifiche di rilievo. Per usare la nuova versione stabile, modificare la versione dell'API e testare il codice.

Se si esegue l'aggiornamento direttamente da 2023-11-01, vengono apportate modifiche che causano un'interruzione. Seguire i passaggi descritti per ogni anteprima più recente per eseguire la migrazione da 2023-11-01 a 2024-07-01.

Eseguire l'aggiornamento alla versione 2024-05-01-preview

2024-05-01-preview aggiunge un indicizzatore per Microsoft OneLake, vettori binari e altri modelli di incorporamento.

Se si esegue l'aggiornamento da 2024-03-01-preview, la competenza AzureOpenAIEmbedding richiede ora un nome modello e una proprietà di dimensioni.

  1. Cercare i riferimenti azureOpenAIEmbedding nella codebase.

  2. Impostare modelName su "text-embedding-ada-002" e dimensions su "1536".

Eseguire l'aggiornamento alla versione 2024-03-01-preview

2024-03-01-preview aggiunge tipi di dati stretti, quantizzazione scalare e opzioni di archiviazione vettoriali.

Se si esegue l'aggiornamento da 2023-10-01-preview, non vengono apportate modifiche di rilievo. Tuttavia, esiste una differenza di comportamento: per 2023-11-01 e le anteprime più recenti, l'impostazione vectorFilterMode predefinita è cambiata dal filtro postfiltro al prefiltro per le espressioni di filtro.

  1. Cercare riferimenti nella codebase vectorFilterMode .

  2. Se la proprietà è impostata in modo esplicito, non è necessaria alcuna azione. Se si basa sul valore predefinito, il nuovo comportamento predefinito consiste nel filtrare prima dell'esecuzione della query. Se si desidera filtrare post-query, impostare esplicitamente il parametro vectorFilterMode su postfilter per mantenere il vecchio comportamento.

Aggiornamento alla versione 2023-11-01

2023-11-01 è una versione generale. Le precedenti funzionalità in anteprima sono ora generalmente disponibili: classificatore semantico e supporto per i vettori.

Non sono presenti cambiamenti significativi da 2023-10-01-preview, ma sono presenti più cambiamenti significativi da 2023-07-01-preview a 2023-11-01. Per altre informazioni, vedere Eseguire l'aggiornamento dalla versione 2023-07-01-preview.

Per usare la nuova versione stabile, modificare la versione dell'API e testare il codice.

Eseguire l'aggiornamento alla versione 2023-10-01-preview

2023-10-01-preview è stata la prima versione di anteprima per aggiungere la suddivisione in blocchi e la vettorizzazione dei dati predefiniti durante l'indicizzazione e la vettorizzazione delle query predefinite. Supporta anche l'indicizzazione vettoriale e le query della versione precedente.

Se si esegue l'aggiornamento dalla versione precedente, la sezione successiva include i passaggi.

Aggiornamento dalla versione 2023-07-01-preview

Non usare questa versione dell'API. Implementa una sintassi di query vettoriale incompatibile con qualsiasi versione più recente dell'API.

2023-07-01-preview è ora deprecato, quindi non è consigliabile basare il nuovo codice su questa versione, né è consigliabile eseguire l'aggiornamento a questa versione in qualsiasi circostanza. Questa sezione illustra il percorso di migrazione da 2023-07-01-preview a qualsiasi versione più recente dell'API.

Aggiornamento del portale per gli indici vettoriali

Azure portale supporta un percorso di aggiornamento con un clic per gli indici 2023-07-01-preview. Rileva i campi vettoriali e fornisce un pulsante Esegui migrazione .

  • Il percorso di migrazione va da 2023-07-01-preview a 2024-05-01-preview.
  • Gli aggiornamenti sono limitati alle definizioni dei campi vettoriali e alle configurazioni dell'algoritmo di ricerca vettoriale.
  • Gli aggiornamenti sono unidirezionali. Non è possibile invertire l'aggiornamento. Dopo l'aggiornamento dell'indice, è necessario usare 2024-05-01-preview o versione successiva per eseguire query sull'indice.

Non è disponibile alcuna migrazione del portale per l'aggiornamento della sintassi delle query vettoriali. Vedere gli aggiornamenti del codice per le modifiche alla sintassi delle query.

Prima di selezionare Esegui migrazione, selezionare Modifica JSON per esaminare prima lo schema aggiornato. È necessario trovare uno schema conforme alle modifiche descritte nella sezione relativa all'aggiornamento del codice . La migrazione del portale gestisce solo gli indici con una sola configurazione dell'algoritmo di ricerca vettoriale. Crea un profilo predefinito che esegue il mapping all'algoritmo 2023-07-01-preview di ricerca vettoriale. Gli indici con più configurazioni di ricerca vettoriale richiedono la migrazione manuale.

Aggiornamento del codice per indici vettoriali e query

Il supporto per la ricerca vettoriale è stato introdotto in Create or Update Index (2023-07-01-preview).

L'aggiornamento da 2023-07-01-preview a qualsiasi versione stabile o di anteprima più recente richiede:

  • Ridenominazione e ristrutturazione della configurazione del vettore nell'indice
  • Riscrittura delle query vettoriali

Usare le istruzioni riportate in questa sezione per eseguire la migrazione di campi vettoriali, configurazione e query da 2023-07-01-preview.

  1. Chiamare Get Index per recuperare la definizione esistente.

  2. Modificare la configurazione della ricerca vettoriale. 2023-11-01 e versioni successive introducono il concetto di profili vettoriali che raggruppano configurazioni correlate al vettore con un solo nome. Le versioni più recenti rinominano algorithmConfigurations anche in algorithms.

    • Rinominare algorithmConfigurations in algorithms. Si tratta solo di una ridenominazione della matrice. Il contenuto è compatibile con le versioni precedenti. Ciò significa che è possibile usare i parametri di configurazione HNSW esistenti.

    • Aggiungere profiles, assegnando un nome e una configurazione dell'algoritmo per ognuno di essi.

    Prima della migrazione (2023-07-01-preview):

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

    Dopo la migrazione (2023-11-01):

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

  3. Modificare le definizioni dei campi vettoriali sostituendo vectorSearchConfiguration con vectorSearchProfile. Assicurarsi che il nome del profilo venga risolto in una nuova definizione del profilo vettoriale e non nel nome di configurazione dell'algoritmo. Altre proprietà dei campi vettoriali rimangono invariate. Ad esempio, non possono essere filtrabili, ordinabili o facettabili, né possono utilizzare analizzatori, normalizzatori o mappe sinonimiche.

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

    Dopo (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. Chiamare Crea o Aggiorna indice per pubblicare le modifiche.

  5. Modificare Search POST per modificare la sintassi della query. Questa modifica dell'API abilita il supporto per i tipi di query vettoriali polimorfici.

    • Rinominare vectors in vectorQueries.
    • Per ogni query vettoriale, aggiungere kind, impostandolo su vector.
    • Per ogni query vettoriale, rinominare value in vector.
    • Facoltativamente, aggiungere vectorFilterMode se si usano espressioni di filtro. Il valore predefinito è prefiltro per gli indici creati dopo 2023-10-01. Gli indici creati prima di tale data supportano solo il postfiltro, indipendentemente dalla modalità di impostazione del filtro.

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

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

Questi passaggi completano la migrazione alla versione stabile dell'API o alle 2023-11-01 versioni api di anteprima più recenti.

Aggiornamento alla versione 2020-06-30

In questa versione è presente una modifica critica e diverse differenze nel comportamento. Le funzionalità disponibili a livello generale includono:

  • Archivio conoscenze, archiviazione permanente di contenuti arricchiti creati tramite set di competenze, creati per l'analisi downstream e l'elaborazione tramite altre applicazioni. Un archivio conoscenze viene creato tramite Azure AI Search API REST, ma risiede in Archiviazione di Azure.

Modifica che causa un'interruzione

Il codice scritto per le versioni precedenti dell'API si interrompe nelle versioni 2020-06-30 e successive se il codice contiene le seguenti funzionalità:

  • Qualsiasi Edm.Date valore letterale (una data composta da anno-mese-giorno, ad esempio 2020-12-12) nelle espressioni di filtro deve seguire il Edm.DateTimeOffset formato : 2020-12-12T00:00:00Z. Questa modifica è stata necessaria per gestire risultati di query errati o imprevisti a causa di differenze di fuso orario.

Modifiche del comportamento

  • L'algoritmo di classificazione BM25 sostituisce l'algoritmo di classificazione precedente con una tecnologia più recente. I servizi creati dopo il 2019 usano automaticamente questo algoritmo. Per i servizi meno recenti, è necessario impostare i parametri per l'uso del nuovo algoritmo.

  • I risultati ordinati per i valori Null sono stati modificati in questa versione, con valori Null visualizzati per primi se l'ordinamento è asc e l'ultimo se l'ordinamento è desc. Se è stato scritto codice per gestire l'ordinamento dei valori Null, tenere presente questa modifica.

Aggiornamento alla versione 2019-05-06

Le funzionalità rese disponibili a livello generale in questa versione dell'API includono:

Modifiche di rilievo

Il codice scritto contro una versione precedente dell'API si interrompe in 2019-05-06 e versioni successive se contiene le seguenti funzionalità:

  1. Proprietà "Tipo" per Azure Cosmos DB. Per gli indicizzatori destinati a un'origine dati Azure Cosmos DB per NoSQL API, modificare "type": "documentdb" in "type": "cosmosdb".

  2. Se la gestione degli errori dell'indicizzatore include riferimenti alla status proprietà , è necessario rimuoverlo. Abbiamo rimosso lo stato dalla risposta di errore perché non forniva informazioni utili.

  3. Le stringhe di connessione dell'origine dati non vengono più restituite nella risposta. Dalle versioni 2019-05-06 dell'API e 2019-05-06-Preview successive, l'API dell'origine dati non restituisce più le stringhe di connessione nella risposta di qualsiasi operazione REST. Nelle versioni precedenti dell'API, per le origini dati create con POST, Azure AI Search ha restituito 201 seguito dalla risposta OData, che conteneva la stringa di connessione in testo normale.

  4. La funzionalità cognitiva di Riconoscimento delle entità denominate è stata ritirata. Se è stata chiamata la competenza Riconoscimento di entità nominate nel codice, la chiamata fallisce. La funzionalità di sostituzione è Competenza riconoscimento entità (V3). Seguire le indicazioni riportate in Competenze deprecate per eseguire la migrazione a una competenza supportata.

Aggiornamento di tipi complessi

La versione 2019-05-06 dell'API ha aggiunto il supporto formale per i tipi complessi. Se il codice ha implementato raccomandazioni precedenti per l'equivalenza dei tipi complessi nel 2017-11-Preview o 2016-09-01-Preview, sono disponibili alcuni limiti nuovi e modificati a partire dalla versione 2019-05-06 di cui è necessario tenere presente:

  • I limiti relativi alla profondità dei sottocampi e al numero di raccolte complesse per indice sono stati ridotti. Se sono stati creati indici che superano questi limiti usando le versioni api di anteprima, qualsiasi tentativo di aggiornarli o ricrearli usando la versione 2019-05-06 dell'API ha esito negativo. Se ci si trova in questa situazione, è necessario riprogettare lo schema in modo che si adatti ai nuovi limiti e quindi ricompilare l'indice.

  • È previsto un nuovo limite a partire dalla versione 2019-05-06 API per il numero di elementi di raccolte complesse per documento. Se sono stati creati indici con documenti che superano questi limiti usando le versioni api di anteprima, qualsiasi tentativo di reindicizzazione dei dati tramite api-version 2019-05-06 ha esito negativo. Se ci si trova in questa situazione, è necessario ridurre il numero di elementi di raccolta complessi per ogni documento prima di reindicizzare i dati.

Per ulteriori informazioni, consultare i limiti del servizio per Azure AI Search.

Come aggiornare una struttura di tipi complessi esistente

Se il codice usa tipi complessi con una delle versioni precedenti dell'API di anteprima, è possibile usare un formato di definizione dell'indice simile al seguente:

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

Nella versione 2017-11-11-Previewdell'API è stato introdotto un formato simile ad albero più recente per la definizione dei campi di indice. Nel nuovo formato, ogni campo complesso ha una raccolta di campi in cui sono definiti i relativi campi secondari. Nella versione API 2019-05-06 questo nuovo formato viene usato esclusivamente e il tentativo di creare o aggiornare un indice usando il formato precedente avrà esito negativo. Se sono stati creati indici usando il formato precedente, è necessario usare la versione 2017-11-11-Preview dell'API per aggiornarli al nuovo formato prima che possano essere gestiti usando la versione API 2019-05-06.

È possibile aggiornare gli indici flat al nuovo formato con la procedura seguente usando la versione 2017-11-11-Previewdell'API :

  1. Eseguire una richiesta GET per recuperare l'indice. Se è già nel nuovo formato, l'operazione è stata completata.

  2. Convertire l'indice dal formato flat al nuovo formato. È necessario scrivere codice per questa attività perché al momento della stesura di questo articolo non è disponibile codice di esempio.

  3. Eseguire una richiesta PUT per aggiornare l'indice al nuovo formato. Evitare di modificare altri dettagli dell'indice, ad esempio la ricerca/filtrabilità dei campi, perché le modifiche che influiscono sull'espressione fisica dell'indice esistente non sono consentite dall'API Aggiorna indice.

Nota

Non è possibile gestire gli indici creati con il formato "flat" precedente dal portale di Azure. Aggiorna gli indici dalla rappresentazione "piatta" alla rappresentazione "ad albero" a tua convenienza.

Aggiornamenti del piano di controllo

Si applica a:2014-07-31-Preview, 2015-02-28, e 2015-08-19

La richiesta GET nelle versioni precedenti dell'API listQueryKeys di gestione della ricerca è ora deprecata. È consigliabile eseguire la migrazione alla versione più recente dell'API del piano di controllo stabile per usare la listQueryKeys richiesta POST.

  1. Nel codice esistente modificare il api-version parametro con la versione più recente (2025-05-01).

  2. Riframeare la richiesta da GET a 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. Se si usa un Azure SDK, è consigliabile eseguire l'aggiornamento alla versione più recente.

Passaggi successivi

Esaminare la documentazione di riferimento dell'API REST di ricerca. In caso di problemi, chiedere assistenza su Stack Overflow o contattare il supporto tecnico.

Informazioni di riferimento sulle API REST del servizio di ricerca

  • Last updated on