Pesquisar e filtrar APIs

Esta página se aplica à Apigee e à Apigee híbrida.

Este tópico descreve como usar a Pesquisa semântica com a tecnologia Vertex AI e opções de pesquisa baseadas em filtros para pesquisar recursos específicos no hub da API.

Figura 1. O hub de APIs oferece recursos poderosos de pesquisa e filtro de linguagem natural.

Pesquisar o hub de APIs usando a pesquisa semântica

É fácil encontrar e acessar os recursos da API registrados no hub de APIs usando a pesquisa semântica. A pesquisa semântica permite que você pesquise todos os recursos de API disponíveis na sua instância usando uma consulta de pesquisa de texto livre. É possível pesquisar em todos os tipos de entidade (APIs, operações de API, especificações etc.) ou especifique o tipo de entidade que você quer consultar.

Com o mecanismo de pesquisa da Vertex AI, a Pesquisa semântica pode ir além do termo "correspondência". A pesquisa semântica retorna resultados contendo termos encontrados em qualquer lugar nas entradas detalhadas do recurso da API que são semanticamente semelhantes às consultas de pesquisa de texto livre inseridas.

A pesquisa de texto livre retorna as seguintes categorias de resultados:

• APIs: uma lista de APIs que correspondem à pesquisa. Para cada API, são fornecidos os seguintes detalhes:
  • O nome da API com um link para a página de detalhes dela.
  • Uma breve descrição do recurso.
  • O nome e o endereço de e-mail do proprietário do recurso.
• Versões: uma lista de versões da API que correspondem à pesquisa. Para cada versão, são fornecidos os seguintes detalhes:
  • Os nomes das APIs associadas à versão, com um link que leva à página de detalhes da API.
  • O nome da versão da API, com um link que leva à página de detalhes da versão.
  • A descrição da versão e os metadados relacionados.
• Especificações: uma lista de especificações da API que correspondem à pesquisa. Para cada especificação, são fornecidos os seguintes detalhes:
  • Os nomes da API associada à especificação, com um link que leva à página de detalhes da API.
  • O nome da especificação da API, com um link que leva à página de detalhes da versão associada à especificação.
  • A descrição da especificação.
  • Um link para o documento de especificação.
  • O tipo de especificação, como a especificação OpenAPI.
• Operações: uma lista de operações de API que correspondem à pesquisa. Para cada operação, os seguintes detalhes são fornecidos:
  • Os nomes da API associada à operação, com um link que leva à página de detalhes da API.
  • O nome da operação, com um link que leva à página de detalhes da versão associada à operação.
  • A descrição da especificação.
  • Um link para o documento de especificação que define a operação.
  • Um link para a versão que inclui a operação.
• Deployments: uma lista de implantações que correspondem à pesquisa. Para cada implantação, os seguintes detalhes são fornecidos:
  • O nome da implantação.
  • A descrição da implantação.
  • O tipo de implantação. Por exemplo, a Apigee híbrida.
  • Um link para a versão que inclui a implantação.

Para pesquisar APIs que contêm um termo específico:

1. No console do Google Cloud, acesse a página Pesquisa semântica do hub de APIs.

   Acesse o hub de API

2. Digite uma consulta de pesquisa na caixa de pesquisa.

   Por exemplo, você pode inserir "APIs de gerenciamento de pedidos" ou "Arquivo de especificações para as configurações da operadora sem fio".

   Você pode refinar sua pesquisa usando atributos do sistema no prompt da consulta de pesquisa. Se você criou atributos de usuário ao registrar suas APIs no hub de API, também será possível incorporar esses atributos nos prompts de consulta de pesquisa.

3. Os resultados da pesquisa são categorizados nas seguintes guias: APIs, Versões, Especificações, Operações e Implantações. Clique em uma das guias para conferir os resultados de uma categoria. Os resultados mostram recursos de API que contêm termos semanticamente semelhantes à consulta de pesquisa inserida.
4. Clique no nome do recurso de API para acessar a página de detalhes dele.
5. Para limpar a consulta atual, clique em Limpar resultados.

Hub da API de Pesquisa usando a API

Também é possível pesquisar os recursos do hub da API usando a API Hub. O método searchResources permite consultar os recursos do hub da API usando consultas e filtros de texto livre.

É possível usar a seguinte chamada de API para pesquisar nos recursos do hub de API:

curl -X POST https://apihub.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION:searchResources \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" \
  -d '{
    "query":"QUERY",
    "filter":"resource_type = RESOURCE_TYPE"
   }'

Em que:

• PROJECT_ID é o ID do projeto host da instância do hub da API.
• LOCATION é o local onde a instância do hub da API está hospedada.
• QUERY é a consulta de texto livre a ser usada na pesquisa. A consulta pode conter palavras-chave relacionadas a qualquer detalhe do recurso do hub da API, incluindo nomes de exibição, descrições ou outros metadados.
• RESOURCE_TYPE é o filtro opcional especificado para sua pesquisa. É possível especificar um dos seguintes tipos de recurso do hub de API como filtro:
  • Api
  • ApiOperation
  • Deployment
  • Definition
  • Spec
  • Version

Por exemplo:

curl -X POST https://apihub.googleapis.com/v1/projects/{project-id}/locations/{location}:searchResources \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" \
  -d '{
    "query":"dog status in the store",
    "filter":"resource_type = SPEC"
    }'

Essa chamada retorna uma lista paginada de recursos do hub da API com metadados específicos do recurso.

Para mais informações sobre a pesquisa de texto livre com a API Hub da API, consulte a documentação de referência da API para Method:project.locations.searchResources.

Opções de pesquisa baseadas em filtros

Você pode refinar a lista de APIs exibida na página APIs usando atributos do sistema como parâmetros de pesquisa. Personalize a lista de recursos da API exibida usando uma das seguintes opções:

• Filtrar
• Paginação

Filtrar

Usando a pesquisa de lista baseada em filtros, é possível otimizar a lista de APIs com base em vários parâmetros predefinidos e atributos do sistema associados ao recurso. Você pode usar as opções Match ALL ou Match ANY para personalizar a visualização com filtro.

Observação: as opções de filtro disponíveis são configuradas por um usuário com permissões de administrador. Para mais informações, consulte Gerenciar configurações do hub de API e Gerenciar atributos.

Para especificar as opções de filtro, faça o seguinte:

1. No console do Google Cloud, acesse a página de APIs do hub das APIs.

   Acessar APIs do hub das APIs

2. Clique no campo Filtrar tabela para filtrar a tabela. O painel Filtro será aberto.
   Dica: você pode mostrar ou ocultar colunas na tabela de APIs. Use o menu de ações na linha Filtro para marcar e desmarcar os nomes das linhas.
3. Especifique ou selecione as opções de filtro. Quando você digita no painel "Filtro", um menu com opções de filtro aparece e inclui uma lista de atributos do sistema relevantes para o contexto atual. Por exemplo, estes são os atributos do sistema que podem aparecer ao filtrar as APIs na página APIs:
   • Nome da API: o nome de exibição da API
   • Unidade de negócios:a unidade de negócios responsável por uma API
   • Equipe: a equipe de produção responsável por uma API
   • Documentação: um link curto para a documentação da API.
   Observação: pode haver outros atributos listados como opções de filtro. Para mais informações, consulte Gerenciar atributos da API.

   Os atributos do sistema aparecem na lista de filtros nas tabelas APIs, Versões e Especificações.

4. Após selecionar uma opção de filtro, selecione um valor na lista Valores. Como alternativa, você pode inserir um valor para o atributo de filtro selecionado.
5. Para adicionar mais um filtro, clique no campo Filtrar tabela para selecionar um dos Operadores disponíveis e selecione outro atributo e valor de filtro.

6. As propriedades de filtro selecionadas exibem a lógica condicional que a consulta de filtro está usando. Você pode selecionar OR como operador. Se nenhum operador for selecionado, o padrão será AND.

7. Para limpar um filtro individual, clique no X no filtro. Para limpar todos os filtros, clique em Limpar tudo no painel Filtro.

Paginação

Quando há vários recursos de API, eles podem aparecer em diversas páginas.

Para personalizar a exibição da lista e navegar entre as páginas:

1. No console do Google Cloud, acesse a página de APIs do hub das APIs.

   Acessar APIs do hub das APIs

   A página da lista APIs é exibida por padrão.

2. Na lista APIs, localize as ferramentas de paginação, conforme mostrado na Figura 2:

   

   Figura 2. Navegue pelos resultados paginados.

3. Selecione o número de APIs a serem exibidas por página.
4. Clique em > Avançar para ir para a próxima página.
5. Clique em < Voltar para voltar à página anterior.

A seguir

• Saiba como gerenciar implantações.