Rechercher et filtrer des API

Cette page s'applique à Apigee et à Apigee hybrid.

Cet article explique comment utiliser la recherche sémantique basée sur Vertex AI et les options de recherche basées sur les filtres pour rechercher des ressources spécifiques dans le hub d'API.

Rechercher et appliquer des filtres
Figure 1. Le hub d'API fournit des fonctionnalités de recherche et de filtrage puissantes en langage naturel.

Vous pouvez trouver et afficher facilement les ressources d'API enregistrées dans votre hub d'API grâce à la recherche sémantique. La recherche sémantique vous permet également de rechercher toutes les ressources d'API disponibles dans votre instance à l'aide d'une requête de recherche en texte libre. Vous pouvez effectuer des recherches dans tous les types d'entités (API, opérations d'API, spécifications, etc.), ou spécifier le type d'entité que vous souhaitez interroger.

Grâce à son moteur de recherche Vertex AI, la recherche sémantique peut aller au-delà du terme "correspondance". La recherche sémantique renvoie des résultats contenant des termes trouvés n'importe où dans les entrées de ressources d'API détaillées qui sont sémantiquement semblables aux requêtes de recherche de texte libre saisies.

La recherche en texte libre renvoie les catégories de résultats suivantes :

  • API : liste des API correspondant à la recherche. Pour chaque API, les informations suivantes sont fournies :
    • Nom de l'API avec un lien vers la page d'informations de l'API.
    • Brève description de la ressource.
    • Nom et adresse e-mail du propriétaire de la ressource.
  • Versions : liste des versions d'API correspondant à la recherche. Pour chaque version, les informations suivantes sont fournies :
    • Les noms des API associées à la version, avec un lien vers la page d'informations de l'API.
    • Nom de la version de l'API, avec un lien vers la page d'informations de la version.
    • Description de la version et des métadonnées associées.
  • Spécifications : liste des spécifications d'API correspondant à la recherche. Pour chaque spécification, les informations suivantes sont fournies :
    • Nom de l'API associée à la spécification, avec un lien vers la page d'informations de l'API.
    • Nom de la spécification de l'API, avec un lien vers la page d'informations de la version associée à la spécification.
    • Description de la spécification.
    • Lien vers le document de spécification.
    • Type de spécification, par exemple OpenAPI.
  • Opérations : liste des opérations d'API correspondant à la recherche. Pour chaque opération, les informations suivantes sont fournies :
    • Noms des API associées à l'opération, avec un lien vers la page d'informations de l'API.
    • Nom de l'opération, avec un lien vers la page d'informations de la version associée à l'opération.
    • Description de la spécification.
    • Lien vers le document de spécification qui définit l'opération.
    • Lien vers la version qui inclut l'opération.
  • Déploiements : liste des déploiements correspondant à la recherche. Pour chaque déploiement, les informations suivantes sont fournies :
    • Le nom du déploiement.
    • La description du déploiement.
    • Type de déploiement. Exemple : Apigee hybrid.
    • Lien vers la version qui inclut le déploiement.

Pour rechercher des API contenant un terme spécifique, procédez comme suit :

  1. Dans la console Google Cloud, accédez à la page Recherche sémantique de l'API Hub.

    Accéder à l'API Hub

  2. Saisissez une requête de recherche dans le champ de recherche.

    Par exemple, vous pouvez saisir "API de gestion des commandes" ou "Fichier de spécification pour les paramètres de l'opérateur sans fil".

    Vous pouvez affiner votre recherche en utilisant les attributs système dans l'invite de requête de recherche. Si vous avez créé des attributs utilisateur lors de l'enregistrement de vos API dans le hub d'API, vous pouvez également les intégrer dans vos requêtes de recherche.

  3. Les résultats de recherche sont classés dans les onglets suivants : API, versions, spécifications, opérations et déploiements. Cliquez sur l'un des onglets pour afficher les résultats d'une catégorie. Les résultats affichent les ressources d'API contenant des termes sémantiquement semblables à la requête de recherche que vous avez saisie.
  4. Cliquez sur le nom de ressource de l'API pour afficher la page d'informations de la ressource.
  5. Pour effacer la requête actuelle, cliquez sur Effacer les résultats.

Vous pouvez également effectuer une recherche dans les ressources de votre hub d'API à l'aide de l'API du hub d'API. La méthode searchResources vous permet d'interroger vos ressources de hub d''API à l'aide de requêtes et de filtres en texte libre.

Vous pouvez utiliser l'appel d'API suivant pour rechercher des ressources dans votre hub d'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"
   }'

Où :

  • PROJECT_ID est l'ID du projet hôte pour votre instance de hub d'API.
  • LOCATION est l'emplacement où votre instance de hub d'API est hébergée.
  • QUERY est la requête de texte libre à utiliser dans la recherche. La requête peut contenir des mots clés en rapport avec n'importe quel détail de la ressource de hub d'API, y compris des noms à afficher, des descriptions ou d'autres métadonnées.
  • RESOURCE_TYPE correspond au filtre facultatif spécifié pour votre recherche. Vous pouvez spécifier l'un des types de ressources du hub d'API suivants en tant que filtre :
    • Api
    • ApiOperation
    • Deployment
    • Definition
    • Spec
    • Version

Exemple :

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"
    }'

Cet appel renvoie une liste paginée de ressources de hub d'API, avec des métadonnées spécifiques à la ressource.

Pour plus d'informations sur la recherche en texte libre avec l'API de hub d'API, consultez la documentation de référence de l'API pour Method:project.locations.searchResources.

Options de recherche basées sur des filtres

Vous pouvez affiner la liste des API affichées sur la page API en utilisant les attributs système en tant que paramètres de recherche. Personnalisez la liste des ressources d'API affichées à l'aide de l'une des options suivantes :

Filtre

La recherche de listes basée sur des filtres vous permet de simplifier votre liste d'API en fonction d'un certain nombre de paramètres et d'attributs système prédéfinis associés à la ressource. Vous pouvez utiliser les options Match ALL ou Match ANY pour personnaliser la vue filtrée.

Pour spécifier des options de filtrage, procédez comme suit :

  1. Dans la console Google Cloud, accédez à la page API du hub d'API.

    Accéder à la page API du hub d'API

  2. Cliquez dans le champ Filtrer le tableau pour filtrer le tableau. Le volet Filtre s'ouvre.
  3. Spécifiez ou sélectionnez les options de filtrage. Lorsque vous tapez du texte dans le volet "Filtre", un menu d'options de filtre s'affiche, avec une liste des attributs système correspondant au contexte actuel. Par exemple, voici les attributs système que vous pouvez voir lorsque vous filtrez les API sur la page API :
    • Nom de l'API : nom à afficher de l'API
    • Unité commerciale : unité commerciale responsable d'une API.
    • Équipe : équipe responsable de la production d'une API.
    • Documentation : lien court vers la documentation de l'API.

      • Les attributs système s'affichent dans la liste des filtres des tableaux API, Versions et Spécifications.

  4. Après avoir sélectionné une option de filtre, sélectionnez une valeur de filtre dans la liste Valeurs. Vous pouvez également saisir une valeur pour l'attribut de filtre que vous sélectionnez.
  5. Pour ajouter un filtre supplémentaire, cliquez dans le champ Filtrer le tableau pour sélectionner l'un des Opérateurs disponibles, puis sélectionnez un autre attribut et une autre valeur de filtre.

  6. Les propriétés du filtre sélectionné affichent la logique conditionnelle utilisée par la requête de filtre. Vous pouvez sélectionner OR comme opérateur. Si aucun opérateur n'est sélectionné, la valeur par défaut est AND.

  7. Pour effacer un filtre individuel, cliquez sur le X dans le filtre. Pour effacer tous les filtres, cliquez sur Tout effacer dans le volet Filtre.

Pagination

Lorsqu'il existe plusieurs ressources d'API, elles peuvent s'afficher sur plusieurs pages.

Pour personnaliser l'affichage de la liste et naviguer entre les pages, procédez comme suit :

  1. Dans la console Google Cloud, accédez à la page API du hub d'API.

    Accéder à la page API du hub d'API

    La page de la liste des API s'affiche par défaut.

  2. Dans la liste API, localisez les outils de pagination comme illustré dans la figure 2 :

    Sélections de pagination
    Figure 2. Déplacez-vous vers l'avant et vers l'arrière dans les résultats paginés.
  3. Sélectionnez le nombre d'API à afficher par page.
  4. Cliquez sur > Suivant pour passer à la page suivante.
  5. Cliquez sur < Retour pour revenir à la page précédente.

Étape suivante