Comparação de versão da API

Para a maioria dos métodos de API, os parâmetros de solicitação e os corpos de resposta diferem entre v1 e v2. Aprenda sobre os métodos equivalentes ou alternativos v2 que você pode usar para fazer ações que são suportadas pela API v1.

A informação de comparação assume que você está usando a versão mais recente da API do v1 (versão 2019-04-30) e a compara a versão mais recente da API v2 (versão 2020-08-30).

Ambientes

Não há conceito de um ambiente em v2. Os detalhes de implementação como tamanho e capacidade de índice são gerenciados com base no tipo de plano de serviço. Em v2, as coleções são organizadas em projetos. Você pode criar diferentes tipos de projetos para aplicar configurações de configuração padrão nas coleções que você adicionar aos projetos.

Não há métodos equivalentes em v2 para os métodos de ambiente v1. No entanto, a tabela a seguir mostra os métodos v2 que atendem funções semelhantes aos métodos correspondentes v1. Os parâmetros suportados e os corpos de resposta que são retornados para cada método diferem também.

Detalhes de suporte de ação da API de ambiente
Ação API da v1 API v2 relacionada
Criar um ambiente POST /v1/environments POST /v2/projects
Listar ambientes GET /v1/environments GET /v2/projects
Obter informações do ambiente GET /v1/environments/{environment_id} GET /v2/projects/{project_id}
Atualizar um ambiente PUT /v1/environments/{environment_id} POST /v2/projects/{project_id}
v2 usa POST em vez de PUT.
Excluir um ambiente DELETE /v1/environment/{environment_id} DELETE /v2/projects/{project_id}
Listar campos nas coleções GET /v1/environments/{environment_id}/fields GET /v2/projects/{project_id}/fields

XLATEREVIEW

A API v2 não tem um endpoint que seja dedicado a configurações. Em vez disso, configurações de configuração para projetos, coleções e consultas são especificadas diretamente na API para esses objetos. Nem todos os parâmetros de configuração que estão disponíveis em v1 estão disponíveis ou aplicáveis em v2.

Na API de configuração v1, o objeto JSON que é usado para especificar um objeto de configuração contém vários parâmetros que estão disponíveis em formatos diferentes a partir de outros terminais v2 ou não estão disponíveis em v2. A tabela a seguir descreve como encontrar parâmetros relacionados em v2.

Não é possível customizar a conversão de documentos durante o processo de ingestão em v2 como você pode em v1.

Configuração de configuração de configuração
Parâmetro de configuração v1 API v2
"conversions.html": { ... } Não disponível
"conversions.image_text_recognition": { ... } Não disponível a partir da API. No entanto, é possível ativar o reconhecimento de caracteres ópticos (OCR) para uma coleta a partir da interface do usuário do produto para extrair texto a partir de imagens. A OCR tem outros benefícios, também. Por exemplo, se uma página em um documento não pode ser processada, OCR converte a página em uma imagem e a scans para garantir que o documento seja carregado com sucesso.
"conversions.json_normalizations": { ... } Movido para a API de Coleções.
"conversions.pdf": { ... } Não disponível. Se você usou parâmetros especiais para extrair texto a partir de imagens em PDFs, ative o reconhecimento de caracteres ópticos (OCR) a partir da interface do usuário do produto para a coleta que contém os PDFs em vez disso.
"conversions.segment": { ... } Não disponível programaticamente. É possível dividir um documento em cada ocorrência de um campo gerado por SDU, como subtitle da interface com o usuário do produto.
. O objeto segment_metadata com informações parent_id, id e total_segments não está disponível em v2. É possível usar o campo metadata.parent_document_id para localizar o pai comum para muitos segmentos do documento..
"conversions.word": { ... } Não disponível
"enrichments": { ... } /v2/projects/{project_id}/enrichments, /v2/projects/{project_id}/collections/{collection_id}
Use a API de enriquecimentos para explorar os enriquecimentos existentes. Use a API de coleções para ver e alterar os enriquecimentos que são ativados em um campo em uma coleção.
Alguns enriquecimentos são aplicados ao serviço por padrão com base no tipo de projeto que você cria. Para obter mais detalhes, consulte Configurações de projeto padrão.
A versão do enriquecimento de Entidades que está disponível em v2 não inclui o campo disambiguation, que em v1 contém as informações de desambiguação para a entidade e inclui as informações do subtipo entidade.
Os enriquecimentos a seguir não estão disponíveis em v2:
-Categorias
-Conceitos
-Emoção
-Relações
-Funções Semânticas
-Sentimento de Entidades
-Sentimento de Palavras-chave
"normalizations": [ ... ] Movido para a API de Coleções.
"source": { ... } Não disponível. Configurar conexões com fontes de dados externas através da interface do usuário. Para obter mais informações, consulte Criando coleções.

Coleções

Detalhes de suporte da API de Coleções
Ação API da v1 API v2
Criar uma coleção POST /v1/environments/{environment_id}/collections POST /v2/projects/{project_id}/collections
Os parâmetros suportados e as respostas diferem entre as duas versões. Veja as notas de cobrança.
Listar coleções GET /v1/environments/{environment_id}/collections GET /v2/projects/{project_id}/collections
Em v2, apenas o ID de coleta e o nome de cada coleção são retornados na lista. Você deve usar o método Obter coleção para retornar mais detalhes sobre cada coleção.
Obter detalhes da coleção GET /v1/environments/{environment_id}/collections/{collection_id} GET /v2/projects/{project_id}/collections/{collection_id}
Veja as notas da coleção.
Atualizar uma coleção PUT /v1/environments/{environment_id}/collections/{collection_id} POST /v2/projects/{project_id}/collections/{collection_id}
Excluir uma coleção DELETE /v1/environments/{environment_id}/collections/{collection_id} DELETE /v2/projects/{project_id}/collections/{collection_id}
Em v2, o campo status não é retornado na resposta.
Campos de coleta de lista GET /v1/environments/{environment_id}/collections/{collection_id}/fields
v1 lista os campos por coleção.		 GET /v2/projects/{project_id}/fields
v2 lista campos por projeto em vez disso. Você pode passar um único ID de coleta com o parâmetro collection_ids para obter campos a partir de uma única coleção.

Notas da API Coleções

A tabela a seguir mostra as diferenças importantes entre as APIs de coleção v1 e v2.

Notas API de Coleções
Método Notas
Criar uma coleção A resposta v2 não inclui os campos status e configuration_id. Você pode obter informações de status para um documento específico usando o método Obter detalhes do documento.
Os objetos disk_usage, training_status e crawl_status não estão presentes no corpo de resposta em v2. O objeto document_counts não está presente no corpo de resposta em v2 atualmente. O status de treinamento é retornado na resposta do método Obter projeto. As outras informações não estão disponíveis em v2. Em v2, é possível definir os enriquecimentos para aplicar aos documentos na coleção especificando um objeto enrichments opcional.
Obter detalhes da coleção A resposta v2 não inclui os campos status e configuration_id. Você pode obter informações de status para um documento específico usando o método Obter detalhes do documento.
Os objetos document_counts, disk_usage, training_status e crawl_status não estão presentes no corpo de resposta em v2. O status de treinamento é retornado na resposta do método Obter projeto. As outras informações não estão disponíveis em v2. Por exemplo, não é possível obter a contagem de documentos para uma coleção e não pode obter o status de crawl para uma coleção que se conecta a uma fonte de dados externa em v2. Em v2, é possível obter informações sobre os enriquecimentos que são aplicados na coleção.
Atualizar uma coleção v2 usa POST em vez de PUT. Em v2, é possível atualizar os enriquecimentos que são aplicados aos documentos na coleção especificando um objeto enrichments opcional.
A resposta v2 não inclui os campos status e configuration_id.

Modificações de consulta

O método que estava disponível em v1 para configurar tokenização programaticamente não é suportado na API v2.

Detalhes de suporte da API de modificações
API da v1 API v2
API do dicionário de tokenização Não disponível.
Expansões v1 API Expansões v2 API
Stopwords v1 API Stopwords v2 API

Documentos

Detalhes de suporte da API de documentos
Ação API da v1 API v2
Listar documentos Não disponível a partir da API v1 GET /v2/projects/{project_id}/collections/{collection_id}/documentos
Criar um documento POST /v1/environments/{environment_id}/collections/{collection_id}/documents POST /v2/projects/{project_id}/collections/{collection_id}/documents
Diferentemente do v1, a resposta v2 não inclui um objeto de avisos. No entanto, você pode obter informações de avisos usando o método Obter detalhes do documento em v2.
Atualizar um documento POST /v1/environments/{environment_id}/collections /{collection_id}/documents/{document_id} POST /v2/projects/{project_id}/collections/{collection_id}/documents/{document_id}
Ao se atualizar um documento que foi dividido, todos os segmentos de documentos estão sobrescrito.
Obter detalhes do documento GET /v1/environments/{environment_id}/collections /{collection_id}/documents/{document_id} GET /v2/projects/{project_id}/collections/{collection_id}/documents/{document_id}
Em v2, não há statusDescription. v2 tem um objeto children com informações sobre quaisquer avisos que estejam associados com os documentos filhos que são gerados durante a ingestão.
Excluir um documento DELETE /v1/environments/{environment_id}/collections /{collection_id}/documents/{document_id} DELETE /v2/projects/{project_id}/collections/{collection_id}/documents/{document_id}
Segmentos de um documento uploaded não podem ser excluídos individualmente. Exclua todos os segmentos com uma solicitação DELETE que inclui o parent_document_id de um resultado do segmento.

v2 introduz um cabeçalho personalizado que é denominado X-Watson-Discovery-Force que não está disponível em v1. Você deve incluir o cabeçalho quando realizar uma operação em dados que são compartilhados entre muitas coleções para indicar que deseja realizar a operação em cada coleção. Se você não incluir o cabeçalho, um erro 403 é retornado.

Os campos de arquivos JSON que são adicionados a uma coleção são convertidos de forma diferente durante a ingestão entre v1 e v2. Para obter mais informações sobre como os arquivos JSON são armazenados no índice v2, veja arquivos JSON.

Consultas

Detalhes de suporte da API de documentos
Ação API da v1 API v2
Consultar uma coleção Suporta uma solicitação GET ou POST.
GET ou POST /v1/environments/{environment_id}/collections/{collection_id}/query		 Consultas um projeto. Para especificar uma única coleção, inclua o parâmetro {collection_id}. Suporta uma solicitação POST apenas.
POST /v2/projects/{project_id}/query
Consultar múltiplas coleções GET ou POST /v1/environments/{environment_id}/query POST /v2/projects/{project_id}/query
Avisos do sistema de consulta GET /v1/environments/{environment_id}/collections/{collection_id}/avisos GET /v2/projects/{project_id}/collections/{collection_id}/avisos
Consultar avisos de vários sistemas de coleta GET /v1/environments/{environment_id}/avisos GET /v2/projects/{project_id}/avisos
Obter sugestões Autocompletas /v1/environments/{environment_id}/collections/{collection_id}/autoconclusão GET /v2/projects/{project_id}/autoconclusão
Veja as notas de consulta.

Algumas configurações de resultado da consulta são aplicadas ao serviço por padrão com base no tipo de projeto que você cria. Para obter mais detalhes, consulte Configurações de projeto padrão.

Notas de consulta

  • v2 consultas retornam resultados de todas as coleções no projeto. Para restringir a consulta a utilizar apenas determinadas coleções dentro do projeto, use o parâmetro de consulta collection_ids. Não é possível consultar várias coleções que são adicionadas a diferentes projetos com uma solicitação de consulta v2.

  • Os resultados do v2 incluem um campo confidence, mas não um campo score.

    A pontuação de confiança substituiu as informações de pontuação em v1, mas pontuação foi retida para compatibilidade com retrocesso. Em v2, apenas o campo de confiança é retornado.

  • Use chamadas POST (em vez de chamadas GET) para enviar consultas com v2.

  • v1 consultas aceitam muitos parâmetros. A tabela Comparação de parâmetros de consulta mapeia os parâmetros v1 para os parâmetros v2.

    Comparação de parâmetros de consulta
    v1 parâmetro v2 parâmetro Notas
    N/D collection_ids Use este parâmetro em v2 para especificar ids de coleta.
    filtro filtro Mesma linguagem de expressão.
    Consultar Consultar Mesma linguagem de expressão.
    natural_language_query natural_language_query Nenhuma nota.
    passages passages O formato de passagem mudou e foi aprimorado em v2. O parâmetro passages:true mudou para passages.enable:true. Além das opções count, characters e fields, você pode especificar per_document, que classifica os documentos por qualidade de documento e, em seguida, retorna as passagens de maior ranqueamento por documento. Você também pode especificar find_answers para retornar um objeto de resposta por passagem, que contém uma resposta sucinta para a consulta.
    agregação agregação Mesma linguagem de expressão.
    contagem contagem Nenhuma nota.
    offset offset Nenhuma nota.
    return return Nenhuma nota.
    ordenar ordenar Nenhuma nota.
    destacar destacar Se passages.enabled e passages.per_document forem true, então, são retornadas passagens para cada documento em vez de destaques.
    spelling_sugestões spelling_sugestões Nenhuma nota.
    deduplicar N/D Não há suporte em v2.
    semelhante semelhante O formato alterado em v2. O parâmetro similar:true mudou para similar.enable:true. Os parâmetros document_ids e fields mudaram de strings para matrizes string. O parâmetro document_ids agora é necessário se enabled for true.
    viés N/D Não há suporte em v2.

Dados de treinamento

Você pode usar a API de dados de treinamento do v1 para trabalhar com dois objetos relacionados:

  • consultas treinadas
  • exemplos que são usados para treinar as consultas

Esses dois objetos possuem terminais de API separados em v1. No v2, os exemplos que são usados para treinar cada consulta são fornecidos junto com a consulta e apenas um terminal é usado para trabalhar com os dados de treinamento...

Por exemplo, para adicionar uma consulta treinada e seus documentos de exemplo de treinamento em v2, você usa a solicitação POST /v2/projects/{project_id}/training_data/queries e passa a consulta e todos os exemplos na carga útil de uma chamada. Da mesma forma, se você deseja atualizar um exemplo no conjunto de treinamentos em v2, deve-se passar a consulta e o exemplo modificado (juntamente com todos os outros exemplos) para o terminal de atualização v2. Em v1, para atualizar as informações de exemplo, você usa o terminal de exemplo de atualização para modificar apenas um exemplo.

Outra diferença importante entre o v1 e o v2 é que em v1, o modelo treinado está associado a uma determinada coleção. Em v2, o modelo treinado está associado a um projeto. Você pode utilizar os dados de várias coleções dentro de um projeto para treinar um modelo de relevância. Ao criar ou atualizar exemplos de treinamento em v2, a API requer o collection_id para a coleta onde o documento é armazenado.

Detalhes de suporte da API de dados de treinamento
Ação API da v1 API v2
Listar dados de treinamento GET /v1/environments/{environment_id}/collections/{collection_id}/training_data GET /v2/projects/{project_id}/training_data /queries
Adicionar consulta aos dados de treinamento POST /v1/environments/{environment_id}/collections/{collection_id}/training_data POST /v2/projects/{project_id}/training_data /queries
Excluir todos os dados de treinamento DELETE /v1/environments/{environment_id}/collections/{collection_id}/training_data DELETE /v2/projects/{project_id}/training_data /queries
Obter detalhes sobre uma consulta GET /v1/environments/{environment_id}/collections/{collection_id}/training_data/{query_id} GET /v2/projects/{project_id}/training_data /queries/{query_id}
Excluir uma consulta de dados de treinamento DELETE /v1/environments/{environment_id}/collections/{collection_id}/training_data/{query_id} DELETE /v2/projects/{project_id}/training_data /queries/{query_id}
Listar exemplos para uma consulta de dados de treinamento GET /v1/environments/{environment_id}/collections/{collection_id}/training_data/{query_id}/examples GET /v2/projects/{project_id}/training_data /queries/{query_id}
Os exemplos estão na lista que é retornada com a consulta.
Adicionar exemplo à consulta de dados de treinamento POST /v1/environments/{environment_id}/collections/{collection_id}/training_data/{query_id}/examples POST /v2/projects/{project_id}/training_data /queries/{query_id}
Use o método Criar consulta de treinamento em v2 e transmitem todos os exemplos quando você criar a consulta. Caso contrário, use a API de atualização.
Excluir exemplo para consulta de dados de treinamento 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}
Use o método de atualização de training_data do v2.
Alterar rótulo ou cross-reference por exemplo 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}
Use o método de atualização de training_data do v2.
Obter detalhes de um exemplo de dados de treinamento GET /v1/environments/{environment_id}/collections/{collection_id}/training_data/{query_id}/examples/{example_id} Não disponível. Use a chamada Leia todos os exemplos para obter todos os exemplos associados a uma consulta e encontre o exemplo que você precisa na lista de devolvidos.

Dados do usuário

A API de dados do usuário é a mesma em v2 e v1.

Detalhes de suporte da API de dados do usuário
Ação API da v1 API v2
Excluir DELETE /v1/user_data DELETE /v2/user_data
Similar ao v1. Use customer_id para excluir os dados associados a esse ID do cliente.

Eventos e feedback

Os eventos do v1 e API de feedback (/v1/events) não estão disponíveis em v2.

Credenciais

A API de credenciais do v1 (/v1/environments/{environment_id}/credentials) não está disponível em v2. A função está disponível a partir da interface do usuário do produto v2.

Códigos de status

Para quase todo método API, os códigos de status que são retornados para os pedidos v2 são diferentes dos códigos de status que são retornados para pedidos v1.