{"meta":{"title":"Script em API REST e JavaScript","intro":"Escreva um script usando o SDK do Octokit.js para interagir com a API REST.","product":"API REST","breadcrumbs":[{"href":"/pt/rest","title":"API REST"},{"href":"/pt/rest/guides","title":"Guias"},{"href":"/pt/rest/guides/scripting-with-the-rest-api-and-javascript","title":"Script com JavaScript"}],"documentType":"article"},"body":"# Script em API REST e JavaScript\n\nEscreva um script usando o SDK do Octokit.js para interagir com a API REST.\n\n## Sobre o Octokit.js\n\nSe você quiser escrever um script usando JavaScript para interagir com GitHuba API REST, GitHub recomenda que você use o SDK do Octokit.js. Octokit.js é mantido por GitHub. O SDK implementa as melhores práticas e facilita a interação com a API REST por meio do JavaScript. O Octokit.js funciona com todos os navegadores modernos, Node.js e Deno. Para obter mais informações sobre o Octokit.js, confira o arquivo [LEIAME do Octokit.js](https://github.com/octokit/octokit.js/#readme).\n\n## Pré-requisitos\n\nEste guia pressupõe que você esteja familiarizado com o JavaScript e a GitHub API REST. Para obter informações sobre a API REST, confira [Introdução à API REST](/pt/rest/using-the-rest-api/getting-started-with-the-rest-api).\n\nVocê precisa instalar e importar `octokit` para usar a biblioteca do Octokit.js. Este guia usa instruções de importação de acordo com o ES6. Para obter mais informações sobre diferentes métodos de instalação e importação, confira a seção de uso no README do Octokit.js.\n\n## Instanciação e autenticação\n\n> \\[!WARNING]\n> Trate suas credenciais de autenticação como uma senha.\n>\n> Para manter suas credenciais seguras, você pode armazená-las como um segredo e executar seu script por meio de GitHub Actions. Para saber mais, confira [Usar segredos em ações do GitHub](/pt/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets).\n\n> Você também pode armazenar suas credenciais como um segredo Codespaces e executar seu script em Codespaces. Para saber mais, confira [Gerenciando seus segredos específicos da conta no GitHub Codespaces](/pt/codespaces/managing-your-codespaces/managing-your-account-specific-secrets-for-github-codespaces).\n\n> Se essas opções não forem possíveis usar outro serviço da CLI para armazenar suas credenciais com segurança.\n\n### Autenticando com um personal access token\n\nSe você quiser usar a GitHub API REST para uso pessoal, poderá criar uma personal access token. Para obter mais informações sobre como criar um personal access token, consulte [Gerenciar seus tokens de acesso pessoal](/pt/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens).\n\nPrimeiro, importe `Octokit` de `octokit`. Depois, passe seu personal access token ao criar uma instância de `Octokit`. No exemplo a seguir, substitua `YOUR-TOKEN` por uma referência ao seu personal access token.\n\n```javascript copy\nimport { Octokit } from \"octokit\";\n\nconst octokit = new Octokit({ \n  auth: 'YOUR-TOKEN',\n});\n```\n\n### Autenticando com um GitHub App\n\nSe você quiser usar a API em nome de uma organização ou de outro usuário, GitHub recomenda que você use uma GitHub App. Se um endpoint estiver disponível para GitHub Apps, a documentação de referência REST desse endpoint indicará que tipo de token GitHub App é necessário. Para saber mais, confira [Registrando um aplicativo GitHub](/pt/apps/creating-github-apps/registering-a-github-app/registering-a-github-app) e [Sobre a autenticação com um aplicativo GitHub](/pt/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app).\n\nEm vez de importar `Octokit` de `octokit`, importe `App`. No exemplo a seguir, substitua `APP_ID` por uma referência à ID do seu aplicativo. Substitua `PRIVATE_KEY` por uma referência à chave privada do seu aplicativo. Substitua `INSTALLATION_ID` pela ID de instalação do seu aplicativo em nome do qual deseja se autenticar. Você pode encontrar a ID do seu aplicativo e gerar uma chave privada na página de configurações do aplicativo. Para saber mais, confira [Gerenciando chaves privadas para aplicativos GitHub](/pt/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps). Você pode obter uma ID de instalação com os pontos de extremidade `GET /users/{username}/installation`, `GET /repos/{owner}/{repo}/installation` ou `GET /orgs/{org}/installation`. Para obter mais informações, consulte [Pontos de extremidade da API REST para o GitHub Apps](/pt/rest/apps/apps).\n\n```javascript copy\nimport { App } from \"octokit\";\n\nconst app = new App({\n  appId: APP_ID,\n  privateKey: PRIVATE_KEY,\n});\n\nconst octokit = await app.getInstallationOctokit(INSTALLATION_ID);\n```\n\n### Autenticação em GitHub Actions\n\nSe você deseja usar a API em um GitHub Actions fluxo de trabalho, GitHub recomenda-se que você se autentique com o token integrado `GITHUB_TOKEN` em vez de criar um token. Você pode conceder permissões à `GITHUB_TOKEN` com a chave `permissions`. Para obter mais informações sobre `GITHUB_TOKEN`, confira [GITHUB\\_TOKEN](/pt/actions/concepts/security/github_token).\n\nSe o fluxo de trabalho precisar acessar recursos fora do repositório dele, então você não poderá usar `GITHUB_TOKEN`. Nesse caso, armazene suas credenciais como um segredo e substitua `GITHUB_TOKEN` nos exemplos abaixo pelo nome do segredo. Para saber mais sobre segredos, confira [Usar segredos em ações do GitHub](/pt/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets).\n\nSe você usar a palavra-chave `run` para executar seu script JavaScript nos seus fluxos de trabalho GitHub Actions, poderá armazenar o valor de `GITHUB_TOKEN` como uma variável de ambiente. Seu script pode acessar a variável de ambiente como `process.env.VARIABLE_NAME`.\n\nPor exemplo, essa etapa do fluxo de trabalho armazena `GITHUB_TOKEN` em uma variável de ambiente chamada `TOKEN`:\n\n```yaml\n- name: Run script\n  env:\n    TOKEN: ${{ secrets.GITHUB_TOKEN }}\n  run: |\n    node .github/actions-scripts/use-the-api.mjs\n```\n\nO script que o fluxo de trabalho executa usa `process.env.TOKEN` para se autenticar:\n\n```javascript copy\nimport { Octokit } from \"octokit\";\n\nconst octokit = new Octokit({ \n  auth: process.env.TOKEN,\n});\n```\n\n### Instanciação sem autenticação\n\nVocê pode usar a API REST sem autenticação, embora isso resulte em uma limitação de taxa mais baixa e não permita o uso de alguns endpoints. Para criar uma instância de `Octokit` sem autenticação, não passe o argumento `auth`.\n\n```javascript copy\nimport { Octokit } from \"octokit\";\n\nconst octokit = new Octokit({ );\n```\n\n## Como fazer solicitações\n\nO Octokit dá suporte a várias maneiras de fazer solicitações. Você pode usar o método `request` para fazer solicitações se souber o verbo HTTP e o caminho para o ponto de extremidade. Você pode usar o método `rest` se quiser aproveitar o preenchimento automático em seu IDE e digitar. Para pontos de extremidade paginados, você pode usar o método `paginate` para solicitar várias páginas de dados.\n\n### Como usar o método `request` para fazer solicitações\n\nPara usar o método `request` a fim de fazer solicitações, passe o método HTTP e o caminho como o primeiro argumento. Passe quaisquer parâmetros de corpo, consulta ou caminho em um objeto como o segundo argumento. Por exemplo, para fazer uma solicitação `GET` para `/repos/{owner}/{repo}/issues` e passar os parâmetros `owner`, `repo` e `per_page`:\n\n```javascript copy\nawait octokit.request(\"GET /repos/{owner}/{repo}/issues\", {\n  owner: \"github\",\n  repo: \"docs\",\n  per_page: 2\n});\n```\n\nO método `request` passa automaticamente o cabeçalho `Accept: application/vnd.github+json`. Para passar cabeçalhos adicionais ou um cabeçalho `Accept` diferente, adicione uma propriedade `headers` ao objeto que é passado como o segundo argumento. O valor da propriedade `headers` é um objeto onde os nomes dos cabeçalhos são as chaves e os valores correspondentes são os valores. Por exemplo, para enviar um cabeçalho `content-type` com o valor de `text/plain` e um cabeçalho `x-github-api-version` com o valor de `2026-03-10`:\n\n```javascript copy\nawait octokit.request(\"POST /markdown/raw\", {\n  text: \"Hello **world**\",\n  headers: {\n    \"content-type\": \"text/plain\",\n    \"x-github-api-version\": \"2026-03-10\",\n  },\n});\n```\n\n### Como usar métodos endpoint `rest` para fazer solicitações\n\nCada ponto de extremidade da API REST tem um método de ponto de extremidade `rest` associado no Octokit. Esses métodos geralmente são preenchidos automaticamente em seu IDE para conveniência. Você pode passar qualquer parâmetro como um objeto para o método.\n\n```javascript copy\nawait octokit.rest.issues.listForRepo({\n  owner: \"github\",\n  repo: \"docs\",\n  per_page: 2\n});\n```\n\nAlém disso, se estiver usando uma linguagem tipada, como TypeScript, você poderá importar tipos para usar com esses métodos. Para obter mais informações, confira a [seção de TypeScript no README do plugin-rest-endpoint-methods.js](https://github.com/octokit/plugin-rest-endpoint-methods.js/#typescript).\n\n### Como fazer solicitações paginadas\n\nSe o endpoint for paginado e você quiser recuperar mais de uma página de resultados, poderá usar o método `paginate`.\n`paginate` buscará a próxima página de resultados até chegar à última página e retornará todos os resultados como uma única matriz. Alguns pontos de extremidade retornam resultados paginados como matriz em um objeto, em vez de retornar os resultados paginados como uma matriz.\n`paginate` sempre retorna uma matriz de itens, mesmo que o resultado bruto tenha sido um objeto .\n\nPor exemplo, o exemplo a seguir obtém todos os problemas do repositório `github/docs`. Embora solicite 100 solicitações por vez, a função não retornará até que a última página de dados seja atingida.\n\n```javascript copy\nconst issueData = await octokit.paginate(\"GET /repos/{owner}/{repo}/issues\", {\n  owner: \"github\",\n  repo: \"docs\",\n  per_page: 100,\n  headers: {\n    \"x-github-api-version\": \"2026-03-10\",\n  },\n});\n```\n\nO método `paginate` aceita uma função de mapa opcional, que pode ser usada para coletar apenas os dados desejados da resposta. Isso reduz o uso de memória pelo seu script. A função de mapa pode usar um segundo argumento, `done`, que pode ser chamado para encerrar a paginação antes que a última página seja alcançada. Isso permite que você busque um subconjunto de páginas. Por exemplo, o exemplo a seguir continua buscando resultados até que seja retornada uma questão que inclua \"teste\" no título. Para as páginas de dados que foram retornadas, apenas o título e o autor da questão são armazenados.\n\n```javascript copy\nconst issueData = await octokit.paginate(\"GET /repos/{owner}/{repo}/issues\", {\n  owner: \"github\",\n  repo: \"docs\",\n  per_page: 100,\n  headers: {\n    \"x-github-api-version\": \"2026-03-10\",\n  },\n},\n    (response, done) => response.data.map((issue) => {\n    if (issue.title.includes(\"test\")) {\n      done()\n    }\n    return ({title: issue.title, author: issue.user.login})\n  })\n);\n```\n\nEm vez de buscar todos os resultados de uma só vez, você pode usar `octokit.paginate.iterator()` para percorrer uma só página de cada vez. Por exemplo, o caso a seguir busca uma página de resultados por vez e processa cada objeto da página atual antes de buscar a próxima. Uma vez encontrado um problema com \"teste\" no título, o script interrompe a iteração e retorna o título e o autor do problema de cada objeto que foi processado. O iterador é o método mais eficiente em termos de memória para buscar dados paginados.\n\n```javascript copy\nconst iterator = octokit.paginate.iterator(\"GET /repos/{owner}/{repo}/issues\", {\n  owner: \"github\",\n  repo: \"docs\",\n  per_page: 100,\n  headers: {\n    \"x-github-api-version\": \"2026-03-10\",\n  },\n});\n\nlet issueData = []\nlet breakLoop = false\nfor await (const {data} of iterator) {\n  if (breakLoop) break\n  for (const issue of data) {\n    if (issue.title.includes(\"test\")) {\n      breakLoop = true\n      break\n    } else {\n      issueData = [...issueData, {title: issue.title, author: issue.user.login}];\n    }\n  }\n}\n```\n\nVocê também pode usar o método `paginate` com os métodos de endpoint `rest`. Passe o método de ponto de extremidade `rest` como o primeiro argumento. Passe todos os demais parâmetros como o segundo argumento.\n\n```javascript copy\nconst iterator = octokit.paginate.iterator(octokit.rest.issues.listForRepo, {\n  owner: \"github\",\n  repo: \"docs\",\n  per_page: 100,\n  headers: {\n    \"x-github-api-version\": \"2026-03-10\",\n  },\n});\n```\n\nPara saber mais sobre a paginação, confira [Como usar paginação na API REST](/pt/rest/using-the-rest-api/using-pagination-in-the-rest-api).\n\n## Captura de erros\n\n### Capturando todos os erros\n\nÀs vezes, a GitHub API REST retornará um erro. Por exemplo, um erro será exibido se o token de acesso tiver expirado ou se um parâmetro obrigatório for omitido. O Octokit.js faz automaticamente novas tentativas de executar a solicitação quando obtém um erro diferente de `400 Bad Request`, `401 Unauthorized`, `403 Forbidden`, `404 Not Found` ou `422 Unprocessable Entity`. Se ocorrer um erro de API mesmo após novas tentativas, o Octokit.js gera um erro que inclui o código de status HTTP da resposta (`response.status`) e os cabeçalhos da resposta (`response.headers`). Você deve tratar esses erros em seu código. Por exemplo, você pode usar um bloco try/catch para capturar erros:\n\n```javascript copy\nlet filesChanged = []\n\ntry {\n  const iterator = octokit.paginate.iterator(\"GET /repos/{owner}/{repo}/pulls/{pull_number}/files\", {\n    owner: \"github\",\n    repo: \"docs\",\n    pull_number: 22809,\n    per_page: 100,\n    headers: {\n      \"x-github-api-version\": \"2026-03-10\",\n    },\n  });\n\n  for await (const {data} of iterator) {\n    filesChanged = [...filesChanged, ...data.map(fileData => fileData.filename)];\n  }\n} catch (error) {\n  if (error.response) {\n    console.error(`Error! Status: ${error.response.status}. Message: ${error.response.data.message}`)\n  }\n  console.error(error)\n}\n```\n\n### Tratamento de códigos de erro previstos\n\nÀs vezes, GitHub usa um código de status 4xx para indicar uma resposta sem erro. Se o endpoint que você está usando fizer isso, você poderá adicionar tratamento adicional para erros específicos. Por exemplo, o endpoint `GET /user/starred/{owner}/{repo}` retornará `404` se o repositório não estiver marcado com estrela. O exemplo a seguir usa a resposta `404` para indicar que o repositório não foi estrelado; todos os demais códigos de erros são tratados como erros.\n\n```javascript copy\ntry {\n  await octokit.request(\"GET /user/starred/{owner}/{repo}\", {\n    owner: \"github\",\n    repo: \"docs\",\n    headers: {\n      \"x-github-api-version\": \"2026-03-10\",\n    },\n  });\n\n  console.log(`The repository is starred by me`);\n\n} catch (error) {\n  if (error.status === 404) {\n    console.log(`The repository is not starred by me`);\n  } else {\n    console.error(`An error occurred while checking if the repository is starred: ${error?.response?.data?.message}`);\n  }\n}\n```\n\n### Tratamento de erros de limite de taxa\n\nSe você receber um erro de limite de taxa, talvez seja necessário repetir a solicitação após aguardar um tempo. Quando houver limitação de taxa, GitHub retornará um erro `403 Forbidden` e o valor do cabeçalho de resposta `x-ratelimit-remaining` será `\"0\"`. Os cabeçalhos de resposta incluirão um cabeçalho `x-ratelimit-reset`, que informa a hora em que a janela de limite de taxa atual é redefinida, em segundos UTC. Você pode repetir a solicitação após aguardar o tempo especificado por `x-ratelimit-reset`.\n\n```javascript copy\nasync function requestRetry(route, parameters) {\n  try {\n    const response = await octokit.request(route, parameters);\n    return response\n  } catch (error) {\n    if (error.response && error.status === 403 && error.response.headers['x-ratelimit-remaining'] === '0') {\n      const resetTimeEpochSeconds = error.response.headers['x-ratelimit-reset'];\n      const currentTimeEpochSeconds = Math.floor(Date.now() / 1000);\n      const secondsToWait = resetTimeEpochSeconds - currentTimeEpochSeconds;\n      console.log(`You have exceeded your rate limit. Retrying in ${secondsToWait} seconds.`);\n      setTimeout(requestRetry, secondsToWait * 1000, route, parameters);\n    } else {\n      console.error(error);\n    }\n  }\n}\n\nconst response = await requestRetry(\"GET /repos/{owner}/{repo}/issues\", {\n    owner: \"github\",\n    repo: \"docs\",\n    per_page: 2\n  })\n```\n\n## Como usar a resposta\n\nO método `request` retorna uma promessa que será resolvida para um objeto se a solicitação for bem-sucedida. As propriedades do objeto são `data` (o corpo da resposta retornado pelo ponto de extremidade), `status` (o código da resposta HTTP), `url` (a URL da solicitação) e `headers` (um objeto que contém os cabeçalhos da resposta). A menos que especificado de outra forma, o corpo da resposta está no formato JSON. Alguns endpoints não retornam um corpo de resposta; nesses casos, a propriedade `data` é omitida.\n\n```javascript copy\nconst response = await octokit.request(\"GET /repos/{owner}/{repo}/issues/{issue_number}\", {\n  owner: \"github\",\n  repo: \"docs\",\n  issue_number: 11901,\n  headers: {\n    \"x-github-api-version\": \"2026-03-10\",\n  },\n});\n\nconsole.log(`The status of the response is: ${response.status}`)\nconsole.log(`The request URL was: ${response.url}`)\nconsole.log(`The x-ratelimit-remaining response header is: ${response.headers[\"x-ratelimit-remaining\"]}`)\nconsole.log(`The issue title is: ${response.data.title}`)\n```\n\nDa mesma forma, o método `paginate` retorna uma promessa. Se a solicitação tiver sido bem-sucedida, a promessa será resolvida para uma matriz de dados retornada pelo ponto de extremidade. Ao contrário do método `request`, o método `paginate` não retorna o código de status, a URL ou os cabeçalhos.\n\n```javascript copy\nconst data = await octokit.paginate(\"GET /repos/{owner}/{repo}/issues\", {\n  owner: \"github\",\n  repo: \"docs\",\n  per_page: 100,\n  headers: {\n    \"x-github-api-version\": \"2026-03-10\",\n  },\n});\n\nconsole.log(`${data.length} issues were returned`)\nconsole.log(`The title of the first issue is: ${data[0].title}`)\n```\n\n## Script de exemplo\n\nAqui está um script de exemplo completo que usa o Octokit.js. O script importa `Octokit` e cria uma instância de `Octokit`. Se você quisesse autenticar com um GitHub App em vez de um personal access token, importaria e instanciaria `App` em vez de `Octokit`. Para obter mais informações, consulte [Como autenticar com um GitHub App](#authenticating-with-a-github-app).\n\nA função `getChangedFiles` obtém todos os arquivos alterados para uma solicitação de pull. A função `commentIfDataFilesChanged` chama a função `getChangedFiles`. Se qualquer um dos arquivos que a solicitação de pull alterou incluir `/data/` no caminho, a função comentará sobre a solicitação de pull.\n\n```javascript copy\nimport { Octokit } from \"octokit\";\n\nconst octokit = new Octokit({ \n  auth: 'YOUR-TOKEN',\n});\n\nasync function getChangedFiles({owner, repo, pullNumber}) {\n  let filesChanged = []\n\n  try {\n    const iterator = octokit.paginate.iterator(\"GET /repos/{owner}/{repo}/pulls/{pull_number}/files\", {\n      owner: owner,\n      repo: repo,\n      pull_number: pullNumber,\n      per_page: 100,\n      headers: {\n        \"x-github-api-version\": \"2026-03-10\",\n      },\n    });\n\n    for await (const {data} of iterator) {\n      filesChanged = [...filesChanged, ...data.map(fileData => fileData.filename)];\n    }\n  } catch (error) {\n    if (error.response) {\n      console.error(`Error! Status: ${error.response.status}. Message: ${error.response.data.message}`)\n    }\n    console.error(error)\n  }\n\n  return filesChanged\n}\n\nasync function commentIfDataFilesChanged({owner, repo, pullNumber}) {\n  const changedFiles = await getChangedFiles({owner, repo, pullNumber});\n\n  const filePathRegex = new RegExp(/\\/data\\//, \"i\");\n  if (!changedFiles.some(fileName => filePathRegex.test(fileName))) {\n    return;\n  }\n\n  try {\n    const {data: comment} = await octokit.request(\"POST /repos/{owner}/{repo}/issues/{issue_number}/comments\", {\n      owner: owner,\n      repo: repo,\n      issue_number: pullNumber,\n      body: `It looks like you changed a data file. These files are auto-generated. \\n\\nYou must revert any changes to data files before your pull request will be reviewed.`,\n      headers: {\n        \"x-github-api-version\": \"2026-03-10\",\n      },\n    });\n\n    return comment.html_url;\n  } catch (error) {\n    if (error.response) {\n      console.error(`Error! Status: ${error.response.status}. Message: ${error.response.data.message}`)\n    }\n    console.error(error)\n  }\n}\n\nawait commentIfDataFilesChanged({owner: \"github\", repo: \"docs\", pullNumber: 191});\n```\n\n## Próximas etapas\n\n* Para saber mais sobre o Octokit.js, confira a [documentação do Octokit.js](https://github.com/octokit/octokit.js/#readme).\n* Para ver alguns exemplos práticos, veja como o GitHub Docs usa o Octokit.js [pesquisando no GitHub repositório do Docs](https://github.com/search?q=repo%3Agithub%2Fdocs%20path%3A.github%20octokit\\&type=code)."}