Background
L’API GitHub GraphQL prend actuellement en charge deux types de formats d’ID de nœud globaux. L’ancien format sera en cours de clôture et remplacé par un nouveau format. Ce guide vous montre comment migrer vers le nouveau format, si nécessaire.
En migrant vers le nouveau format, vous vous garantissez que les temps de réponse de vos demandes restent cohérents et petits. Vous vous assurez également que votre application continue de fonctionner une fois que les anciens identifiants sont en cours de clôture.
Pour en savoir plus sur la raison pour laquelle le format d’ID de nœud global hérité sera en cours de clôture, consultez Nouveau format d’ID global disponible dans GraphQL.
Déterminer si vous devez prendre des mesures
Vous devez uniquement suivre les étapes de migration si vous stockez des références aux ID de nœud globaux GraphQL. Ces ID correspondent au champ id de tout objet du schéma. Si vous ne stockez pas d’ID de nœud global, vous pouvez continuer à interagir avec l’API sans modification.
En outre, si vous décodez actuellement les ID hérités pour extraire des informations sur les types (par exemple, si vous utilisez les deux premiers caractères de PR_kwDOAHz1OX4uYAah pour déterminer si l’objet est un pull request), votre service se cassera car le format des ID a changé. Vous devez migrer votre service pour traiter ces ID comme des chaînes opaques. Ces ID seront uniques. Par conséquent, vous pouvez vous appuyer directement dessus comme références.
Migration vers les nouveaux ID globaux
Pour faciliter la migration vers le nouveau format d’ID, vous pouvez utiliser l’en-tête X-Github-Next-Global-ID dans vos demandes d’API GraphQL. La valeur de l’en-tête X-Github-Next-Global-ID peut être 1 ou 0. Définir la valeur sur 1 force la charge utile de réponse à toujours utiliser le nouveau format d’ID pour tout objet pour lequel vous avez demandé le champ id. Définir la valeur sur 0 rétablit le comportement par défaut, qui consiste à afficher l’ID hérité ou le nouvel ID en fonction de la date de création de l’objet.
Voici un exemple de demande à l’aide d’une commande curl :
$ curl \
-H "Authorization: Bearer $GITHUB_TOKEN" \
-H "X-Github-Next-Global-ID: 1" \
https://api.github.com/graphql \
-d '{ "query": "{ node(id: \"MDQ6VXNlcjM0MDczMDM=\") { id } }" }'
Même si l’ID hérité MDQ6VXNlcjM0MDczMDM= a été utilisé dans la requête, la réponse contient le nouveau format d’ID :
{"data":{"node":{"id":"U_kgDOADP9xw"}}}
Avec l’en-tête X-Github-Next-Global-ID, vous trouverez le nouveau format d’ID pour les ID hérités que vous référencez dans votre application. Vous pouvez ensuite mettre à jour ces références avec l’ID reçu dans la réponse. Vous devez mettre à jour toutes les références aux ID hérités et utiliser le nouveau format d’ID pour toutes les demandes suivantes à l’API.
Pour effectuer des opérations en bloc, vous pouvez utiliser des alias pour envoyer plusieurs requêtes de nœud dans un appel d’API. Pour plus d’informations, consultez la documentation GraphQL.
Vous pouvez également obtenir le nouvel ID pour une collection d’éléments. Par exemple, si vous souhaitez obtenir le nouvel ID pour les 10 derniers dépôts de votre organisation, vous pouvez utiliser une requête comme celle-ci :
{
organization(login: "github") {
repositories(last: 10) {
edges {
cursor
node {
name
id
}
}
}
}
}
Notez que le paramètre X-Github-Next-Global-ID sur 1 affecte la valeur de retour de chaque champ id dans votre requête. Cela signifie que même lorsque vous envoyez une requête non node, vous obtenez le nouvel ID de format si vous avez demandé le champ id.
Partage de commentaires
Si vous avez des préoccupations concernant le lancement de ce changement qui a un impact sur votre application, veuillez contacter nous via le portail de support GitHub et incluez des informations telles que le nom de votre application pour que nous puissions vous aider au mieux.