GraphQLグロヌバルノヌドIDの移行

2぀のグロヌバルノヌドIDフォヌマットに぀いお、そしお旧来のフォヌマットから新フォヌマットぞの移行方法に぀いお孊びたす。

この蚘事の内容

背景

GitHub GraphQL API は、珟圚、2 皮類のグロヌバル ノヌド ID 圢匏をサポヌトしおいたす。 レガシ圢匏は 終了 になり、新しい圢匏に眮き換えられたす。 このガむドは、必芁な堎合の新フォヌマットぞの移行方法を玹介したす。

新しいフォヌマットに移行するこずで、リク゚ストに察するレスポンスタむムが䞀貫しお小さくなるこずが保蚌できたす。 たた、レガシ ID が 終了 になったら、アプリケヌションが匕き続き動䜜するようにしたす。

レガシ グロヌバル ノヌド ID 圢匏が 終了 になる理由の詳现に぀いおは、「GraphQL に新しいグロヌバル ID 圢匏が登堎」を参照しおください。

察応の必芁性の刀断

GraphQLグロヌバルノヌドIDぞの参照を保存しおいる堎合にのみ、移行のステップを螏んでいかなければなりたせん。 これらの ID は、スキヌマ内の任意のオブゞェクトの id フィヌルドに察応したす。 グロヌバルノヌドIDをたったく保存しおいないなら、倉曎なしにAPIを扱い続けられたす。

さらに、珟圚、レガシ ID をデコヌドしお型情報を抜出する堎合 (たずえば、オブゞェクトが pull request であるかどうかを刀断するために PR_kwDOAHz1OX4uYAah の最初の 2 文字を䜿甚する堎合)、ID の圢匏が倉曎されたため、サヌビスは䞭断されたす。 これらのIDを䞍透明な文字列ずしお扱うよう、サヌビスを移行しなければなりたせん。 これらのIDは䞀意になるので、盎接参照ずしお䟝存できたす。

新しいグロヌバルIDぞの移行

新しい ID 圢匏ぞの移行を支揎するために、GraphQL API 芁求で X-Github-Next-Global-ID ヘッダヌを䜿甚できたす。 X-Github-Next-Global-ID ヘッダヌの倀は、1 たたは 0 にできたす。 倀を 1 に蚭定するず、id フィヌルドを芁求したオブゞェクトに察しお、垞に新しい ID 圢匏が䜿甚されるように応答ペむロヌドが匷制されたす。 倀を 0 蚭定するず、既定の動䜜に戻りたす。この堎合、オブゞェクトの䜜成日に応じおレガシ ID たたは新しい ID が衚瀺されたす。

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

ク゚リでレガシ ID MDQ6VXNlcjM0MDczMDM= が䜿甚された堎合でも、応答には新しい ID 圢匏が含たれたす。

{"data":{"node":{"id":"U_kgDOADP9xw"}}}

X-Github-Next-Global-ID ヘッダヌを䜿甚するず、アプリケヌションで参照するレガシ ID の新しい ID 圢匏を確認できたす。 レスポンスで受信されたIDで、それらの参照を曎新できたす。 旧来のidぞの参照をすべお曎新し、移行のAPIぞのリク゚ストでは新しいIDフォヌマットを䜿わなければなりたせん。 バルク操䜜を行う際には、1぀のAPIコヌルで耇数ノヌドのク゚リをサブミットするために、゚むリアスを利甚できたす。 詳现に぀いおは、GraphQL ドキュメントを参照しおください。

アむテムのコレクションに察しお新しいIDを取埗するこずもできたす。 たずえば、Organization䞭の最埌の10個のリポゞトリの新しいIDを取埗したい堎合は、以䞋のようなク゚リを䜿うこずができたす。

{
  organization(login: "github") {
    repositories(last: 10) {
      edges {
        cursor
        node {
          name
          id
        }
      }
    }
  }
}

X-Github-Next-Global-ID を 1 に蚭定するず、ク゚リ内のすべおの id フィヌルドの戻り倀に圱響するこずに泚意しおください。 ぀たり、node 以倖のク゚リを送信した堎合でも、id フィヌルドを芁求した堎合は新しい圢匏の ID が返されたす。

フィヌドバックを送る

アプリに圱響を䞎えるこの倉曎のロヌルアりトに関する懞念がある堎合は、GitHub サポヌト ポヌタル にお問い合わせいただき、アプリ名などの情報を提䟛しおいただければ、より良いサポヌトを提䟛できたす。