# Migrando IDs globais de nós do GraphQL

Saiba mais sobre os dois formatos de ID do nó global e como fazer a migração do formato de legado para o novo formato.

## Plano de fundo

A API GraphQL GitHub atualmente suporta dois tipos de formatos de ID de nó global. O formato herdado será encerrando e será substituído por um novo formato. Este guia mostra como fazer a migração para o novo formato, se necessário.

Ao fazer a migraçãopara o novo formato, você garante que os tempos de resposta dos seus pedidos permaneçam consistentes e pequenos. Você também garante que seu aplicativo continue funcionando depois que as IDs antigas forem encerrando.

Para saber mais sobre por que o formato de ID de nó global legado será encerrando, consulte [Novo formato de ID global disponível para o GraphQL](https://github.blog/2021-02-10-new-global-id-format-coming-to-graphql).

## Determinando se você precisa tomar medidas

Você só precisa seguir as etapas de migração se armazenar referências para os IDs de nó global do GraphQL. Essas IDs correspondem ao campo `id` de qualquer objeto no esquema. Se você não armazenar nenhuma ID de nó global, você poderá continuar interagindo com a API sem alterações.

Além disso, se você decodificar as IDs herdadas para extrair informações de tipo (por exemplo, se você usar os dois primeiros caracteres de `PR_kwDOAHz1OX4uYAah` para determinar se o objeto é uma solicitação de pull), seu serviço será interrompido, pois o formato das IDs mudou. Você deve migrar seu serviço para tratar esses IDs como strings opacas. Esses IDs serão únicos. Portanto, você pode confiar neles diretamente como referências.

## Fazendo a migração para os novos IDs globais

Para facilitar a migração para o novo formato de ID, você pode usar o cabeçalho `X-Github-Next-Global-ID` em suas solicitações de API do GraphQL. O valor do cabeçalho `X-Github-Next-Global-ID` pode ser `1` ou `0`. A definição do valor como `1` forçará o conteúdo de resposta a sempre usar o novo formato de ID em qualquer objeto para o qual você solicitou o campo `id`. A definição do valor como `0` reverterá isso para o comportamento padrão, que é mostrar a ID herdada ou a nova ID, dependendo da data de criação do objeto.

Aqui está um exemplo de solicitação usando um comando `curl`:

```shell
$ curl \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "X-Github-Next-Global-ID: 1" \
  https://api.github.com/graphql \
  -d '{ "query": "{ node(id: \"MDQ6VXNlcjM0MDczMDM=\") { id } }" }'
```

Embora a ID herdada `MDQ6VXNlcjM0MDczMDM=` tenha sido usada na consulta, a resposta conterá o novo formato de ID:

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

Com o cabeçalho `X-Github-Next-Global-ID`, você pode encontrar o novo formato de ID para IDs herdadas que você referencia em seu aplicativo. Você pode atualizar as referências com o ID recebido na resposta. Você deve atualizar todas as referências aos IDs legados e usar o novo formato de ID em todas as solicitações subsequentes à API.
Para executar operações em massa, você pode usar aliases para enviar várias consultas de nó em uma chamada de API. Para obter mais informações, confira [a documentação do GraphQL](https://graphql.org/learn/queries/#aliases).

Você também pode obter o novo ID para uma coleção de itens. Por exemplo, se você quiser obter o novo ID para os últimos 10 repositórios na sua organização, você poderia usar uma consulta como esta:

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

Observe que a configuração `X-Github-Next-Global-ID` para `1` afetará o valor retornado de cada campo `id` em sua consulta. Isso significa que, mesmo quando você enviar uma consulta não `node`, receberá de volta a nova ID de formato se tiver solicitado o campo `id`.

## Compartilhando feedback

Se tiver alguma dúvida sobre a implementação dessa alteração que afeta o seu aplicativo, entre em contato com o nos por meio do portal  e inclua informações como o nome do seu aplicativo para que possamos ajudá-lo melhor.