API-Versionsvergleich

Bei den meisten API-Methoden unterscheiden sich die Anforderungsparameter und Antworthauptteile zwischen v1 und v2. Erfahren Sie mehr über die funktional entsprechenden oder alternativen v2-Methoden, die Sie verwenden können, um Aktionen auszuführen, die von der API v1 unterstützt werden.

Die Vergleichsinformationen setzen voraus, dass Sie die neueste Version der API v1 (Version 2019-04-30) verwenden und sie mit der neuesten Version der API v2 (Version 2020-08-30) vergleicht.

Umgebungen

Es gibt kein Konzept einer Umgebung in v2. Die Implementierungsdetails wie Größe und Indexkapazität werden auf der Basis des Serviceplantyps verwaltet. In v2werden Sammlungen in Projekten organisiert. Sie können verschiedene Projekttypen erstellen, um Standardkonfigurationseinstellungen auf die Sammlungen anzuwenden, die Sie den Projekten hinzufügen.

Es gibt keine funktional entsprechenden Methoden in v2 für die v1-Umgebungsmethoden. Die folgende Tabelle zeigt jedoch v2-Methoden, die ähnliche Funktionen wie die entsprechenden v1-Methoden bereitstellen. Die unterstützten Parameter und Antworthauptteile, die für jede Methode zurückgegeben werden, unterscheiden sich ebenfalls.

Details zur Unterstützung der Umgebungs-API
Aktion API der Version 1 (v1) Zugehörige v2-API
Umgebung erstellen POST /v1/environments POST /v2/projects
Umgebungen auflisten GET /v1/environments GET /v2/projects
Umgebungsinformationen abrufen GET /v1/environments/{environment_id} GET /v2/projects/{project_id}
Umgebung aktualisieren PUT /v1/environments/{environment_id} POST /v2/projects/{project_id}
v2 verwendet POST anstelle von PUT.
Umgebung löschen DELETE /v1/environment/{environment_id} DELETE /v2/projects/{project_id}
Felder datensammlungsübergreifend auflisten GET /v1/environments/{environment_id}/fields GET /v2/projects/{project_id}/fields

Konfigurationen

Die v2-API hat keinen Endpunkt, der Konfigurationen zugeordnet ist. Stattdessen werden Konfigurationseinstellungen für Projekte, Sammlungen und Abfragen direkt in der API für diese Objekte angegeben. Nicht alle in v1 verfügbaren Konfigurationsparameter sind in v2verfügbar oder anwendbar.

In v1-Konfigurations-API enthält das JSON-Objekt, das zur Angabe eines Konfigurationsobjekts verwendet wird, verschiedene Parameter, die entweder in anderen Formaten als andere v2-Endpunkte verfügbar sind oder in v2nicht verfügbar sind. In der folgenden Tabelle wird beschrieben, wie zugehörige Parameter in v2gesucht werden.

Sie können die Konvertierung von Dokumenten während des Einpflegeprozesses in v2 nicht wie in v1anpassen.

Details der Konfigurationseinstellungen
Konfigurationsparameter v1 v2-API
"conversions.html": { ... } Nicht verfügbar
"conversions.image_text_recognition": { ... } Über die API nicht verfügbar. Sie können jedoch die optische Zeichenerkennung (OCR) für eine Objektgruppe über die Produktbenutzerschnittstelle aktivieren, um Text aus Bildern zu extrahieren. OCR hat auch andere Vorteile. Wenn beispielsweise eine Seite in einem Dokument nicht verarbeitet werden kann, konvertiert OCR die Seite in ein Bild und scannt es, um sicherzustellen, dass das Dokument erfolgreich hochgeladen wird.
"conversions.json_normalizations": { ... } In die Objektgruppen-API verschoben.
"conversions.pdf": { ... } Nicht verfügbar. Wenn Sie spezielle Parameter zum Extrahieren von Text aus Bildern in PDFs verwendet haben, aktivieren Sie die optische Zeichenerkennung (OCR) über die Produktbenutzerschnittstelle für die Sammlung, die die PDFs enthält.
"conversions.segment": { ... } Nicht programmgesteuert verfügbar. Sie können ein Dokument bei jedem Vorkommen eines SDU-generierten Felds wie subtitle über die Produktbenutzerschnittstelle aufteilen.
Das Objekt segment_metadata mit Informationen zu parent_id, id und total_segments ist in v2nicht verfügbar. Sie können das Feld metadata.parent_document_id verwenden, um das allgemeine übergeordnete Element für viele Dokumentsegmente zu suchen.
"conversions.word": { ... } Nicht verfügbar
"enrichments": { ... } /v2/projects/{project_id}/enrichments, /v2/projects/{project_id}/collections/{collection_id}
Verwenden Sie die Aufbereitungen-API, um vorhandene Aufbereitungen zu untersuchen. Verwenden Sie die API für Sammlungen, um die Aufbereitungen anzuzeigen und zu ändern, die für ein Feld in einer Sammlung aktiviert sind.
Einige Aufbereitungen werden standardmäßig basierend auf dem von Ihnen erstellten Projekttyp auf den Service angewendet. Weitere Informationen finden Sie unter Standardprojekteinstellungen.
Die Version der Entitätsaufbereitung, die in v2 verfügbar ist, enthält nicht das Feld disambiguation, das in v1 die Informationen zur Begriffsklärung für die Entität und die Informationen zum Entitätssubtyp enthält.
Die folgenden Aufbereitungen sind in v2:
-Categories
-Concepts
-Emotion
-Relations
-Semantic roles
-Sentiment of Entities
-Sentiment of Keywords
"normalizations": [ ... ] In die Objektgruppen-API verschoben.
"source": { ... } Nicht verfügbar. Konfigurieren Sie Verbindungen zu externen Datenquellen über die Benutzerschnittstelle. Weitere Informationen finden Sie unter Sammlungen erstellen.

Sammlungen

Details der Objektgruppen-API-Unterstützung
Aktion API der Version 1 (v1) v2-API
Objektgruppe erstellen POST /v1/environments/{environment_id}/collections POST /v2/projects/{project_id}/collections
Die unterstützten Parameter und Antworten unterscheiden sich in den beiden Versionen. Weitere Informationen finden Sie in den Hinweisen zur Sammlung.
Objektgruppen auflisten GET /v1/environments/{environment_id}/collections GET /v2/projects/{project_id}/collections
In v2werden nur die Objektgruppen-ID und der Name jeder Objektgruppe in der Liste zurückgegeben. Sie müssen die Methode Get collection verwenden, um weitere Details zu jeder Sammlung zurückzugeben.
Sammlungsdetails abrufen GET /v1/environments/{environment_id}/collections/{collection_id} GET /v2/projects/{project_id}/collections/{collection_id}
Lesen Sie die Sammlungshinweise.
Objektgruppe aktualisieren PUT /v1/environments/{environment_id}/collections/{collection_id} POST /v2/projects/{project_id}/collections/{collection_id}
Sammlung löschen DELETE /v1/environments/{environment_id}/collections/{collection_id} DELETE /v2/projects/{project_id}/collections/{collection_id}
In v2wird das Feld status nicht in der Antwort zurückgegeben.
Listensammlungsfelder GET /v1/environments/{environment_id}/collections/{collection_id}/fields
v1 listet die Felder nach Sammlung auf.		 GET /v2/projects/{project_id}/fields
v2 listet stattdessen Felder pro Projekt auf. Sie können eine einzelne Objektgruppen-ID mit dem Parameter collection_ids übergeben, um Felder aus einer einzelnen Objektgruppe abzurufen.

Hinweise zur Objektgruppen-API

Die folgende Tabelle zeigt die wichtigen Unterschiede zwischen den Erfassungs-APIs für v1 und v2.

Hinweise zur API für Sammlungen
Methode Anmerkungen
Objektgruppe erstellen Die Antwort v2 enthält nicht die Felder status und configuration_id. Sie können Statusinformationen für ein bestimmtes Dokument mithilfe der Methode Dokumentdetails abrufen abrufen.
Die Objekte disk_usage, training_status und crawl_status sind im Antworthauptteil in v2nicht vorhanden. Das Objekt document_counts ist derzeit nicht im Antworthauptteil in v2 enthalten. Der Trainingsstatus wird in der Antwort der Methode Projekt abrufen zurückgegeben. Die anderen Informationen sind in v2nicht verfügbar. In v2können Sie die Aufbereitungen definieren, die auf die Dokumente in der Sammlung angewendet werden sollen, indem Sie ein optionales enrichments-Objekt angeben.
Sammlungsdetails abrufen Die Antwort v2 enthält nicht die Felder status und configuration_id. Sie können Statusinformationen für ein bestimmtes Dokument mithilfe der Methode Dokumentdetails abrufen abrufen.
Die Objekte document_counts, disk_usage, training_status und crawl_status sind im Antworthauptteil in v2nicht vorhanden. Der Trainingsstatus wird in der Antwort der Methode Projekt abrufen zurückgegeben. Die anderen Informationen sind in v2nicht verfügbar. Sie können beispielsweise die Dokumentanzahl für eine Objektgruppe und den Crawlerstatus für eine Objektgruppe, die eine Verbindung zu einer externen Datenquelle in v2herstellt, nicht abrufen. In v2können Sie Informationen zu den Aufbereitungen abrufen, die auf die Sammlung angewendet werden.
Objektgruppe aktualisieren v2 verwendet POST anstelle von PUT. In v2können Sie die Aufbereitungen aktualisieren, die auf die Dokumente in der Sammlung angewendet werden, indem Sie ein optionales enrichments-Objekt angeben
. Die Antwort v2 enthält nicht die Felder status und configuration_id.

Abfrageänderungen

Die in v1 verfügbare Methode für die programmgesteuerte Konfiguration der Tokenisierung wird in der API v2 nicht unterstützt.

Details der API-Unterstützung für Abfrageänderungen
API der Version 1 (v1) v2-API
API für Tokenisierungswörterbücher Nicht verfügbar.
Erweiterungen v1 API API für Erweiterungen v2
Stoppwörter v1-API Stoppwörter v2-API

Dokumente

Dokumente-API-Unterstützungsdetails
Aktion API der Version 1 (v1) v2-API
Dokumente auflisten Nicht über die API v1 verfügbar GET /v2/projects/{project_id}/collections/{collection_id}/documents
Dokument erstellen POST /v1/environments/{environment_id}/collections/{collection_id}/documents POST /v2/projects/{project_id}/collections/{collection_id}/documents
Im Gegensatz zu v1enthält die v2-Antwort kein Objekt "notices". Sie können jedoch mit der Methode Dokumentdetails abrufen in v2Bemerkungen abrufen.
Aktualisierung eines Dokuments POST /v1/environments/{environment_id}/collections /{collection_id}/documents/{document_id} POST /v2/projects/{project_id}/collections/{collection_id}/documents/{document_id}
Wenn Sie ein aufgeteiltes Dokument aktualisieren, werden alle Dokumentsegmente überschrieben.
Dokumentdetails abrufen GET /v1/environments/{environment_id}/collections /{collection_id}/documents/{document_id} GET /v2/projects/{project_id}/collections/{collection_id}/documents/{document_id}
In v2gibt es kein statusDescription. v2 hat ein children-Objekt mit Informationen zu allen Hinweisen, die den untergeordneten Dokumenten zugeordnet sind, die während der Aufnahme generiert werden.
Dokument löschen DELETE /v1/environments/{environment_id}/collections /{collection_id}/documents/{document_id} DELETE /v2/projects/{project_id}/collections/{collection_id}/documents/{document_id}
Segmente eines hochgeladenen Dokuments können nicht einzeln gelöscht werden. Löschen Sie alle Segmente mit einer DELETE-Anforderung, die die parent_document_id eines Segmentergebnisses enthält.

Mit v2 wird ein angepasster Header namens X-Watson-Discovery-Force eingeführt, der in v1nicht verfügbar ist. Sie müssen den Header einschließen, wenn Sie eine Operation für Daten ausführen, die von mehreren Objektgruppen gemeinsam genutzt werden, um anzugeben, dass Sie die Operation in jeder Objektgruppe ausführen möchten. Wenn Sie den Header nicht einschließen, wird der Fehler 403 zurückgegeben.

Felder aus JSON-Dateien, die einer Sammlung hinzugefügt wurden, werden während der Aufnahme zwischen v1 und v2unterschiedlich konvertiert. Weitere Informationen dazu, wie JSON-Dateien im Index v2 gespeichert werden, finden Sie unter JSON-Dateien.

Abfragen

Dokumente-API-Unterstützungsdetails
Aktion API der Version 1 (v1) v2-API
Objektgruppe abfragen Unterstützt eine GET-oder POST-Anforderung.
GET oder POST /v1/environments/{environment_id}/collections/{collection_id}/query		 Fragt ein Projekt ab. Um eine einzelne Objektgruppe anzugeben, schließen Sie den Parameter {collection_id} ein. Unterstützt nur eine POST-Anforderung.
POST /v2/projects/{project_id}/query
Fragt mehrere Sammlungen ab. GET oder POST /v1/environments/{environment_id}/query POST /v2/projects/{project_id}/query
Systembemerkungen abfragen GET /v1/environments/{environment_id}/collections/{collection_id}/notices GET /v2/projects/{project_id}/collections/{collection_id}/notices
Abfrage mehrerer Sammelsystem-Meldungen GET /v1/environments/{environment_id}/notices GET /v2/projects/{project_id}/notices
Vorschläge für automatische Vervollständigung abrufen /v1/environments/{environment_id}/collections/{collection_id}/autocompletion GET /v2/projects/{project_id}/autocompletion
Siehe die Abfragehinweise.

Einige Abfrageergebniskonfigurationen werden standardmäßig basierend auf dem von Ihnen erstellten Projekttyp auf den Service angewendet. Weitere Informationen finden Sie unter Standardprojekteinstellungen.

Anmerkungen zur Abfrage

  • v2-Abfragen geben Ergebnisse aus allen Sammlungen im Projekt zurück. Um die Abfrage auf die Verwendung bestimmter Objektgruppen innerhalb des Projekts zu beschränken, verwenden Sie den Abfrageparameter collection_ids. Sie können nicht mehrere Sammlungen abfragen, die verschiedenen Projekten mit einer v2-Abfrageanforderung hinzugefügt wurden.

  • v2-Ergebnisse enthalten ein Feld confidence, aber kein Feld score.

    Die Konfidenzbewertung hat die Bewertungsinformationen in v1ersetzt, aber die Bewertung wurde aus Gründen der Abwärtskompatibilität beibehalten. In v2wird nur das Konfidenzfeld zurückgegeben.

  • Verwenden Sie POST-Aufrufe (anstelle von GET-Aufrufen), um Abfragen mit v2zu übergeben.

  • v1-Abfragen akzeptieren viele Parameter. Die Tabelle Vergleich von Abfrageparametern ordnet v1-Parameter v2-Parametern zu.

    Vergleich der Abfrageparameter
    Parameter v1 Parameter v2 Anmerkungen
    Nicht zutreffend Parameter 'collection_ids' Verwenden Sie diesen Parameter in v2, um Objektgruppen-IDs anzugeben.
    Filter Filter Dieselbe Ausdruckssprache.
    Abfrage Abfrage Dieselbe Ausdruckssprache.
    Parameter 'natural_language_query' Parameter 'natural_language_query' Keine Anmerkungen.
    Parameter 'passages' Parameter 'passages' Das Format der Passage wurde geändert und in v2erweitert. Der Parameter passages:true wurde in passages.enable:true geändert. Zusätzlich zu den Optionen count, characters und fields können Sie per_document angeben, das die Dokumente nach Dokumentqualität einstuft und dann die am höchsten eingestuften Passagen pro Dokument zurückgibt. Sie können auch find_answers angeben, um ein Antwortobjekt pro Passage zurückzugeben, das eine verkürzte Antwort auf die Abfrage enthält.
    Parameter 'aggregation' Parameter 'aggregation' Dieselbe Ausdruckssprache.
    Zähler Zähler Keine Anmerkungen.
    Zeitzonenabweichung Zeitzonenabweichung Keine Anmerkungen.
    zurückgeben zurückgeben Keine Anmerkungen.
    sortieren sortieren Keine Anmerkungen.
    hervorheben hervorheben Wenn passages.enabled und passages.per_document true sind, werden Passagen für jedes Dokument anstelle von Hervorhebungen zurückgegeben.
    Rechtschreibvorschläge Rechtschreibvorschläge Keine Anmerkungen.
    deduplizieren Nicht zutreffend Nicht unterstützt in v2.
    Parameter 'similar' Parameter 'similar' Das Format wurde in v2geändert. Der Parameter similar:true wurde in similar.enable:true geändert. Die Parameter document_ids und fields wurden von Zeichenfolgen in Zeichenfolgenarrays geändert. Der Parameter document_ids ist jetzt erforderlich, wenn enabled auf 'true' gesetzt ist.
    systematischer Fehler Nicht zutreffend Nicht unterstützt in v2.

Trainingsdaten

Sie können die v1-API für Trainingsdaten verwenden, um mit zwei zugehörigen Objekten zu arbeiten:

  • Trainierte Abfragen
  • Beispiele zum Trainieren der Abfragen

Diese beiden Objekte haben separate API-Endpunkte in v1. In v2werden die Beispiele, die zum Trainieren jeder Abfrage verwendet werden, zusammen mit der Abfrage bereitgestellt und es wird nur ein Endpunkt für die Arbeit mit den Trainingsdaten verwendet.

Um beispielsweise eine trainierte Abfrage und die zugehörigen Trainingsbeispieldokumente in v2hinzuzufügen, verwenden Sie die Anforderung POST /v2/projects/{project_id}/training_data/queries und übergeben die Abfrage und alle Beispiele in den Nutzdaten eines Aufrufs. Wenn Sie ein Beispiel im Trainingsset in v2aktualisieren möchten, müssen Sie die Abfrage und das geänderte Beispiel (zusammen mit allen anderen Beispielen) an den Aktualisierungsendpunkt von v2 übergeben. In v1verwenden Sie zum Aktualisieren der Beispielinformationen den Aktualisierungsbeispielendpunkt, um nur ein Beispiel zu ändern.

Ein weiterer wichtiger Unterschied zwischen v1 und v2 ist, dass in v1das trainierte Modell einer bestimmten Sammlung zugeordnet ist. In v2wird das trainierte Modell einem Projekt zugeordnet. Sie können die Daten aus mehreren Sammlungen innerhalb eines Projekts verwenden, um ein Relevanzmodell zu trainieren. Wenn Sie Trainingsbeispiele in v2erstellen oder aktualisieren, benötigt die API collection_id für die Sammlung, in der das Dokument gespeichert ist.

Details zur Unterstützung der Trainingsdaten-API
Aktion API der Version 1 (v1) v2-API
Trainingsdaten auflisten GET /v1/environments/{environment_id}/collections/{collection_id}/training_data GET /v2/projects/{project_id}/training_data /queries
Abfrage zu Trainingsdaten hinzufügen POST /v1/environments/{environment_id}/collections/{collection_id}/training_data POST /v2/projects/{project_id}/training_data /queries
Alle Trainingsdaten löschen DELETE /v1/environments/{environment_id}/collections/{collection_id}/training_data DELETE /v2/projects/{project_id}/training_data /queries
Details zu einer Abfrage erhalten GET /v1/environments/{environment_id}/collections/{collection_id}/training_data/{query_id} GET /v2/projects/{project_id}/training_data /queries/{query_id}
Löschen einer Trainingsdatenabfrage DELETE /v1/environments/{environment_id}/collections/{collection_id}/training_data/{query_id} DELETE /v2/projects/{project_id}/training_data /queries/{query_id}
Beispiele für eine Trainingsdatenabfrage auflisten GET /v1/environments/{environment_id}/collections/{collection_id}/training_data/{query_id}/examples GET /v2/projects/{project_id}/training_data /queries/{query_id}
Die Beispiele befinden sich in der Liste, die mit der Abfrage zurückgegeben wird.
Beispiel zur Trainingsdatenabfrage hinzufügen POST /v1/environments/{environment_id}/collections/{collection_id}/training_data/{query_id}/examples POST /v2/projects/{project_id}/training_data /queries/{query_id}
Verwenden Sie die Methode Trainingsabfrage erstellen in v2 und übergeben Sie alle Beispiele, wenn Sie die Abfrage erstellen. Verwenden Sie andernfalls die Update-API.
Beispiel für Trainingsdatenabfrage löschen 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}
Verwenden Sie die Aktualisierungsmethode v2 training_data.
Beschriftung oder Querverweis ändern, z. B. 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}
Verwenden Sie die Aktualisierungsmethode v2 training_data.
Details für ein Trainingsdatenbeispiel abrufen GET /v1/environments/{environment_id}/collections/{collection_id}/training_data/{query_id}/examples/{example_id} Nicht verfügbar. Verwenden Sie den Aufruf zum Lesen aller Beispiele, um alle Beispiele abzurufen, die einer Abfrage zugeordnet sind, und suchen Sie das gewünschte Beispiel in der zurückgegebenen Liste.

Benutzerdaten

Die Benutzerdaten-API ist in v2 und v1identisch.

Unterstützungsdetails für Benutzerdaten-API
Aktion API der Version 1 (v1) v2-API
Löschen DELETE /v1/user_data DELETE /v2/user_data
Ähnlich wie v1. Verwenden Sie customer_id, um die Daten zu löschen, die dieser Kunden-ID zugeordnet sind.

Veranstaltungen und Feedback

Die Ereignis-und Feedback-API v1 (/v1/events) ist in v2nicht verfügbar.

Berechtigungsnachweise

Die API für v1-Berechtigungsnachweise (/v1/environments/{environment_id}/credentials) ist in v2nicht verfügbar. Die Funktion ist über die Produktbenutzerschnittstelle von v2 verfügbar.

Statuscodes

Für fast jede API-Methode unterscheiden sich die Statuscodes, die für v2-Anforderungen zurückgegeben werden, von den Statuscodes, die für v1-Anforderungen zurückgegeben werden.