Скриптирование с помощью REST API и JavaScript

Напишите скрипт с помощью пакета SDK Octokit.js для взаимодействия с REST API.

В этой статье

О Octokit.js

Если вы хотите написать скрипт с помощью JavaScript для взаимодействия с REST API GitHub, GitHub рекомендует использовать пакет SDK Octokit.js. Octokit.js поддерживается GitHub. Пакет SDK реализует рекомендации и упрощает взаимодействие с REST API с помощью JavaScript. Octokit.js работает со всеми современными браузерами, Node.js и Deno. Дополнительные сведения о Octokit.js см . в Octokit.js README.

Необходимые компоненты

В этом руководстве предполагается, что вы знакомы с JavaScript и REST API GitHub REST API. Дополнительные сведения о REST API см. в разделе Начало работы с REST API.

Чтобы использовать библиотеку Octokit.js, необходимо установить и импортировать octokit ее. В этом руководстве используются инструкции импорта в соответствии с ES6. Дополнительные сведения о различных методах установки и импорта см . в разделе об использовании Octokit.js README.

Создание экземпляров и проверка подлинности

Warning

Обработайте учетные данные проверки подлинности как пароль.

Чтобы обеспечить безопасность учетных данных, вы можете хранить свои учетные данные в виде секрета и запускать скрипт с помощью GitHub Actions. Дополнительные сведения см. в разделе Использование секретов в GitHub Actions.

Вы также можете хранить свои учетные данные в виде секрета Codespaces и запустить скрипт в Codespaces. Дополнительные сведения см. в разделе Управление секретами конкретной учетной записи для GitHub Codespaces.

Если эти параметры недоступны, попробуйте использовать другую службу CLI для безопасного хранения учетных данных.

Проверка подлинности с помощью personal access token

Если вы хотите использовать REST API GitHub для личного использования, можно создать personal access token. Дополнительные сведения о создании personal access tokenсм. в разделе Управление личными маркерами доступа.

Сначала импортируйте Octokit из octokit. Затем передайте personal access token при создании экземпляра Octokit. В следующем примере замените YOUR-TOKEN ссылку на данные personal access token.{ %ifversion ghes %} Замените HOSTNAME именем GitHub.com.{ % endif %}

JavaScript
import { Octokit } from "octokit";

const octokit = new Octokit({ 
  auth: 'YOUR-TOKEN',
});

Проверка подлинности с помощью GitHub App

Если вы хотите использовать API от имени организации или другого пользователя, GitHub рекомендует использовать GitHub App. Если конечная точка доступна для GitHub Apps, справочная документация REST для этой конечной точки будет указывать тип маркера GitHub App. Дополнительные сведения см. в разделе [AUTOTITLE и Регистрация приложения GitHub](/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app).

Вместо импорта Octokit из octokit, импорта App. В следующем примере замените APP_ID ссылку на идентификатор приложения. Замените PRIVATE_KEY ссылкой на закрытый ключ приложения. Замените INSTALLATION_ID идентификатором установки приложения, от имени которого требуется выполнить проверку подлинности. Идентификатор приложения можно найти и создать закрытый ключ на странице параметров приложения. Дополнительные сведения см. в разделе Управление закрытыми ключами для приложений GitHub. Идентификатор установки можно получить с GET /users/{username}/installationпомощью конечных точек или GET /orgs/{org}/installation конечных GET /repos/{owner}/{repo}/installationточек. Дополнительные сведения см. в разделе Конечные точки REST API для GitHub Apps.{ %ifversion ghes %} Замените HOSTNAME именем GitHub.com.{ % endif %}

JavaScript
import { App } from "octokit";

const app = new App({
  appId: APP_ID,
  privateKey: PRIVATE_KEY,
});

const octokit = await app.getInstallationOctokit(INSTALLATION_ID);

Проверка подлинности в GitHub Actions

Если вы хотите использовать API в рабочем процессе GitHub Actions, GitHub рекомендует выполнять проверку подлинности с помощью встроенного GITHUB_TOKEN вместо создания маркера. Вы можете предоставить разрешения для GITHUB_TOKEN с помощью ключа permissions. Дополнительные сведения см. в GITHUB_TOKENразделе Автоматическая проверка подлинности токенов.

Если рабочий процесс должен получить доступ к ресурсам за пределами репозитория рабочего процесса, вы не сможете использовать GITHUB_TOKEN. В этом случае сохраните свои учетные данные в виде секрета и замените GITHUB_TOKEN в приведенных ниже примерах именем секрета. Дополнительные сведения о секретах см. в разделе Использование секретов в GitHub Actions.

Если вы используете ключевое run слово для выполнения скрипта JavaScript в рабочих процессах GitHub Actions, можно сохранить значение GITHUB_TOKEN в качестве переменной среды. Скрипт может получить доступ к переменной среды как process.env.VARIABLE_NAME.

Например, этот шаг рабочего процесса сохраняется GITHUB_TOKEN в переменной среды:TOKEN

- name: Run script
  env:
    TOKEN: ${{ secrets.GITHUB_TOKEN }}
  run: |
    node .github/actions-scripts/use-the-api.mjs

Скрипт, который process.env.TOKEN выполняется рабочим процессом для проверки подлинности:

JavaScript
import { Octokit } from "octokit";

const octokit = new Octokit({ 
  auth: process.env.TOKEN,
});

Создание экземпляров без проверки подлинности

REST API можно использовать без проверки подлинности, хотя у вас будет более низкий предел скорости и не удастся использовать некоторые конечные точки. Чтобы создать экземпляр Octokit без проверки подлинности, не передайте auth аргумент.{ %ifversion ghes %} Задайте базовый URL-адрес https://api.github.com. Замените [hostname] именем GitHub.com.{ % endif %}

JavaScript
import { Octokit } from "octokit";

const octokit = new Octokit({ });

Выполнение запросов

Octokit поддерживает несколько способов выполнения запросов. Метод можно использовать request для выполнения запросов, если вы знаете HTTP-команду и путь к конечной точке. Этот метод можно использовать, если вы хотите воспользоваться rest преимуществами автозаполнения в интегрированной среде разработки и вводе. Для конечных точек с разбивкой на страницы можно использовать paginate метод для запроса нескольких страниц данных.

request Использование метода для выполнения запросов

Чтобы использовать метод для выполнения запросов, передайте request метод HTTP и путь в качестве первого аргумента. Передайте все параметры текста, запроса или пути в объект в качестве второго аргумента. Например, чтобы выполнить GET запрос к /repos/{owner}/{repo}/issues и передать параметрыrepo``owner, и per_page выполнить следующие параметры:

JavaScript
await octokit.request("GET /repos/{owner}/{repo}/issues", {
  owner: "github",
  repo: "docs",
  per_page: 2
});

Метод request автоматически передает Accept: application/vnd.github+json заголовок. Чтобы передать дополнительные заголовки или другой Accept заголовок, добавьте headers свойство в объект, передаваемый в качестве второго аргумента. Значение свойства headers — это объект с именами заголовков в качестве ключей и значениями заголовков в качестве значений. Например, чтобы отправить content-type заголовок со значением text/plain и x-github-api-version заголовком со значением 2022-11-28:

JavaScript
await octokit.request("POST /markdown/raw", {
  text: "Hello **world**",
  headers: {
    "content-type": "text/plain",
    "x-github-api-version": "2022-11-28",
  },
});

Использование rest методов конечной точки для выполнения запросов

Каждая конечная точка REST API имеет связанный rest метод конечной точки в Octokit. Эти методы обычно автоматически заполняются в интегрированной среде разработки для удобства. В метод можно передать любые параметры в качестве объекта.

JavaScript
await octokit.rest.issues.listForRepo({
  owner: "github",
  repo: "docs",
  per_page: 2
});

Кроме того, если используется типизированный язык, например TypeScript, можно импортировать типы для использования с этими методами. Дополнительные сведения см . в разделе TypeScript в plugin-rest-endpoint-methods.js README.

Выполнение запросов с разбивкой на страницы

Если конечная точка разбина на страницы и вы хотите получить несколько страниц результатов, можно использовать paginate этот метод. paginate Возвращает следующую страницу результатов, пока не достигнет последней страницы, а затем возвращает все результаты в виде одного массива. Несколько конечных точек возвращают результаты с разбивкой на страницы в виде массива в объекте, а не возвращать результаты с разбивкой на страницы в виде массива. paginate всегда возвращает массив элементов, даже если необработанный результат был объектом.

Например, следующий пример получает все проблемы из github/docs репозитория. Хотя она запрашивает 100 проблем за раз, функция не возвращается до достижения последней страницы данных.

JavaScript
const issueData = await octokit.paginate("GET /repos/{owner}/{repo}/issues", {
  owner: "github",
  repo: "docs",
  per_page: 100,
  headers: {
    "x-github-api-version": "2022-11-28",
  },
});

Метод paginate принимает необязательную функцию карты, которую можно использовать для сбора только нужных данных из ответа. Это сокращает использование памяти скриптом. Функция карты может принимать второй аргумент, doneкоторый можно вызвать для завершения разбиения на страницы до достижения последней страницы. Это позволяет получить подмножество страниц. Например, следующий пример продолжает получение результатов до тех пор, пока не будет возвращена проблема, содержащая "test" в заголовке. Для страниц возвращаемых данных хранятся только название проблемы и автор.

JavaScript
const issueData = await octokit.paginate("GET /repos/{owner}/{repo}/issues", {
  owner: "github",
  repo: "docs",
  per_page: 100,
  headers: {
    "x-github-api-version": "2022-11-28",
  },
},
    (response, done) => response.data.map((issue) => {
    if (issue.title.includes("test")) {
      done()
    }
    return ({title: issue.title, author: issue.user.login})
  })
);

Вместо одновременного получения всех результатов можно использовать octokit.paginate.iterator() для итерации по одной странице за раз. Например, следующий пример извлекает одну страницу результатов за раз и обрабатывает каждый объект из страницы перед получением следующей страницы. После достижения проблемы, включающей "test" в заголовок, скрипт останавливает итерацию и возвращает заголовок проблемы и автор проблемы каждого обработанного объекта. Итератор — это наиболее эффективный метод памяти для получения данных с разбивкой на страницы.

JavaScript
const iterator = octokit.paginate.iterator("GET /repos/{owner}/{repo}/issues", {
  owner: "github",
  repo: "docs",
  per_page: 100,
  headers: {
    "x-github-api-version": "2022-11-28",
  },
});

let issueData = []
let breakLoop = false
for await (const {data} of iterator) {
  if (breakLoop) break
  for (const issue of data) {
    if (issue.title.includes("test")) {
      breakLoop = true
      break
    } else {
      issueData = [...issueData, {title: issue.title, author: issue.user.login}];
    }
  }
}

Этот paginate метод также можно использовать с методами конечной rest точки. Передайте метод конечной rest точки в качестве первого аргумента. Передайте все параметры в качестве второго аргумента.

JavaScript
const iterator = octokit.paginate.iterator(octokit.rest.issues.listForRepo, {
  owner: "github",
  repo: "docs",
  per_page: 100,
  headers: {
    "x-github-api-version": "2022-11-28",
  },
});

Дополнительные сведения о разбиении на страницы см. в разделе Использование разбиения на страницы в REST API.

выявления ошибок;

Перехват всех ошибок

Иногда REST API GitHub возвращает ошибку. Например, вы получите ошибку, если срок действия маркера доступа истек или если не указан обязательный параметр. Octokit.js автоматически повторяет запрос при получении ошибки, отличной от 400 Bad Request, 401 Unauthorized, 403 Forbiddenи 404 Not Found.422 Unprocessable Entity Если ошибка API возникает даже после повторных попыток, Octokit.js выдает ошибку, содержащую код состояния HTTP ответа (response.status) и заголовки ответа (response.headers). Эти ошибки следует обрабатывать в коде. Например, для перехвата ошибок можно использовать блок try/catch:

JavaScript
let filesChanged = []

try {
  const iterator = octokit.paginate.iterator("GET /repos/{owner}/{repo}/pulls/{pull_number}/files", {
    owner: "github",
    repo: "docs",
    pull_number: 22809,
    per_page: 100,
    headers: {
      "x-github-api-version": "2022-11-28",
    },
  });

  for await (const {data} of iterator) {
    filesChanged = [...filesChanged, ...data.map(fileData => fileData.filename)];
  }
} catch (error) {
  if (error.response) {
    console.error(`Error! Status: ${error.response.status}. Message: ${error.response.data.message}`)
  }
  console.error(error)
}

Обработка предполагаемых кодов ошибок

Иногда GitHub использует код состояния 4xx для указания ответа без ошибок. Если используется эта конечная точка, можно добавить дополнительную обработку для определенных ошибок. Например, конечная GET /user/starred/{owner}/{repo} точка вернет объект, 404 если репозиторий не указан. В следующем примере используется ответ, указывающий, что репозиторий 404 не был в главной роли; все остальные коды ошибок рассматриваются как ошибки.

JavaScript
try {
  await octokit.request("GET /user/starred/{owner}/{repo}", {
    owner: "github",
    repo: "docs",
    headers: {
      "x-github-api-version": "2022-11-28",
    },
  });

  console.log(`The repository is starred by me`);

} catch (error) {
  if (error.status === 404) {
    console.log(`The repository is not starred by me`);
  } else {
    console.error(`An error occurred while checking if the repository is starred: ${error?.response?.data?.message}`);
  }
}

Обработка ошибок ограничения скорости

Если вы получаете ошибку ограничения скорости, вы можете повторить запрос после ожидания. Если скорость ограничена, GitHub отвечает с ошибкой403 Forbidden, а x-ratelimit-remaining значение заголовка ответа будет."0" Заголовки ответа будут содержать x-ratelimit-reset заголовок, который указывает время сброса текущего ограничения скорости в секундах эпохи UTC. После указанного x-ratelimit-resetвремени можно повторить запрос.

JavaScript
async function requestRetry(route, parameters) {
  try {
    const response = await octokit.request(route, parameters);
    return response
  } catch (error) {
    if (error.response && error.status === 403 && error.response.headers['x-ratelimit-remaining'] === '0') {
      const resetTimeEpochSeconds = error.response.headers['x-ratelimit-reset'];
      const currentTimeEpochSeconds = Math.floor(Date.now() / 1000);
      const secondsToWait = resetTimeEpochSeconds - currentTimeEpochSeconds;
      console.log(`You have exceeded your rate limit. Retrying in ${secondsToWait} seconds.`);
      setTimeout(requestRetry, secondsToWait * 1000, route, parameters);
    } else {
      console.error(error);
    }
  }
}

const response = await requestRetry("GET /repos/{owner}/{repo}/issues", {
    owner: "github",
    repo: "docs",
    per_page: 2
  })

Использование ответа

Метод request возвращает обещание, разрешающее объекту, если запрос выполнен успешно. Свойства объекта : data (текст ответа, возвращаемый конечной точкой), status (код ОТВЕТА HTTP), url (URL-адрес запроса) и headers (объект, содержащий заголовки ответа). Если не указано иное, текст ответа имеет формат JSON. Некоторые конечные точки не возвращают текст ответа; В этих случаях data свойство опущено.

JavaScript
const response = await octokit.request("GET /repos/{owner}/{repo}/issues/{issue_number}", {
  owner: "github",
  repo: "docs",
  issue_number: 11901,
  headers: {
    "x-github-api-version": "2022-11-28",
  },
});

console.log(`The status of the response is: ${response.status}`)
console.log(`The request URL was: ${response.url}`)
console.log(`The x-ratelimit-remaining response header is: ${response.headers["x-ratelimit-remaining"]}`)
console.log(`The issue title is: ${response.data.title}`)

Аналогичным образом paginate метод возвращает обещание. Если запрос выполнен успешно, обещание разрешает массив данных, возвращаемых конечной точкой. request В отличие от метода, paginate метод не возвращает код состояния, URL-адрес или заголовки.

JavaScript
const data = await octokit.paginate("GET /repos/{owner}/{repo}/issues", {
  owner: "github",
  repo: "docs",
  per_page: 100,
  headers: {
    "x-github-api-version": "2022-11-28",
  },
});

console.log(`${data.length} issues were returned`)
console.log(`The title of the first issue is: ${data[0].title}`)

Пример сценария

Ниже приведен полный пример скрипта, использующего Octokit.js. Скрипт импортирует Octokit и создает новый экземпляр Octokit. Если вы хотите выполнить проверку подлинности с помощью GitHub App, а не personal access token, вы будете импортировать и создать экземпляр App вместо Octokitнего. Дополнительные сведения см. в статье "Проверка подлинности с помощью GitHub App".

Функция getChangedFiles получает все файлы, измененные для запроса на вытягивание. Функция commentIfDataFilesChanged вызывает функцию getChangedFiles . Если любой из файлов, измененных запросом на вытягивание, включен /data/ в путь к файлу, функция будет комментировать запрос на вытягивание.

JavaScript
import { Octokit } from "octokit";

const octokit = new Octokit({ 
  auth: 'YOUR-TOKEN',
});

async function getChangedFiles({owner, repo, pullNumber}) {
  let filesChanged = []

  try {
    const iterator = octokit.paginate.iterator("GET /repos/{owner}/{repo}/pulls/{pull_number}/files", {
      owner: owner,
      repo: repo,
      pull_number: pullNumber,
      per_page: 100,
      headers: {
        "x-github-api-version": "2022-11-28",
      },
    });

    for await (const {data} of iterator) {
      filesChanged = [...filesChanged, ...data.map(fileData => fileData.filename)];
    }
  } catch (error) {
    if (error.response) {
      console.error(`Error! Status: ${error.response.status}. Message: ${error.response.data.message}`)
    }
    console.error(error)
  }

  return filesChanged
}

async function commentIfDataFilesChanged({owner, repo, pullNumber}) {
  const changedFiles = await getChangedFiles({owner, repo, pullNumber});

  const filePathRegex = new RegExp(/\/data\//, "i");
  if (!changedFiles.some(fileName => filePathRegex.test(fileName))) {
    return;
  }

  try {
    const {data: comment} = await octokit.request("POST /repos/{owner}/{repo}/issues/{issue_number}/comments", {
      owner: owner,
      repo: repo,
      issue_number: pullNumber,
      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.`,
      headers: {
        "x-github-api-version": "2022-11-28",
      },
    });

    return comment.html_url;
  } catch (error) {
    if (error.response) {
      console.error(`Error! Status: ${error.response.status}. Message: ${error.response.data.message}`)
    }
    console.error(error)
  }
}

await commentIfDataFilesChanged({owner: "github", repo: "docs", pullNumber: 191});

Следующие шаги

  • Дополнительные сведения о Octokit.js см . в документации по Octokit.js.
  • В некоторых реальных примерах см. сведения о том, как документы GitHub используют Octokit.js путем поиска в репозитории документов GitHub.