Comparación de versiones de API

Para la mayoría de los métodos de API, los parámetros de solicitud y los cuerpos de respuesta difieren entre v1 y v2. Conozca los métodos v2 equivalentes o alternativos que puede utilizar para realizar acciones soportadas por la API v1.

La información de comparación presupone que está utilizando la versión más reciente de la API v1 (versión 2019-04-30) y la compara con la versión más reciente de la API v2 (versión 2020-08-30).

Entornos

No existe ningún concepto de entorno de ** en v2. Los detalles de despliegue, como el tamaño y la capacidad de índice, se gestionan en función del tipo de plan de servicio. En v2, las colecciones se organizan en proyectos. Puede crear distintos tipos de proyectos para aplicar valores de configuración predeterminados a las colecciones que añada a los proyectos.

No hay métodos equivalentes en v2 para los métodos de entorno v1. Sin embargo, la tabla siguiente muestra métodos v2 que sirven funciones similares a los métodos v1 correspondientes. Los parámetros soportados y los cuerpos de respuesta que se devuelven para cada método también difieren.

Detalles de soporte de acciones de la API de entorno
Acción API v1 API v2 relacionada
Crear un entorno POST /v1/environments POST /v2/projects
Listar entornos GET /v1/environments GET /v2/projects
Obtener información de entorno GET /v1/environments/{environment_id} GET /v2/projects/{project_id}
Actualizar un entorno PUT /v1/environments/{environment_id} POST /v2/projects/{project_id}
v2 utiliza POST en lugar de PUT.
Suprimir un entorno DELETE /v1/environment/{environment_id} DELETE /v2/projects/{project_id}
Listar campos entre colecciones GET /v1/environments/{environment_id}/fields GET /v2/projects/{project_id}/fields

Configuraciones

La API v2 no tiene un punto final dedicado a las configuraciones. En su lugar, los valores de configuración para proyectos, colecciones y consultas se especifican directamente en la API para esos objetos. No todos los parámetros de configuración que están disponibles en v1 están disponibles o son aplicables en v2.

En la API de configuración dev1, el objeto JSON que se utiliza para especificar un objeto de configuración contiene varios parámetros que están disponibles en formatos diferentes de otros puntos finales v2 o no están disponibles en v2. En la tabla siguiente se describe cómo encontrar parámetros relacionados en v2.

No puede personalizar la conversión de documentos durante el proceso de ingestión en v2 como puede hacerlo en v1.

Detalles del valor de configuración
Parámetro de configuración v1 API de v2
"conversions.html": { ... } No disponible
"conversions.image_text_recognition": { ... } No disponible desde la API. Sin embargo, puede habilitar el reconocimiento óptico de caracteres (OCR) para una colección de la interfaz de usuario del producto para extraer texto de imágenes. La OCR también tiene otros beneficios. Por ejemplo, si una página de un documento no se puede procesar, OCR convierte la página en una imagen y la explora para asegurarse de que el documento se ha cargado correctamente.
"conversions.json_normalizations": { ... } Se ha movido a la API de recopilaciones.
"conversions.pdf": { ... } No disponible. Si ha utilizado parámetros especiales para extraer texto de imágenes en PDF, habilite el reconocimiento óptico de caracteres (OCR) desde la interfaz de usuario del producto para la colección que contiene los PDF.
"conversions.segment": { ... } No disponible mediante programación. Puede dividir un documento en cada aparición de un campo generado por SDU como, por ejemplo, subtitle desde la interfaz de usuario del producto.
El objeto segment_metadata con información de parent_id, id y total_segments no está disponible en v2. Puede utilizar el campo metadata.parent_document_id para buscar el padre común para muchos segmentos de documento.
"conversions.word": { ... } No disponible
"enrichments": { ... } /v2/projects/{project_id}/enrichments, /v2/projects/{project_id}/collections/{collection_id}
Utilice la API de enriquecimientos para explorar los enriquecimientos existentes. Utilice la API de colecciones para ver y cambiar los enriquecimientos que están habilitados en un campo de una colección.
Algunos enriquecimientos se aplican al servicio de forma predeterminada en función del tipo de proyecto que cree. Para obtener más detalles, consulte Valores predeterminados del proyecto.
La versión del enriquecimiento Entidades que está disponible en v2 no incluye el campo disambiguation, que en v1 contiene la información de desambiguación para la entidad e incluye la información de subtipo de entidad.
Los enriquecimientos siguientes no están disponibles en v2:
-Categorías
-Conceptos
-Emoción
-Relaciones
-Roles semánticos
-Sentimiento de entidades
-Sentimiento de palabras clave
"normalizations": [ ... ] Se ha movido a la API de recopilaciones.
"source": { ... } No disponible. Configure conexiones con orígenes de datos externos a través de la interfaz de usuario. Para obtener más información, consulte Creación de colecciones.

Colecciones

Detalles de soporte de API de colecciones
Acción API v1 API de v2
Crear una colección POST /v1/environments/{environment_id}/collections POST /v2/projects/{project_id}/collections
Los parámetros y respuestas soportados difieren entre las dos versiones. Consulte las notas de la colección.
Listar colecciones GET /v1/environments/{environment_id}/collections GET /v2/projects/{project_id}/collections
En v2, sólo se devuelven en la lista el ID de colección y el nombre de cada colección. Debe utilizar el método Obtener colección para devolver más detalles sobre cada colección.
Obtener detalles de colección GET /v1/environments/{environment_id}/collections/{collection_id} GET /v2/projects/{project_id}/collections/{collection_id}
Consulte las notas de la colección.
Actualizar una colección PUT /v1/environments/{environment_id}/collections/{collection_id} POST /v2/projects/{project_id}/collections/{collection_id}
Suprimir una colección DELETE /v1/environments/{environment_id}/collections/{collection_id} DELETE /v2/projects/{project_id}/collections/{collection_id}
En v2, el campo status no se devuelve en la respuesta.
Listar campos de colección GET /v1/environments/{environment_id}/collections/{collection_id}/fields
v1 lista los campos por colección.		 GET /v2/projects/{project_id}/fields
v2 lista campos por proyecto en su lugar. Puede pasar un único ID de colección con el parámetro collection_ids para obtener campos de una única colección.

Notas de la API de colecciones

La tabla siguiente muestra las diferencias importantes entre las API de recopilación v1 y v2.

Notas de la API de colecciones
Método Notas
Crear una colección La respuesta v2 no incluye los campos status y configuration_id. Puede obtener información de estado para un documento específico utilizando el método Obtener detalles de documento.
Los objetos disk_usage, training_status y crawl_status no están presentes en el cuerpo de respuesta en v2. El objeto document_counts no está presente en el cuerpo de respuesta en v2 actualmente. El estado de entrenamiento se devuelve en la respuesta del método Obtener proyecto. La otra información no está disponible en v2. En v2, puede definir los enriquecimientos que se aplicarán a los documentos de la colección especificando un objeto enrichments opcional.
Obtener detalles de colección La respuesta v2 no incluye los campos status y configuration_id. Puede obtener información de estado para un documento específico utilizando el método Obtener detalles de documento.
Los objetos document_counts, disk_usage, training_status y crawl_status no están presentes en el cuerpo de respuesta en v2. El estado de entrenamiento se devuelve en la respuesta del método Obtener proyecto. La otra información no está disponible en v2. Por ejemplo, no puede obtener el recuento de documentos para una colección y no puede obtener el estado de rastreo para una colección que se conecta a un origen de datos externo en v2. En v2, puede obtener información sobre los enriquecimientos que se aplican a la colección.
Actualizar una colección v2 utiliza POST en lugar de PUT. En v2, puede actualizar los enriquecimientos que se aplican a los documentos de la colección especificando un objeto enrichments opcional.
La respuesta v2 no incluye los campos status y configuration_id.

Modificaciones de consulta

El método que estaba disponible en v1 para configurar la tokenización mediante programación no está soportado en la API v2.

Detalles de soporte de API de modificaciones de consulta
API v1 API de v2
API de diccionario de señalización No disponible.
API v1 de expansiones Expansión v2 API
API de palabras vacías v1 API v2 de palabras vacías

Documentos

Detalles de soporte de la API de documentos
Acción API v1 API de v2
Listar documentos No disponible en la API v1 GET /v2/projects/{project_id}/collections/{collection_id}/documents
Crear un documento POST /v1/environments/{environment_id}/collections/{collection_id}/documents POST /v2/projects/{project_id}/collections/{collection_id}/documents
A diferencia de v1, la respuesta v2 no incluye un objeto de avisos. Sin embargo, puede obtener información de avisos utilizando el método Obtener detalles de documento en v2.
Actualizar un documento POST /v1/environments/{environment_id}/collections /{collection_id}/documents/{document_id} POST /v2/projects/{project_id}/collections/{collection_id}/documents/{document_id}
Al actualizar un documento que se ha dividido, se sobrescriben todos los segmentos de documento.
Obtener detalles de documento GET /v1/environments/{environment_id}/collections /{collection_id}/documents/{document_id} GET /v2/projects/{project_id}/collections/{collection_id}/documents/{document_id}
En v2, no hay ningún objeto statusDescription. v2 tiene un objeto children con información sobre los avisos asociados con los documentos hijo que se generan durante la ingestión.
Supresión de un documento DELETE /v1/environments/{environment_id}/collections /{collection_id}/documents/{document_id} DELETE /v2/projects/{project_id}/collections/{collection_id}/documents/{document_id}
Los segmentos de un documento cargado no se pueden suprimir individualmente. Suprimir todos los segmentos con una solicitud DELETE que incluya el parent_document_id de un resultado de segmento.

v2 introduce una cabecera personalizada denominada X-Watson-Discovery-Force que no está disponible en v1. Debe incluir la cabecera cuando realice una operación en datos que se comparten entre muchas colecciones para indicar que desea realizar la operación en cada colección. Si no incluye la cabecera, se devuelve un error 403.

Los campos de los archivos JSON que se añaden a una colección se convierten de forma diferente durante la ingestión entre v1 y v2. Para obtener más información sobre cómo se almacenan los archivos JSON en el índice v2, consulte Archivos JSON.

Consultas

Detalles de soporte de la API de documentos
Acción API v1 API de v2
Consultar una colección Da soporte a una solicitud GET o POST.
GET o POST /v1/environments/{environment_id}/collections/{collection_id}/query		 Consulta un proyecto. Para especificar una única colección, incluya el parámetro {collection_id}. Sólo da soporte a una solicitud POST.
POST /v2/projects/{project_id}/query
Consultar varias colecciones GET o POST /v1/environments/{environment_id}/query POST /v2/projects/{project_id}/query
Consultar avisos del sistema GET /v1/environments/{environment_id}/collections/{collection_id}/avisos GET /v2/projects/{project_id}/collections/{collection_id}/avisos
Consulta de notificaciones de múltiples sistemas de recogida GET /v1/environments/{environment_id}/avisos GET /v2/projects/{project_id}/avisos
Obtener sugerencias de rellenado automático /v1/environments/{environment_id}/collections/{collection_id}/autocomplete GET /v2/projects/{project_id}/autocomplete
Consulte las notas de consulta.

Algunas configuraciones de resultados de consulta se aplican al servicio de forma predeterminada en función del tipo de proyecto que cree. Para obtener más detalles, consulte Valores predeterminados del proyecto.

Notas de consulta

  • Las consultas v2 devuelven resultados de todas las colecciones del proyecto. Para restringir la consulta para que utilice sólo determinadas colecciones dentro del proyecto, utilice el parámetro de consulta collection_ids. No puede consultar varias colecciones que se han añadido a distintos proyectos con una solicitud de consulta v2.

  • Los resultados v2 incluyen un campo confidence, pero no un campo score.

    La puntuación de confianza ha sustituido la información de puntuación en v1, pero la puntuación se ha retenido para la compatibilidad con versiones anteriores. En v2, sólo se devuelve el campo de confianza.

  • Utilice llamadas POST (en lugar de llamadas GET) para enviar consultas con v2.

  • Las consultas v1 aceptan muchos parámetros. La tabla Comparación de parámetros de consulta correlaciona los parámetros v1 con los parámetros v2.

    Comparación de parámetros de consulta
    Parámetro v1 Parámetro v2 Notas
    N/D collection_ids Utilice este parámetro en v2 para especificar los ID de colección.
    filtro filtro Mismo lenguaje de expresión.
    consulta consulta Mismo lenguaje de expresión.
    natural_language_query natural_language_query No hay notas.
    passages passages El formato de pasaje ha cambiado y se ha mejorado en v2. El parámetro passages:true ha cambiado a passages.enable:true. Además de las opciones count, characters y fields, puede especificar per_document, que clasifica los documentos por calidad de documento y, a continuación, devuelve los pasajes con la clasificación más alta por documento. También puede especificar find_answers para devolver un objeto de respuesta por pasaje, que contiene una respuesta sucinta a la consulta.
    agregación agregación Mismo lenguaje de expresión.
    recuento recuento No hay notas.
    offset offset No hay notas.
    return return No hay notas.
    sort sort No hay notas.
    highlight highlight Si passages.enabled y passages.per_document son true, se devuelven pasajes para cada documento en lugar de resaltados.
    sugerencias de ortografía sugerencias de ortografía No hay notas.
    deduplicate N/D No se admite en v2.
    similar similar El formato ha cambiado en v2. El parámetro similar:true ha cambiado a similar.enable:true. Los parámetros document_ids y fields han cambiado de series a matrices de series. El parámetro document_ids ahora es necesario si enabled es true.
    bias N/D No se admite en v2.

Datos de entrenamiento

Puede utilizar la API de datos de entrenamiento v1 para trabajar con dos objetos relacionados:

  • consultas entrenadas
  • ejemplos que se utilizan para entrenar las consultas

Estos dos objetos tienen puntos finales de API separados en v1. En v2, los ejemplos que se utilizan para entrenar cada consulta se proporcionan junto con la consulta y sólo se utiliza un punto final para trabajar con los datos de entrenamiento.

Por ejemplo, para añadir una consulta entrenada y sus documentos de ejemplo de entrenamiento en v2, utilice la solicitud POST /v2/projects/{project_id}/training_data/queries y pase la consulta y todos los ejemplos en la carga útil de una llamada. De forma similar, si desea actualizar un ejemplo en el conjunto de entrenamiento en v2, debe pasar la consulta y el ejemplo modificado (junto con todos los demás ejemplos) al punto final de actualización v2. En v1, para actualizar la información de ejemplo, utilice el punto final de ejemplo de actualización para modificar sólo un ejemplo.

Otra diferencia importante entre v1 y v2 es que en v1, el modelo entrenado se asocia a una colección determinada. En v2, el modelo entrenado está asociado a un proyecto. Puede utilizar los datos de varias recopilaciones dentro de un proyecto para entrenar un modelo de relevancia. Al crear o actualizar ejemplos de entrenamiento en v2, la API requiere collection_id para la colección donde se almacena el documento.

Detalles de soporte de API de datos de entrenamiento
Acción API v1 API de v2
Listar datos de entrenamiento GET /v1/environments/{environment_id}/collections/{collection_id}/training_data GET /v2/projects/{project_id}/training_data /queries
Añadir consulta a los datos de entrenamiento POST /v1/environments/{environment_id}/collections/{collection_id}/training_data POST /v2/projects/{project_id}/training_data /queries
Suprimir todos los datos de entrenamiento DELETE /v1/environments/{environment_id}/collections/{collection_id}/training_data DELETE /v2/projects/{project_id}/training_data /queries
Obtener detalles sobre una consulta GET /v1/environments/{environment_id}/collections/{collection_id}/training_data/{query_id} GET /v2/projects/{project_id}/training_data /queries/{query_id}
Borrar una consulta de datos de entrenamiento DELETE /v1/environments/{environment_id}/collections/{collection_id}/training_data/{query_id} DELETE /v2/projects/{project_id}/training_data /queries/{query_id}
Lista de ejemplos para una consulta de datos de formación GET /v1/environments/{environment_id}/collections/{collection_id}/training_data/{query_id}/examples GET /v2/projects/{project_id}/training_data /queries/{query_id}
Los ejemplos están en la lista que se devuelve con la consulta.
Añadir ejemplo a la consulta de datos de formación POST /v1/environments/{environment_id}/collections/{collection_id}/training_data/{query_id}/examples POST /v2/projects/{project_id}/training_data /queries/{query_id}
Utilice el método Crear consulta de entrenamiento en v2 y pase todos los ejemplos al crear la consulta. De lo contrario, utilice la API de actualización.
Ejemplo de supresión para la consulta de datos de formación 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}
Utilice el método de actualización training_data v2.
Cambiar etiqueta o referencia cruzada, por ejemplo 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}
Utilice el método de actualización training_data v2.
Obtener detalles de un ejemplo de datos de entrenamiento GET /v1/environments/{environment_id}/collections/{collection_id}/training_data/{query_id}/examples/{example_id} No disponible. Utilice la llamada Leer todos los ejemplos para obtener todos los ejemplos asociados a una consulta y buscar el ejemplo que necesita en la lista devuelta.

Datos de usuario

La API de datos de usuario es la misma en v2 y v1.

Detalles de soporte de API de datos de usuario
Acción API v1 API de v2
Suprimir DELETE /v1/user_data DELETE /v2/user_data
Similar a v1. Utilice customer_id para suprimir los datos asociados con ese ID de cliente.

Eventos y comentarios

La API de sucesos y comentarios de v1 (/v1/events) no está disponible en v2.

Credenciales

La API de credenciales de v1 (/v1/environments/{environment_id}/credentials) no está disponible en v2. La función está disponible desde la interfaz de usuario del producto v2.

Códigos de estado

Para casi cada método de API, los códigos de estado que se devuelven para las solicitudes v2 son diferentes de los códigos de estado que se devuelven para las solicitudes v1.