Interroger l'API Context de Pulumi

L'API Context répond aux questions sur l'infrastructure cloud d'une organisation sous forme de graphe : ce qui existe, ce qui dépend de quoi, ce qu'une modification affecterait. Elle couvre les ressources trouvées via Pulumi Discovery, pas seulement celles gérées par Pulumi.

Préférez-la à Resource Search chaque fois que la question implique des relations. Resource Search trouve des ressources individuelles mais ne peut pas suivre les arêtes, donc répondre à « qu'est-ce qui dépend de X » en répétant les recherches est lent et généralement incomplet.

Avant-première publique, pour les organisations aux éditions Enterprise et Business Critical. Nécessite Pulumi CLI v3.243.0 ou plus récent, un pulumi login actif, et un rôle accordant resources:search (les rôles Member et Admin par défaut le font).

Étape 1 : récupérer le primer, toujours

pulumi whoami -v liste chaque organisation que la connexion peut atteindre. Demandez laquelle la question concerne plutôt que d'assumer l'organisation par défaut — c'est souvent un compte individuel sans droit d'accès.

pulumi api GetGraphSchema -F orgName=<org>

Cela retourne un guide autonome pour composer des sélecteurs — vocabulaire, types d'arête, capacités du moteur, exemples travaillés, pagination, règles d'exhaustivité, et les pièges qui produisent une réponse confiante mais fausse au lieu d'une erreur. Il est servi par le déploiement qui répond à vos requêtes, donc c'est le contrat, et il change entre les versions de schéma. Cette compétence vous y amorce et s'arrête là ; tout ce qui suit en dépend. Récupérez-le à neuf à chaque session et pour chaque org que vous interrogez — un primer mémorisé antérieurement peut décrire un schéma que ce déploiement ne sert plus.

Lisez-le en intégralité — ne le tronquez jamais avec head, tail, ou une limite d'octets. Un primer raccourci signifie des sélecteurs malformés et des requêtes rejetées.

Si cet appel échoue

Vous n'avez pas encore de primer, donc traitez-le ici plutôt que de le chercher ailleurs :

Signalez la barrière à l'utilisateur au lieu de réessayer quoi que ce soit sauf le 503. Si pulumi api ne connaît pas du tout GetGraphSchema, ce n'est pas une barrière : lancez pulumi api list --refresh-spec pour rafraîchir le spec en cache, puis réessayez la récupération.

Étape 2 : interroger

pulumi api GraphQuery -F orgName=<org> --input selector.json

Le corps est un sélecteur JSON, pas du texte de requête. Composez-le à partir du primer que vous venez de lire, pas de mémoire ou d'une grammaire que vous vous rappeliez d'une autre session.

Étape 3 : appliquer les règles d'exhaustivité du primer avant de répondre

Chaque réponse porte des signaux de fidélité — actuellement meta.resultMode, meta.visibility, et pageInfo.continuationToken ; le primer nomme l'ensemble autoritaire. Lisez les règles du primer pour eux et suivez-les ; les remèdes diffèrent par signal et une paraphrase obsolète ici serait pire qu'aucune.

Ce qui importe le plus : une affirmation d'exhaustivité a besoin qu'ils soient tous propres. L'analyse d'impact, « rien ne dépend de ceci », une liste de nettoyage exhaustive, un total entre groupes — aucun de ceux-ci ne survivent un résultat tronqué, une traversée élaguée, ou une page non vidée. Quand vous ne pouvez pas y arriver, dites ce que la réponse couvre.

Portée du graphe

Ressources, stacks, et les relations entre eux, filtrés aux stacks et comptes que l'appelant peut voir. La section « What it cannot answer yet » du primer est la limite active — vérifiez-la avant de conclure qu'une question est sans réponse, et ayez recours à une API différente plutôt que d'approximer une de ces lacunes avec une requête de graphe.

Une limite à connaître d'emblée, parce qu'elle décide quel API utiliser : le graphe retourne un sous-ensemble déclaré par schéma de champs par type de nœud, pas des sacs de propriétés complets. Le primer liste quels champs chaque type de nœud peut correspondre et lesquels il peut retourner ; quand la question a besoin des valeurs de propriété elles-mêmes, elles reviennent de Resource Search.

Référence lisible : Aperçu de l'API Context et guide de requête.