Confronto versione API

Per la maggior parte dei metodi API, i parametri di richiesta e il corpo della risposta differiscono tra v1 e v2. Scopri i metodi v2 equivalenti o alternativi che puoi utilizzare per eseguire azioni supportate dall'API v1.

Le informazioni di confronto presumono che stai utilizzando l'ultima versione dell'API v1 (versione 2019-04-30) e la confronta con la versione più recente dell'API v2 (versione 2020-08-30).

Ambienti

Non esiste alcun concetto di un ambiente ** in v2. I dettagli di distribuzione come la dimensione e la capacità dell'indice sono gestiti in base al tipo di piano di servizio. In v2, le raccolte vengono organizzate in progetti. È possibile creare diversi tipi di progetti per applicare le impostazioni di configurazione predefinite alle raccolte che si aggiungono ai progetti.

Non esistono metodi equivalenti in v2 per i metodi di ambiente v1. Tuttavia, la seguente tabella mostra i metodi v2 che servono funzioni simili ai metodi v1 corrispondenti. Anche i parametri supportati e i corpi di risposta restituiti per ciascun metodo differiscono.

Dettagli supporto azione API ambiente
Azione	API v1	API v2 correlate
Crea un ambiente	`POST /v1/environments`	`POST /v2/projects`
Elencare gli ambienti	`GET /v1/environments`	`GET /v2/projects`
Ottieni informazioni sull'ambiente	`GET /v1/environments/{environment_id}`	`GET /v2/projects/{project_id}`
Aggiorna un ambiente	`PUT /v1/environments/{environment_id}`	`POST /v2/projects/{project_id}` v2 utilizza `POST` anziché `PUT`.
Elimina un ambiente	`DELETE /v1/environment/{environment_id}`	`DELETE /v2/projects/{project_id}`
Elenca campi tra le raccolte	`GET /v1/environments/{environment_id}/fields`	`GET /v2/projects/{project_id}/fields`

Configurazioni

L'API v2 non dispone di un endpoint dedicato alle configurazioni. Invece, le impostazioni di configurazione per progetti, raccolte e query vengono specificate direttamente nell'API per tali oggetti. Non tutti i parametri di configurazione disponibili in v1 sono disponibili o applicabili in v2.

Nell'API di configurazione v1, l'oggetto JSON utilizzato per specificare un oggetto di configurazione contiene diversi parametri disponibili in formati diversi da altri endpoint v2 o non disponibili in v2. La seguente tabella descrive come trovare i parametri correlati in v2.

Non puoi modificare la conversione dei documenti durante il processo di inserimento in v2 come in v1.

Dettagli impostazioni di configurazione
parametro di configurazione v1	API v2
`"conversions.html": { ... }`	Non disponibile
`"conversions.image_text_recognition": { ... }`	Non disponibile dall'API. Tuttavia, è possibile abilitare OCR (optical character recognition) per una raccolta dall'interfaccia utente del prodotto per estrarre il testo dalle immagini. Anche l'OCR ha altri vantaggi. Ad esempio, se una pagina in un documento non può essere elaborata, OCR converte la pagina in un'immagine e la scansiona per assicurarsi che il documento sia caricato correttamente.
`"conversions.json_normalizations": { ... }`	Spostato nell'API Collections.
`"conversions.pdf": { ... }`	Non disponibile. Se sono stati utilizzati parametri speciali per estrarre il testo dalle immagini nei PDF, abilitare OCR (optical character recognition) dall'interfaccia utente del prodotto per la raccolta che contiene invece i PDF.
`"conversions.segment": { ... }`	Non disponibile in modo programmatico. È possibile suddividere un documento ad ogni ricorrenza di un campo generato da SDU, ad esempio `subtitle` dall'interfaccia utente del prodotto . L'oggetto `segment_metadata` con informazioni `parent_id`, `id` e `total_segments` non è disponibile in v2. È possibile utilizzare il campo `metadata.parent_document_id` per trovare il parent comune per molti segmenti di documenti.
`"conversions.word": { ... }`	Non disponibile
`"enrichments": { ... }`	`/v2/projects/{project_id}/enrichments`, `/v2/projects/{project_id}/collections/{collection_id}` Utilizza l'API degli arricchimenti per esplorare quelli esistenti. Utilizza l'API di raccolte per vedere e modificare gli arricchimenti abilitati su un campo in una raccolta. Alcuni arricchimenti vengono applicati al servizio per impostazione predefinita in base al tipo di progetto che crei. Per ulteriori dettagli, consultare Impostazioni di progetto predefinite. La versione dell'arricchimento Entities disponibile in v2 non include il campo `disambiguation`, che in v1 contiene le informazioni di disambiguazione per l'entità e include le informazioni del sottotipo dell'entità. I seguenti arricchimenti non sono disponibili in v2: Categorie Concetti Emozione Relazioni Ruoli semantici Sentimento di entità Sentimento di parole chiave
`"normalizations": [ ... ]`	Spostato nell'API Collections.
`"source": { ... }`	Non disponibile. Configurare le connessioni alle origini dati esterne tramite l'interfaccia utente. Per ulteriori informazioni, consultare Creazione di raccolte.

Raccolte

Dettagli supporto API Collezioni
Azione	API v1	API v2
Crea una raccolta	`POST /v1/environments/{environment_id}/collections`	`POST /v2/projects/{project_id}/collections` I parametri e risposte supportati differiscono tra le due versioni. Vedi le note della raccolta.
Elenca raccolte	`GET /v1/environments/{environment_id}/collections`	`GET /v2/projects/{project_id}/collections` In v2, nell'elenco vengono restituiti solo l'ID raccolta e il nome di ogni raccolta. Devi utilizzare il metodo Get collection per restituire ulteriori dettagli su ogni raccolta.
Richiama dettagli raccolta	`GET /v1/environments/{environment_id}/collections/{collection_id}`	`GET /v2/projects/{project_id}/collections/{collection_id}` Consultare le note della raccolta.
Aggiorna una raccolta	`PUT /v1/environments/{environment_id}/collections/{collection_id}`	`POST /v2/projects/{project_id}/collections/{collection_id}`
Elimina una raccolta	`DELETE /v1/environments/{environment_id}/collections/{collection_id}`	`DELETE /v2/projects/{project_id}/collections/{collection_id}` In v2, il campo `status` non viene restituito nella risposta.
Elenca campi di raccolta	GET /v1/environments/{environment_id}/collections/{collection_id}/fields v1 elenca i campi per raccolta.	GET /v2/projects/{project_id}/fields v2 elenca invece i campi per progetto. È possibile passare un singolo ID raccolta con il parametro `collection_ids` per ottenere i campi da una sola raccolta.

Note API delle raccolte

La seguente tabella mostra le importanti differenze tra le API di raccolta v1 e v2.

Note API Collezioni
Metodo	Note
Crea una raccolta	La risposta v2 non include i campi `status` e `configuration_id`. È possibile ottenere le informazioni sullo stato di un documento specifico utilizzando il metodo Richiama dettagli documento. Gli oggetti `disk_usage`, `training_status` e `crawl_status` non sono presenti nel corpo della risposta in v2. L'oggetto `document_counts` non è attualmente presente nel corpo della risposta in v2. Lo stato di addestramento viene restituito nella risposta del metodo Get project. Le altre informazioni non sono disponibili in v2. In v2, puoi definire gli arricchimenti da applicare ai documenti nella raccolta specificando un oggetto `enrichments` facoltativo.
Richiama dettagli raccolta	La risposta v2 non include i campi `status` e `configuration_id`. È possibile ottenere le informazioni sullo stato di un documento specifico utilizzando il metodo Richiama dettagli documento. Gli oggetti `document_counts`, `disk_usage`, `training_status` e `crawl_status` non sono presenti nel corpo della risposta in v2. Lo stato di addestramento viene restituito nella risposta del metodo Get project. Le altre informazioni non sono disponibili in v2. Ad esempio, non è possibile ottenere il numero di documenti per una raccolta e non è possibile ottenere lo stato della ricerca per indicizzazione per una raccolta che si connette ad una origine dati esterna in v2. In v2, puoi ottenere informazioni sugli arricchimenti applicati alla raccolta.
Aggiorna una raccolta	v2 utilizza `POST` invece di `PUT`. In v2, puoi aggiornare gli arricchimenti applicati ai documenti nella raccolta specificando un oggetto `enrichments` facoltativo. La risposta v2 non include i campi `status` e `configuration_id`.

Modifiche query

Il metodo disponibile in v1 per configurare la tokenizzazione in modo programmatico non è supportato nell'API v2.

Dettagli supporto API di modifiche query
API v1	API v2
API del dizionario di token	Non disponibile.
Espansioni v1 API	Espansioni v2 API
API v1 parole non significative	Stopwords v2 API

Documenti

Dettagli supporto API documenti
Azione	API v1	API v2
Elenca documenti	Non disponibile dall'API v1	GET /v2/projects/{project_id}/collections/{collection_id}/documents
Creare un documento	`POST /v1/environments/{environment_id}/collections/{collection_id}/documents`	`POST /v2/projects/{project_id}/collections/{collection_id}/documents` A differenza di v1, la risposta v2 non include un oggetto avvisi. Tuttavia, puoi ottenere le informazioni particolari utilizzando il metodo Get document details in v2.
Aggiornare un documento	`POST /v1/environments/{environment_id}/collections /{collection_id}/documents/{document_id}`	`POST /v2/projects/{project_id}/collections/{collection_id}/documents/{document_id}` Quando si aggiorna un documento che è stato suddiviso, tutti i segmenti del documento vengono sovrascritti.
Ottieni dettagli documento	`GET /v1/environments/{environment_id}/collections /{collection_id}/documents/{document_id}`	GET /v2/projects/{project_id}/collections/{collection_id}/documents/{document_id} In v2, non vi è alcun oggetto `statusDescription`. v2 ha un oggetto `children` con informazioni su eventuali avvisi associati ai documenti secondari generati durante l'inserimento.
Eliminare un documento	`DELETE /v1/environments/{environment_id}/collections /{collection_id}/documents/{document_id}`	`DELETE /v2/projects/{project_id}/collections/{collection_id}/documents/{document_id}` Impossibile eliminare singolarmente i segmenti di un documento caricato. Eliminare tutti i segmenti con una richiesta DELETE che include il risultato parent_document_id di un segmento.

v2 introduce un'intestazione personalizzata denominata X-Watson-Discovery-Force che non è disponibile in v1. È necessario includere l'intestazione quando si esegue un'operazione sui dati condivisi tra molte raccolte per indicare che si desidera eseguire l'operazione in ciascuna raccolta. Se non si include l'intestazione, viene restituito un errore 403.

I campi dei file JSON aggiunti a una raccolta vengono convertiti in modo diverso durante l'inserimento tra v1 e v2. Per ulteriori informazioni su come i file JSON vengono archiviati nell'indice v2, consulta File JSON.

Query

Dettagli supporto API documenti
Azione	API v1	API v2
Interrogare una raccolta	Supporta una richiesta GET o POST. GET o POST /v1/environments/{environment_id}/collections/{collection_id}/query	Interroga un progetto. Per specificare una singola raccolta, includere il parametro {collection_id}. Supporta solo una richiesta POST. POST /v2/projects/{project_id}/query
Esegui una query di più raccolte	GET o POST /v1/environments/{environment_id}/query	POST /v2/projects/{project_id}/query
Interrogare gli avvisi di sistema	GET /v1/environments/{environment_id}/collections/{collection_id}/notice	GET /v2/projects/{project_id}/collections/{collection_id}/notice
Interrogazione di più avvisi del sistema di raccolta	GET /v1/environments/{environment_id}/notices	GET /v2/projects/{project_id}/notice
Ottieni suggerimenti di completamento automatico	/v1/environments/{environment_id}/collections/{collection_id}/completamento automatico	GET /v2/projects/{project_id}/autocompletion Consultare le note sulla query.

Alcune configurazioni dei risultati della query vengono applicate al servizio per impostazione predefinita in base al tipo di progetto creato. Per ulteriori dettagli, consultare Impostazioni del progetto predefinite.

Note query

Le query v2 restituiscono risultati da tutte le raccolte nel progetto. Per limitare la query ad utilizzare solo determinate raccolte all'interno del progetto, utilizzare il parametro di query collection_ids. Non è possibile interrogare più raccolte che vengono aggiunte a progetti differenti con una richiesta di query v2.
I risultati di v2 includono un campo confidence, ma non un campo score.

Il punteggio di affidabilità ha sostituito le informazioni sul punteggio in v1, ma il punteggio è stato mantenuto per la compatibilità con le versioni precedenti. In v2, viene restituito solo il campo di confidenza.
Utilizza le chiamate POST (invece delle chiamate GET) per inoltrare le interrogazioni con v2.

Le query v1 accettano molti parametri. La tabella Confronto parametri query associa i parametri v1 ai parametri v2.

Confronto parametri di query
parametro v1	parametro v2	Note
N/D	collection_ids	Utilizzare questo parametro in v2 per specificare gli ID raccolta.
filtro	filtro	Stesso linguaggio di espressione.
query	query	Stesso linguaggio di espressione.
natural_language_query	natural_language_query	Nessuna nota.
passages	passages	Il formato del passaggio è stato modificato ed è stato migliorato in v2. Il parametro `passages:true` è stato modificato in `passages.enable:true`. Oltre alle opzioni `count`, `characters` e `fields`, è possibile specificare `per_document`, che classifica i documenti in base alla qualità del documento e restituisce i passaggi più classificati per documento. È anche possibile specificare `find_answers` per restituire un oggetto risposta per passaggio, che contiene una risposta succinta alla query.
aggregazione	aggregazione	Stesso linguaggio di espressione.
conteggio	conteggio	Nessuna nota.
scostamento	scostamento	Nessuna nota.
restituire	restituire	Nessuna nota.
ordinamento	ordinamento	Nessuna nota.
evidenziare	evidenziare	Se `passages.enabled` e `passages.per_document` sono `true`, i passaggi vengono restituiti per ogni documento invece che per le evidenziazioni.
suggerimenti ortografico	suggerimenti ortografico	Nessuna nota.
deduplicare	N/D	Non supportato in v2.
similar	similar	Il formato è stato modificato in v2. Il parametro `similar:true` è stato modificato in `similar.enable:true`. I parametri `document_ids` e `fields` sono cambiati da stringhe a array di stringhe. Il parametro `document_ids` ora è obbligatorio se `enabled` è true.
bias	N/D	Non supportato in v2.

Dati di addestramento

Puoi utilizzare l'API dei dati di addestramento v1 per gestire due oggetti correlati:

query formate
esempi utilizzati per preparare le query

Questi due oggetti hanno endpoint API separati in v1. In v2, gli esempi utilizzati per preparare ciascuna query vengono forniti insieme alla query e solo un endpoint viene utilizzato per gestire i dati di addestramento.

Ad esempio, per aggiungere una query addestrata e i relativi documenti di esempio di addestramento in v2, utilizzi la richiesta POST /v2/projects/{project_id}/training_data/queries e passi la query e tutti gli esempi nel payload di una chiamata. Allo stesso modo, se desideri aggiornare un esempio nella serie di addestramento in v2, devi passare la query e l'esempio modificato (insieme a tutti gli altri esempi) all'endpoint di aggiornamento v2. In v1, per aggiornare informazioni di esempio, si utilizza l'endpoint di esempio di aggiornamento per modificare solo un esempio.

Un'altra differenza importante tra v1 e v2 è che in v1, il modello sottoposto a training è associato a una particolare raccolta. In v2, il modello sottoposto a training è associato ad un progetto. Puoi utilizzare i dati da più raccolte all'interno di un progetto per addestrare un modello di rilevanza. Quando crei o aggiorni gli esempi di formazione in v2, l'API richiede collection_id per la raccolta in cui è memorizzato il documento.

Dettagli supporto API dati di formazione
Azione	API v1	API v2
Elenca dati di addestramento	`GET /v1/environments/{environment_id}/collections/{collection_id}/training_data`	`GET /v2/projects/{project_id}/training_data /queries`
Aggiungere una query ai dati di addestramento	`POST /v1/environments/{environment_id}/collections/{collection_id}/training_data`	`POST /v2/projects/{project_id}/training_data /queries`
Elimina tutti i dati di addestramento	`DELETE /v1/environments/{environment_id}/collections/{collection_id}/training_data`	`DELETE /v2/projects/{project_id}/training_data /queries`
Ottenere dettagli su una query	`GET /v1/environments/{environment_id}/collections/{collection_id}/training_data/{query_id}`	`GET /v2/projects/{project_id}/training_data /queries/{query_id}`
Cancellare una query di dati di addestramento	`DELETE /v1/environments/{environment_id}/collections/{collection_id}/training_data/{query_id}`	`DELETE /v2/projects/{project_id}/training_data /queries/{query_id}`
Elenco di esempi per una query di dati di addestramento	`GET /v1/environments/{environment_id}/collections/{collection_id}/training_data/{query_id}/examples`	`GET /v2/projects/{project_id}/training_data /queries/{query_id}` Gli esempi si trovano nell'elenco restituito con la query.
Aggiungere un esempio alla query dei dati di addestramento	`POST /v1/environments/{environment_id}/collections/{collection_id}/training_data/{query_id}/examples`	`POST /v2/projects/{project_id}/training_data /queries/{query_id}` Utilizza il metodo Create training query in v2 e passa tutti gli esempi quando crei la query. Altrimenti, utilizzare l'API di aggiornamento.
Esempio di cancellazione per l'interrogazione dei dati di addestramento	`DELETE /v1/environments/{environment_id}/collections/{collection_id}/training_data/{query_id}/examples/{example_id}`	`POST /v2/projects/{project_id}/training_data/ queries/{query_id}` Utilizzare il metodo v2 training_data update.
Modificare l'etichetta o il riferimento incrociato, ad esempio	`PUT /v1/environments/{environment_id}/collections/{collection_id}/training_data/{query_id}/examples/{example_id}`	`POST /v2/projects/{project_id}/training_data/ queries/{query_id}` Utilizzare il metodo v2 training_data update.
Ottenere i dettagli di un esempio di dati di addestramento	`GET /v1/environments/{environment_id}/collections/{collection_id}/training_data/{query_id}/examples/{example_id}`	Non disponibile. Utilizzare la chiamata Leggi tutti gli esempi per ottenere tutti gli esempi associati a una query e trovare l'esempio necessario nell'elenco restituito.

Dati utente

L'API dei dati utente è la stessa in v2 e v1.

Dettagli supporto API dati utente
Azione	API v1	API v2
Elimina	`DELETE /v1/user_data`	`DELETE /v2/user_data` Simile a v1. Utilizzare `customer_id` per eliminare i dati associati a tale ID cliente.

Eventi e feedback

L'API di feedback e gli eventi v1 (/v1/events) non è disponibile in v2.

Credenziali

L'API delle credenziali v1 (/v1/environments/{environment_id}/credentials) non è disponibile in v2. La funzionalità è disponibile dall'interfaccia utente del prodotto v2.

Codici di stato

Per quasi tutti il metodo API, i codici di stato restituiti per richieste v2 sono diversi dai codici di stato restituiti per le richieste v1.