Comparaison des versions d'API

Pour la plupart des méthodes d'API, les paramètres de demande et les corps de réponse diffèrent entre v1 et v2. Découvrez les méthodes v2 équivalentes ou alternatives que vous pouvez utiliser pour effectuer des actions prises en charge par l'API v1.

Les informations de comparaison supposent que vous utilisez la dernière version de l'API v1 (version 2019-04-30) et que vous la compare à la dernière version de l'API v2 (version 2020-08-30).

Environnements

Il n'existe aucun concept d'environnement ** dans v2. Les détails de déploiement, tels que la taille et la capacité d'index, sont gérés en fonction du type de plan de service. Dans v2, les collections sont organisées en projets. Vous pouvez créer différents types de projet pour appliquer les paramètres de configuration par défaut aux collections que vous ajoutez aux projets.

Il n'existe pas de méthodes équivalentes dans v2 pour les méthodes d'environnement v1. Toutefois, le tableau suivant présente les méthodes v2 qui servent des fonctions similaires aux méthodes v1 correspondantes. Les paramètres pris en charge et les corps de réponse renvoyés pour chaque méthode diffèrent également.

Détails de la prise en charge des actions d'API d'environnement
Opération API v1 API v2 associée
Créer un environnement POST /v1/environments POST /v2/projects
Répertorier les environnements GET /v1/environments GET /v2/projects
Obtenir les informations d'environnement GET /v1/environments/{environment_id} GET /v2/projects/{project_id}
Mise à jour d'un environnement PUT /v1/environments/{environment_id} POST /v2/projects/{project_id}
v2 utilise POST à la place de PUT.
Supprimer un environnement DELETE /v1/environment/{environment_id} DELETE /v2/projects/{project_id}
Zones de liste dans les collections GET /v1/environments/{environment_id}/fields GET /v2/projects/{project_id}/fields

Configurations

L'API v2 ne possède pas de noeud final dédié aux configurations. A la place, les paramètres de configuration des projets, des collections et des requêtes sont spécifiés directement dans l'API pour ces objets. Tous les paramètres de configuration disponibles dans v1 ne sont pas disponibles ou applicables dans v2.

Dans l'API de configurationv1, l'objet JSON qui est utilisé pour spécifier un objet de configuration contient plusieurs paramètres qui sont disponibles dans des formats différents à partir d'autres noeuds finaux v2 ou qui ne sont pas disponibles dans v2. Le tableau suivant décrit comment rechercher des paramètres associés dans v2.

Vous ne pouvez pas personnaliser la conversion des documents pendant le processus d'ingestion dans v2 comme vous le pouvez dans v1.

Détails des paramètres de configuration
Paramètre de configuration v1 API v2
"conversions.html": { ... } Non disponible
"conversions.image_text_recognition": { ... } Non disponible à partir de l'API. Toutefois, vous pouvez activer la reconnaissance optique des caractères (OCR) pour une collection à partir de l'interface utilisateur du produit afin d'extraire du texte des images. Le RCO a également d'autres avantages. Par exemple, si une page d'un document ne peut pas être traitée, la reconnaissance optique des caractères convertit la page en image et la scanne pour s'assurer que le téléchargement du document a abouti.
"conversions.json_normalizations": { ... } Déplacé vers l'API Collections.
"conversions.pdf": { ... } Non disponible. Si vous avez utilisé des paramètres spéciaux pour extraire du texte d'images dans des fichiers PDF, activez la reconnaissance optique des caractères (OCR) à partir de l'interface utilisateur du produit pour la collection qui contient les fichiers PDF à la place.
"conversions.segment": { ... } Non disponible à l'aide d'un programme. Vous pouvez fractionner un document à chaque occurrence d'une zone générée par SDU, telle que subtitle, à partir de l'interface utilisateur du produit.
L'objet segment_metadata avec les informations parent_id, id et total_segments n'est pas disponible dans v2. Vous pouvez utiliser la zone metadata.parent_document_id pour rechercher le parent commun pour de nombreux segments de document.
"conversions.word": { ... } Non disponible
"enrichments": { ... } /v2/projects/{project_id}/enrichments, /v2/projects/{project_id}/collections/{collection_id}
Utilisez l'API d'enrichissement pour explorer les enrichissements existants. Utilisez l'API collections pour voir et modifier les enrichissements qui sont activés sur une zone dans une collection.
Certains enrichissements sont appliqués au service par défaut en fonction du type de projet que vous créez. Pour plus de détails, voir Paramètres de projet par défaut.
La version de l'enrichissement Entities disponible dans v2 n'inclut pas la zone disambiguation, qui dans v1 contient les informations de désambiguïsation de l'entité et inclut les informations de sous-type d'entité.
Les enrichissements suivants ne sont pas disponibles dans v2:
-Categories
-Concepts
-Emotion
-Relations
-Rôles sémantiques
-Sentiment d'entités
-Sentiment de mots clés
"normalizations": [ ... ] Déplacé vers l'API Collections.
"source": { ... } Non disponible. Configurez les connexions aux sources de données externes via l'interface utilisateur. Pour plus d'informations, voir Création de collections.

Collections

Détails de la prise en charge de l'API Collections
Opération API v1 API v2
Créer une collection POST /v1/environments/{environment_id}/collections POST /v2/projects/{project_id}/collections
Les paramètres et les réponses pris en charge diffèrent entre les deux versions. Voir les remarques sur les collections.
Répertorier les collections GET /v1/environments/{environment_id}/collections GET /v2/projects/{project_id}/collections
Dans v2, seuls l'ID et le nom de chaque collection sont renvoyés dans la liste. Vous devez utiliser la méthode Get collection pour renvoyer plus de détails sur chaque collection.
Obtenir les détails de la collection GET /v1/environments/{environment_id}/collections/{collection_id} GET /v2/projects/{project_id}/collections/{collection_id}
Voir les remarques sur les collections.
Mise à jour d'une collection PUT /v1/environments/{environment_id}/collections/{collection_id} POST /v2/projects/{project_id}/collections/{collection_id}
Supprimer une collection DELETE /v1/environments/{environment_id}/collections/{collection_id} DELETE /v2/projects/{project_id}/collections/{collection_id}
Dans v2, la zone status n'est pas renvoyée dans la réponse.
Liste des zones de collection GET /v1/environments/{environment_id}/collections/{collection_id}/fields
v1 répertorie les zones par collection.		 GET /v2/projects/{project_id}/fields
v2 répertorie les zones par projet à la place. Vous pouvez transmettre un ID de collection unique avec le paramètre collection_ids pour obtenir les zones d'une collection unique.

Remarques sur l'API Collections

Le tableau suivant présente les différences importantes entre les API de collection v1 et v2.

Remarques sur l'API Collections
Méthode Remarques
Créer une collection La réponse v2 n'inclut pas les zones status et configuration_id. Vous pouvez obtenir des informations de statut pour un document spécifique à l'aide de la méthode Obtenir les détails du document.
Les objets disk_usage, training_status et crawl_status ne sont pas présents dans le corps de réponse dans v2. L'objet document_counts n'est actuellement pas présent dans le corps de la réponse dans v2. Le statut d'entraînement est renvoyé dans la réponse de la méthode Obtenir le projet. Les autres informations ne sont pas disponibles dans v2. Dans v2, vous pouvez définir les enrichissements à appliquer aux documents de la collection en spécifiant un objet enrichments facultatif.
Obtenir les détails de la collection La réponse v2 n'inclut pas les zones status et configuration_id. Vous pouvez obtenir des informations de statut pour un document spécifique à l'aide de la méthode Obtenir les détails du document.
Les objets document_counts, disk_usage, training_status et crawl_status ne sont pas présents dans le corps de réponse dans v2. Le statut d'entraînement est renvoyé dans la réponse de la méthode Obtenir le projet. Les autres informations ne sont pas disponibles dans v2. Par exemple, vous ne pouvez pas obtenir le nombre de documents d'une collection ni le statut d'exploration d'une collection qui se connecte à une source de données externe dans v2. Dans v2, vous pouvez obtenir des informations sur les enrichissements appliqués à la collection.
Mise à jour d'une collection v2 utilise POST à la place de PUT. Dans v2, vous pouvez mettre à jour les enrichissements appliqués aux documents de la collection en spécifiant un objet enrichments facultatif.
La réponse v2 n'inclut pas les zones status et configuration_id.

Modifications de requête

La méthode disponible dans v1 pour configurer le marquage sémantique à l'aide d'un programme n'est pas prise en charge dans l'API v2.

Détails de la prise en charge de l'API de modifications de requête
API v1 API v2
API de dictionnaire de marquage sémantique Non disponible.
API d'extensions v1 API d'extensions v2
Stopwords v1 API Stopwords v2 API

Documents

Détails de la prise en charge de l'API de documents
Opération API v1 API v2
Répertorier les documents Non disponible à partir de l'API v1 GET /v2/projects/{project_id}/collections/{collection_id}/documents
Créer un document POST /v1/environments/{environment_id}/collections/{collection_id}/documents POST /v2/projects/{project_id}/collections/{collection_id}/documents
Contrairement à v1, la réponse v2 n'inclut pas d'objet notices. Toutefois, vous pouvez obtenir des informations sur les avis à l'aide de la méthode Obtenir les détails du document dans v2.
Mettre à jour un document POST /v1/environments/{environment_id}/collections /{collection_id}/documents/{document_id} POST /v2/projects/{project_id}/collections/{collection_id}/documents/{document_id}
Lorsque vous mettez à jour un document qui a été fractionné, tous les segments de document sont écrasés.
Obtenir les détails du document GET /v1/environments/{environment_id}/collections /{collection_id}/documents/{document_id} GET /v2/projects/{project_id}/collections/{collection_id}/documents/{document_id}
Dans v2, il n'existe pas d'objet statusDescription. v2 possède un objet children contenant des informations sur les avis associés aux documents enfant générés lors de l'ingestion.
Suppression d'un document DELETE /v1/environments/{environment_id}/collections /{collection_id}/documents/{document_id} DELETE /v2/projects/{project_id}/collections/{collection_id}/documents/{document_id}
Les segments d'un document téléchargé ne peuvent pas être supprimés individuellement. Supprimez tous les segments avec une demande DELETE qui inclut l'ID parent_document_id d'un résultat de segment.

v2 introduit un en-tête personnalisé nommé X-Watson-Discovery-Force qui n'est pas disponible dans v1. Vous devez inclure l'en-tête lorsque vous effectuez une opération sur des données qui sont partagées entre plusieurs collections pour indiquer que vous souhaitez effectuer l'opération dans chaque collection. Si vous n'incluez pas l'en-tête, une erreur 403 est renvoyée.

Les zones des fichiers JSON qui sont ajoutés à une collection sont converties différemment lors de l'ingestion entre v1 et v2. Pour plus d'informations sur la façon dont les fichiers JSON sont stockés dans l'index v2, voir Fichiers JSON.

Requêtes

Détails de la prise en charge de l'API de documents
Opération API v1 API v2
Interrogation d'une collection Prend en charge une demande GET ou POST.
GET ou POST /v1/environments/{environment_id}/collections/{collection_id}/query		 Interroge un projet. Pour spécifier une collection unique, incluez le paramètre {collection_id}. Prend en charge une demande POST uniquement.
POST /v2/projects/{project_id}/query
Faire une requête sur plusieurs collections GET ou POST /v1/environments/{environment_id}/query POST /v2/projects/{project_id}/query
Remarques sur le système de requête GET /v1/environments/{environment_id}/collections/{collection_id}/notices GET /v2/projects/{project_id}/collections/{collection_id}/notices
Interroger les avis de systèmes de collecte multiples GET /v1/environments/{environment_id}/notices GET /v2/projects/{project_id}/notices
Obtenir des suggestions de saisie semi-automatique /v1/environments/{environment_id}/collections/{collection_id}/autocomplete GET /v2/projects/{project_id}/autocomplete
Voir les remarques sur les requêtes.

Certaines configurations de résultat de requête sont appliquées au service par défaut en fonction du type de projet que vous créez. Pour plus de détails, voir Paramètres de projet par défaut.

Remarques sur les requêtes

  • Les requêtes v2 renvoient les résultats de toutes les collections du projet. Pour limiter la requête à l'utilisation de certaines collections dans le projet, utilisez le paramètre de requête collection_ids. Vous ne pouvez pas interroger plusieurs collections qui sont ajoutées à différents projets avec une demande de requête v2.

  • Les résultats v2 incluent une zone confidence, mais pas une zone score.

    La cote de confiance a remplacé les informations de score dans v1, mais le score a été conservé à des fins de compatibilité avec les versions antérieures. Dans v2, seul le champ de confiance est renvoyé.

  • Utilisez les appels POST (au lieu des appels GET) pour soumettre des requêtes avec v2.

  • Les requêtes v1 acceptent de nombreux paramètres. Le tableau Comparaison des paramètres de requête mappe les paramètres v1 aux paramètres v2.

    Comparaison des paramètres de requête
    Paramètre v1 Paramètre v2 Remarques
    N/A Paramètre collection_ids Utilisez ce paramètre dans v2 pour spécifier les ID de collection.
    filter filter Même langage d'expression.
    requête requête Même langage d'expression.
    natural_language_query natural_language_query Aucune note.
    Paramètre passages Paramètre passages Le format de passage a changé et a été amélioré dans v2. Le paramètre passages:true a été remplacé par passages.enable:true. Outre les options count, characters et fields, vous pouvez spécifier per_document, qui classe les documents par qualité de document, puis renvoie les passages les mieux classés par document. Vous pouvez également spécifier find_answers pour renvoyer un objet de réponse par passage, qui contient une réponse succincte à la requête.
    regroupement regroupement Même langage d'expression.
    nombre nombre Aucune note.
    offset offset Aucune note.
    return return Aucune note.
    trier trier Aucune note.
    mettre en évidence mettre en évidence Si passages.enabled et passages.per_document sont true, des passages sont renvoyés pour chaque document à la place des mises en évidence.
    suggestions d'orthographe suggestions d'orthographe Aucune note.
    dédoublonner N/A Non pris en charge sur v2.
    similar similar Le format a été modifié dans v2. Le paramètre similar:true a été remplacé par similar.enable:true. Les paramètres document_ids et fields sont passés des chaînes aux tableaux de chaînes. Le paramètre document_ids est désormais requis si enabled est défini sur true.
    pondération N/A Non pris en charge sur v2.

Données d'entraînement

Vous pouvez utiliser l'API de données d'entraînement v1 pour utiliser deux objets associés:

  • requêtes entraînées
  • exemples utilisés pour entraîner les requêtes

Ces deux objets ont des noeuds finaux d'API distincts dans v1. Dans v2, les exemples utilisés pour entraîner chaque requête sont fournis avec la requête et un seul noeud final est utilisé pour utiliser les données d'entraînement.

Par exemple, pour ajouter une requête entraînée et ses exemples de documents d'apprentissage dans v2, vous utilisez la demande POST /v2/projects/{project_id}/training_data/queries et transmettez la requête et tous les exemples dans le contenu d'un appel. De même, si vous souhaitez mettre à jour un exemple dans l'ensemble d'entraînement dans v2, vous devez transmettre la requête et l'exemple modifié (ainsi que tous les autres exemples) au noeud final de mise à jour v2. Dans v1, pour mettre à jour les informations de l'exemple, vous utilisez le noeud final de mise à jour de l'exemple pour modifier un seul exemple.

Une autre différence importante entre v1 et v2 est que dans v1, le modèle entraîné est associé à une collection particulière. Dans v2, le modèle entraîné est associé à un projet. Vous pouvez utiliser les données de plusieurs collections dans un projet pour entraîner un modèle de pertinence. Lorsque vous créez ou mettez à jour des exemples d'entraînement dans v2, l'API requiert collection_id pour la collection dans laquelle le document est stocké.

Détails de la prise en charge de l'API de données de formation
Opération API v1 API v2
Répertorier les données d'entraînement GET /v1/environments/{environment_id}/collections/{collection_id}/training_data GET /v2/projects/{project_id}/training_data /queries
Ajouter une requête aux données d'apprentissage POST /v1/environments/{environment_id}/collections/{collection_id}/training_data POST /v2/projects/{project_id}/training_data /queries
Supprimer toutes les données d'entraînement DELETE /v1/environments/{environment_id}/collections/{collection_id}/training_data DELETE /v2/projects/{project_id}/training_data /queries
Obtenir des détails sur une requête GET /v1/environments/{environment_id}/collections/{collection_id}/training_data/{query_id} GET /v2/projects/{project_id}/training_data /queries/{query_id}
Supprimer une requête de données de formation DELETE /v1/environments/{environment_id}/collections/{collection_id}/training_data/{query_id} DELETE /v2/projects/{project_id}/training_data /queries/{query_id}
Liste d'exemples pour une requête de données de formation GET /v1/environments/{environment_id}/collections/{collection_id}/training_data/{query_id}/examples GET /v2/projects/{project_id}/training_data /queries/{query_id}
Les exemples figurent dans la liste renvoyée avec la requête.
Ajouter un exemple à la requête de données de formation POST /v1/environments/{environment_id}/collections/{collection_id}/training_data/{query_id}/examples POST /v2/projects/{project_id}/training_data /queries/{query_id}
Utilisez la méthode Create training query dans v2 et transmettez tous les exemples lorsque vous créez la requête. Sinon, utilisez l'API de mise à jour.
Exemple de suppression d'une requête de données de formation 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}
Utilisez la méthode de mise à jour v2 training_data.
Modifier le libellé ou la référence croisée, par exemple 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}
Utilisez la méthode de mise à jour v2 training_data.
Obtenir les détails d'un exemple de données d'entraînement GET /v1/environments/{environment_id}/collections/{collection_id}/training_data/{query_id}/examples/{example_id} Non disponible. Utilisez l'appel Lire tous les exemples pour obtenir tous les exemples associés à une requête et rechercher l'exemple dont vous avez besoin dans la liste renvoyée.

Données utilisateur

L'API des données utilisateur est la même dans v2 et v1.

Détails de la prise en charge de l'API de données utilisateur
Opération API v1 API v2
Supprimer DELETE /v1/user_data DELETE /v2/user_data
Similaire à v1. Utilisez customer_id pour supprimer les données associées à cet ID client.

Evénements et commentaires en retour

L'API d'événements et de commentaires v1 (/v1/events) n'est pas disponible dans v2.

Données d'identification

L'API de données d'identification v1 (/v1/environments/{environment_id}/credentials) n'est pas disponible dans v2. La fonction est disponible à partir de l'interface utilisateur du produit v2.

Codes d'état

Pour presque chaque méthode d'API, les codes de statut renvoyés pour les demandes v2 sont différents des codes de statut renvoyés pour les demandes v1.