Aggiungere, aggiornare o eliminare documenti (API REST di Ricerca di intelligenza artificiale di Azure)

È possibile importare documenti di ricerca in un indice specificato usando HTTP POST. Per un aggiornamento di grandi dimensioni, l'invio in batch (fino a 1000 documenti per batch o circa 16 MB per batch) è consigliato e migliorerà significativamente le prestazioni di indicizzazione.

POST https://[service name].search.windows.net/indexes/[index name]/docs/index?api-version=[api-version]   
  Content-Type: application/json   
  api-key: [admin key]  

Per le origini dati di Azure supportate, gli indicizzatori offrono un'alternativa più semplice per l'aggiunta e l'aggiornamento di documenti. Per altre informazioni, vedere Indexer operations (Operazioni dell'indicizzatore).

Parametri dell'URI

Intestazioni richiesta

La tabella seguente descrive le intestazioni della richiesta obbligatorie e facoltative.

Corpo della richiesta

Il corpo della richiesta contiene uno o più documenti da indicizzare. I documenti vengono identificati da una chiave con distinzione tra maiuscole e minuscole univoche. Ogni documento è associato a un'azione: "upload", "delete", "merge" o "mergeOrUpload". Le richieste di caricamento devono includere i dati del documento sotto forma di coppie chiave/valore.

{  
  "value": [  
    {  
      "@search.action": "upload (default) | merge | mergeOrUpload | delete",  
      "key_field_name": "unique_key_of_document", (key/value pair for key field from index schema)  
      "field_name": field_value (key/value pairs matching index schema)  
        ...  
    },  
    ...  
  ]  
}  

Risposta

Codice di stato: 200 viene restituito per una risposta corretta, vale a dire che tutti gli elementi sono stati archiviati in modo permanente e inizieranno a essere indicizzati. L'indicizzazione viene eseguita in background e rende disponibili nuovi documenti ( ovvero ricercabili e ricercabili) pochi secondi dopo il completamento dell'operazione di indicizzazione. Il ritardo specifico dipende dal carico del servizio.

L'indicizzazione riuscita è indicata dalla proprietà status impostata su true per tutti gli elementi, nonché la proprietà statusCode impostata su 201 (per i documenti appena caricati) o 200 (per i documenti uniti o eliminati):

{
  "value": [
    {
      "key": "unique_key_of_new_document",
      "status": true,
      "errorMessage": null,
      "statusCode": 201
    },
    {
      "key": "unique_key_of_merged_document",
      "status": true,
      "errorMessage": null,
      "statusCode": 200
    },
    {
      "key": "unique_key_of_deleted_document",
      "status": true,
      "errorMessage": null,
      "statusCode": 200
    }
  ]
}  

Codice di stato: 207 viene restituito quando almeno un elemento non è stato indicizzato correttamente. Gli elementi che non sono stati indicizzati hanno il campo di stato impostato su false. Le proprietà errorMessage e statusCode indicano il motivo dell'errore di indicizzazione:

{
  "value": [
    {
      "key": "unique_key_of_document_1",
      "status": false,
      "errorMessage": "The search service is too busy to process this document. Please try again later.",
      "statusCode": 503
    },
    {
      "key": "unique_key_of_document_2",
      "status": false,
      "errorMessage": "Document not found.",
      "statusCode": 404
    },
    {
      "key": "unique_key_of_document_3",
      "status": false,
      "errorMessage": "Index is temporarily unavailable because it was updated with the 'allowIndexDowntime' flag set to 'true'. Please try again later.",
      "statusCode": 422
    }
  ]
}  

La proprietà errorMessage indica il motivo dell'errore di indicizzazione, se possibile.

La tabella seguente illustra i vari codici di stato per documento che possono essere restituiti nella risposta. Alcuni codici di stato indicano problemi con la richiesta stessa, mentre altri indicano condizioni di errore temporanee. Per queste ultime è necessario riprovare dopo un breve intervallo di tempo.

Il codice di stato 429 indica che è stata superata la quota del numero di documenti per indice. È necessario creare un nuovo indice o effettuare l'aggiornamento per ottenere limiti di capacità più elevati.

Esempio

Esempio: Caricare due documenti completamente definiti

{
  "value": [
    {          
      "@search.action": "upload",  
      "HotelId": "1",
      "HotelName": "Secret Point Motel",
      "Description": "The hotel is ideally located on the main commercial artery of the city in the heart of New York.",
      "Category": "Boutique",
      "Tags": [ "pool", "air conditioning", "concierge" ],
      "ParkingIncluded": false,
      "LastRenovationDate": "1970-01-18T00:00:00Z",
      "Rating": 3.60,
      "Address": {
        "StreetAddress": "677 5th Ave",
        "City": "New York",
        "StateProvince": "NY",
        "PostalCode": "10022",
        "Country": "USA"
      },
      "Location": {
        "type": "Point",
        "coordinates": [ -73.975403, 40.760586 ]
      },
      "Rooms": [
        {
          "Description": "Budget Room, 1 Queen Bed (Cityside)",
          "Description_fr": "Chambre Économique, 1 grand lit (côté ville)",
          "Type": "Budget Room",
          "BaseRate": 96.99,
          "BedOptions": "1 Queen Bed",
          "SleepsCount": 2,
          "SmokingAllowed": true,
          "Tags": [ "vcr/dvd" ]
        },
        {
          "Description": "Budget Room, 1 King Bed (Mountain View)",
          "Description_fr": "Chambre Économique, 1 très grand lit (Mountain View)",
          "Type": "Budget Room",
          "BaseRate": 80.99,
          "BedOptions": "1 King Bed",
          "SleepsCount": 2,
          "SmokingAllowed": true,
          "Tags": [ "vcr/dvd", "jacuzzi tub" ]
        }
      ]  
    },
    {  
      "@search.action": "upload",  
      "HotelId": "2",
      "HotelName": "Twin Dome Motel",
      "Description": "The hotel is situated in a  nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts.",
      "Description_fr": "L'hôtel est situé dans une place du XIXe siècle, qui a été agrandie et rénovée aux plus hautes normes architecturales pour créer un hôtel moderne, fonctionnel et de première classe dans lequel l'art et les éléments historiques uniques coexistent avec le confort le plus moderne.",
      "Category": "Boutique",
      "Tags": [ "pool", "free wifi", "concierge" ],
      "ParkingIncluded": false,
      "LastRenovationDate": "1979-02-18T00:00:00Z",
      "Rating": 3.60,
      "Address": {
        "StreetAddress": "140 University Town Center Dr",
        "City": "Sarasota",
        "StateProvince": "FL",
        "PostalCode": "34243",
        "Country": "USA"
      },
      "Location": {
        "type": "Point",
        "coordinates": [ -82.452843, 27.384417 ]
      },
      "Rooms": [
        {
          "Description": "Suite, 2 Double Beds (Mountain View)",
          "Description_fr": "Suite, 2 lits doubles (vue sur la montagne)",
          "Type": "Suite",
          "BaseRate": 250.99,
          "BedOptions": "2 Double Beds",
          "SleepsCount": 2,
          "SmokingAllowed": false,
          "Tags": [ "Room Tags" ]
        }
      ]
    }, 
    {  
      "@search.action": "merge",  
      "HotelId": "3",  
      "Rating": 2.39,  
      "Description": "Surprisingly expensive",  
      "LastRenovationDate": null  
    },  
    {  
      "@search.action": "delete",  
      "hotelId": "4"  
    }  
  ]  
}  

Vedi anche

• API REST di Ricerca intelligenza artificiale di Azure
• Codici di stato HTTP (Ricerca intelligenza artificiale di Azure)
• Caricare i dati in un indice di ricerca