# Начало работы с REST API Узнайте, как пользоваться GitHub REST API. ## Введение В этой статье описывается, как использовать GitHub REST API с GitHub CLI, `curl`или JavaScript. Краткое руководство см [. в разделе AUTOTITLE](/ru/enterprise-server@3.22/rest/quickstart).

## Сведения о запросах к REST API В этом разделе описываются элементы, составляющие запрос API: * [Метод HTTP](#http-method) * [Путь](#path) * [Заголовки](#headers) * [Типы носителей](#media-types) * [Аутентификация](#authentication) * [Параметры](#parameters) Каждый запрос к REST API включает метод HTTP и путь. В зависимости от конечной точки REST API может потребоваться также указать заголовки запросов, сведения о проверке подлинности, параметры запроса или параметры текста. Справочная документация по REST API описывает метод HTTP, путь и параметры для каждой конечной точки. В нем также отображаются примеры запросов и ответов для каждой конечной точки. Дополнительные сведения см. в [справочной документации по REST](/ru/enterprise-server@3.22/rest). ### HTTP method (Метод HTTP) Метод HTTP конечной точки определяет тип действия, выполняемого в заданном ресурсе. Некоторые распространенные методы HTTP: `GET`, `POST``DELETE`и `PATCH`. Справочная документация по REST API предоставляет метод HTTP для каждой конечной точки. Например, http-метод для конечной [точки](/ru/enterprise-server@3.22/rest/issues/issues#list-repository-issues)`GET`"Проблемы с репозиторием списка". По возможности GitHub REST API стремится использовать подходящий HTTP-метод для каждого действия. * `GET`: используется для получения ресурсов. * `POST`: используется для создания ресурсов. * `PATCH`: используется для обновления свойств ресурсов. * `PUT`: используется для замены ресурсов или коллекций ресурсов. * `DELETE`: используется для удаления ресурсов. ### Путь Каждая конечная точка имеет путь. Справочная документация по REST API предоставляет путь для каждой конечной точки. Например, путь к конечной точке [](/ru/enterprise-server@3.22/rest/issues/issues#list-repository-issues)`/repos/{owner}/{repo}/issues`"Проблемы с репозиторием списка". Фигурные скобки `{}` в пути указывают параметры пути, которые необходимо указать. Параметры пути изменяют путь конечной точки и требуются в запросе. Например, параметры пути для конечной [точки](/ru/enterprise-server@3.22/rest/issues/issues#list-repository-issues) "Проблемы с репозиторием списка" и `{owner}``{repo}` . Чтобы использовать этот путь в запросе API, замените `{repo}` на имя репозитория, в котором вы хотите запросить список проблем, и замените `{owner}` именем учетной записи, принадлежащей репозиторию. ### Заголовки Заголовки предоставляют дополнительные сведения о запросе и требуемом ответе. Ниже приведены примеры заголовков, которые вы можете использовать в запросах к GitHub REST API. Пример запроса, использующего заголовки, см. в разделе ["Создание запроса](#making-a-request)". #### `Accept` Большинство конечных точек GitHub REST API указывают, что нужно передавать `Accept` заголовок со значением `application/vnd.github+json`. Значение заголовка `Accept` — тип носителя. Дополнительные сведения о типах носителей см. в разделе ["Типы](#media-types) носителей". #### `X-GitHub-Api-Version` Этот заголовок следует использовать для указания версии REST API, используемой для запроса. Дополнительные сведения см. в разделе [Версии API](/ru/enterprise-server@3.22/rest/about-the-rest-api/api-versions). ### Типы носителей Можно указать один или несколько типов носителей, добавив их в `Accept` заголовок запроса. Дополнительные сведения о заголовке `Accept` см. в разделе`Accept`[](#accept) . Типы носителей указывают формат данных, которые требуется использовать из API. Типы мультимедиа связаны с конкретными ресурсами, что позволяет изменять их независимо друг от друга и обеспечить поддержку форматов, которые не поддерживают другие ресурсы. Документация по каждой GitHub конечной точке REST API описывает типы медиа, которые он поддерживает. Дополнительные сведения см. в [разделе AUTOTITLE](/ru/enterprise-server@3.22/rest). Наиболее распространённые типы медиа, поддерживаемые GitHub REST API, — это `application/vnd.github+json` и `application/json`. Существуют пользовательские типы носителей, которые можно использовать с некоторыми конечными точками. Например, REST API для управления фиксациями и [](/ru/enterprise-server@3.22/rest/commits/commits#get-a-commit) Типы `full`носителей , `raw``text`или `html` используются другими конечными точками. Все пользовательские типы GitHub медиа выглядят так: `application/vnd.github.PARAM+json`, где `PARAM` — название типа медиа. Например, чтобы указать `raw` тип носителя, следует использовать `application/vnd.github.raw+json`. Пример запроса, использующего типы носителей, см. в разделе ["Создание запроса](#making-a-request)". ### Аутентификация Для многих конечных точек требуется проверка подлинности или возврат дополнительных сведений при проверке подлинности. Кроме того, при проверке подлинности можно выполнять больше запросов в час.

Чтобы выполнить проверку подлинности запроса, необходимо предоставить маркер проверки подлинности с необходимыми областями или разрешениями. Есть несколько способов получить токен: вы можете создать personal access token, сгенерировать токен с GitHub App, или использовать встроенный `GITHUB_TOKEN` токен в рабочем GitHub Actions процессе. Дополнительные сведения см. в разделе [Проверка подлинности в REST API](/ru/enterprise-server@3.22/rest/authentication/authenticating-to-the-rest-api). Пример запроса, использующего маркер проверки подлинности, см. в разделе ["Выполнение запроса](#making-a-request)". > \[!NOTE] > Если не хотите создавать токен, можно использовать GitHub CLI. > GitHub CLI Он займётся вашей аутентификацией и поможет сохранить безопасность вашего аккаунта. Для получения дополнительной информации смотрите [GitHub CLI версию этой страницы](/ru/enterprise-server@3.22/rest/using-the-rest-api/getting-started-with-the-rest-api?tool=cli). > \[!WARNING] > Обработайте маркер доступа так же, как и пароли или другие конфиденциальные учетные данные. Дополнительные сведения см. в разделе [Обеспечение безопасности учетных данных API](/ru/enterprise-server@3.22/rest/authentication/keeping-your-api-credentials-secure).

Хотя некоторые конечные точки REST API доступны без аутентификации, GitHub CLI для этого требуется аутентификация, прежде чем использовать `api` подкоманду для запроса API. Используйте `auth login` подкоманду для аутентификации в GitHub. Дополнительные сведения см. в разделе ["Создание запроса](#making-a-request)".

Чтобы выполнить проверку подлинности запроса, необходимо предоставить маркер проверки подлинности с необходимыми областями или разрешениями. Есть несколько способов получить токен: вы можете создать personal access token, сгенерировать токен с GitHub App, или использовать встроенный `GITHUB_TOKEN` токен в рабочем GitHub Actions процессе. Дополнительные сведения см. в разделе [Проверка подлинности в REST API](/ru/enterprise-server@3.22/rest/authentication/authenticating-to-the-rest-api). Пример запроса, использующего маркер проверки подлинности, см. в разделе ["Выполнение запроса](#making-a-request)". > \[!WARNING] > Обработайте маркер доступа так же, как и пароли или другие конфиденциальные учетные данные. Дополнительные сведения см. в разделе [Обеспечение безопасности учетных данных API](/ru/enterprise-server@3.22/rest/authentication/keeping-your-api-credentials-secure).

### Параметры Многие методы API требуют или позволяют отправлять дополнительные сведения в параметрах запроса. Существует несколько различных типов параметров: параметры пути, параметры тела и параметры запроса. #### Параметры пути Параметры пути изменяют путь конечной точки. Эти параметры необходимы в запросе. Дополнительные сведения см. в разделе ["Путь](#path)". #### Параметры запроса Параметры запроса позволяют передавать дополнительные данные в API. Эти параметры могут быть необязательными или обязательными в зависимости от конечной точки. Например, параметр body может позволить указать заголовок проблемы при создании новой проблемы или указать определенные параметры при включении или отключении функции. Документация по каждой GitHub конечной точке REST API описывает поддерживаемые им параметры тела. Дополнительные сведения см. в [разделе AUTOTITLE](/ru/enterprise-server@3.22/rest). Например, [для конечной точки](/ru/enterprise-server@3.22/rest/issues/issues#create-an-issue) "Создание проблемы" требуется указать название новой проблемы в запросе. Кроме того, вы можете дополнительно указать другие сведения, например текст, помещенный в текст проблемы, пользователи могут назначить новую проблему или метки для применения к новой проблеме. Пример запроса, использующего параметры текста, см. в разделе ["Создание запроса](#making-a-request)". Для передачи параметров тела необходимо пройти проверку подлинности запроса. Дополнительные сведения см. в разделе [Authenticate to the Speech API](#authentication) (Аутентификация в API речи). #### Параметры запроса Параметры запроса позволяют контролировать, какие данные возвращаются для запроса. Обычно эти параметры являются необязательными. Документация для каждой GitHub конечной точки REST API описывает любые поддерживаемые ими параметры запроса. Дополнительные сведения см. в [разделе AUTOTITLE](/ru/enterprise-server@3.22/rest). Например, конечная [точка](/ru/enterprise-server@3.22/rest/activity/events#list-public-events) "Список общедоступных событий" возвращает тридцать проблем по умолчанию. Для возврата двух проблем вместо 30 можно использовать `per_page` параметр запроса. Параметр запроса можно использовать `page` для получения только первой страницы результатов. Пример запроса, использующего параметры запроса, см. в разделе ["Создание запроса](#making-a-request)". ## Выполнение запроса

В этом разделе демонстрируется, как сделать аутентифицированный запрос в GitHub REST API с помощью GitHub CLI. ### 1. Настройка Установите GitHub CLI на macOS, Windows или Linux. Для получения дополнительной информации смотрите [раздел «Установка](https://github.com/cli/cli#installation) » в GitHub CLI репозитории. ### 2. Проверка подлинности 1. Для аутентификации в GitHub, выполните следующую команду из вашего терминала. ```shell gh auth login ``` Вы можете использовать `--scopes` этот параметр, чтобы указать нужные области. Если вы хотите пройти проверку подлинности с помощью созданного маркера, можно использовать этот `--with-token` параметр. Для получения дополнительной информации смотрите [GitHub CLI`auth login` документацию](https://cli.github.com/manual/gh_auth_login). 2. Выберите место для проверки подлинности: * Если вы получите доступ GitHub к GitHub.com, выберите **GitHub.com**. * Если вы заходите GitHub на другой домен, выберите **«Другое**», затем введите имя хоста (например: `octocorp.ghe.com`). 3. Следуйте остальным запросам на экране. GitHub CLI Автоматически сохраняет ваши учётные данные Git, когда вы выбираете HTTPS как предпочтительный протокол для операций с Git, и отвечает «да» на вопрос, хотите ли вы аутентифицироваться в Git с вашими GitHub учетными данными. Это может быть полезно, так как это позволяет использовать такие команды Git, как `git push` и `git pull` без необходимости настраивать отдельный диспетчер учетных данных или использовать SSH. ### 3. Выберите конечную точку для запроса 1. Выберите конечную точку для выполнения запроса. Вы можете изучить GitHub[документацию REST API](/ru/enterprise-server@3.22/rest), чтобы найти конечные точки для взаимодействия с GitHub. 2. Определите метод HTTP и путь конечной точки. Вы отправите их с запросом. Дополнительные сведения см. в разделе ["Метод](#http-method) HTTP" и ["Путь".](#path) Например, конечная [точка](/ru/enterprise-server@3.22/rest/issues/issues#create-an-issue) "Создание проблемы" использует метод `POST` HTTP и путь `/repos/{owner}/{repo}/issues`. 3. Определите все необходимые параметры пути. Требуемые параметры пути отображаются в фигурных скобках `{}` в пути конечной точки. Замените заполнитель каждого параметра требуемым значением. Дополнительные сведения см. в разделе ["Путь](#path)". Например, [конечная точка](/ru/enterprise-server@3.22/rest/issues/issues#create-an-issue) "Создание проблемы" использует путь, а параметры пути `/repos/{owner}/{repo}/issues`— `{owner}` и `{repo}`. Чтобы использовать этот путь в запросе API, замените `{repo}` именем репозитория, в котором вы хотите создать новую проблему, и замените `{owner}` именем учетной записи, которая владеет репозиторием. ### 4. Сделайте запрос с GitHub CLI Используйте GitHub CLI`api` подкоманду, чтобы сделать ваш API-запрос. Для получения дополнительной информации смотрите [GitHub CLI`api` документацию](https://cli.github.com/manual/gh_api). В запросе укажите следующие параметры и значения: * **--имя хозяина:** Если вы аутентифицированы на несколько аккаунтов на разных GitHub платформах, уточните, где вы делаете запрос. Например: `--hostname octocorp.ghe.com`. * **--method** , за которым следует метод HTTP и путь конечной точки. Дополнительные сведения см. в разделе ["Метод](#http-method) HTTP" и ["Путь".](#path) * **--заголовок:** * **`Accept`:** передайте тип носителя в заголовке `Accept` . Чтобы передать несколько типов мультимедиа в заголовке, разделите типы носителей `Accept` с запятой: `Accept: application/vnd.github+json,application/vnd.github.diff` Дополнительные сведения см. в разделе [`Accept`](#accept) и [типах](#media-types) мультимедиа. * **`X-GitHub-Api-Version`:** Передайте версию API в заголовке `X-GitHub-Api-Version`. Для получения дополнительной информации см. [`X-GitHub-Api-Version`](#x-github-api-version). * **`-f`** или **`-F`** следуют любые параметры текста или параметры запроса в `key=value` формате. `-F` Используйте параметр для передачи параметра, который является числом, логическим значением или null. `-f` Используйте параметр для передачи параметров строки. Некоторые конечные точки используют параметры запроса, которые являются массивами. Чтобы отправить массив в строке запроса, используйте параметр запроса один раз на элемент массива и добавьте `[]` после имени параметра запроса. Например, чтобы предоставить массив двух идентификаторов репозитория, используйте `-f repository_ids[]=REPOSITORY_A_ID -f repository_ids[]=REPOSITORY_B_ID`. Если в запросе не требуется указывать параметры текста или параметры запроса, опустите этот параметр. Дополнительные сведения см. в разделе ["Параметры](#body-parameters) текста" и ["Параметры](#query-parameters) запроса". Примеры см. в разделе ["Пример запроса с использованием параметров](#example-request-using-body-parameters) текста" и ["Пример запроса" с помощью параметров](#example-request-using-query-parameters) запроса. * **--имя хозяина:** Если вы аутентифицированы на несколько аккаунтов на разных GitHub платформах, уточните, где вы делаете запрос. Например: `--hostname octocorp.ghe.com`. #### Пример запроса В следующем примере запроса используется [конечная точка](/ru/enterprise-server@3.22/rest/meta/meta#get-octocat) Get Octocat для возврата октоката в виде искусства ASCII. ```shell copy gh api --method GET /octocat \ --header 'Accept: application/vnd.github+json' \ --header "X-GitHub-Api-Version: 2022-11-28" ``` #### Пример запроса с помощью параметров запроса Конечная [точка](/ru/enterprise-server@3.22/rest/activity/events#list-public-events) "Список общедоступных событий" возвращает тридцать проблем по умолчанию. В следующем примере используется `per_page` параметр запроса для возврата двух проблем вместо 30, а `page` параметр запроса для получения только первой страницы результатов. ```shell copy gh api --method GET /events -F per_page=2 -F page=1 --header 'Accept: application/vnd.github+json' \ ``` #### Пример запроса с использованием параметров текста Следующий пример использует [конечную точку «Создать проблему](/ru/enterprise-server@3.22/rest/issues/issues#create-an-issue) » для создания новой задачи в определённом . Замените `REPO-NAME` имя репозитория, где хотите создать новый выпуск, и замените `REPO-OWNER` на имя аккаунта, владеющего репозиторием. В ответе найдите `html_url` информацию о вашей проблеме и перейдите к ней в браузере. ```shell copy gh api --method POST /repos/REPO-OWNER/REPO-NAME/issues \ --header "Accept: application/vnd.github+json" \ --header "X-GitHub-Api-Version: 2022-11-28" \ -f title='Created with the REST API' \ -f body='This is a test issue created by the REST API' \ ```

В этом разделе демонстрируется, как сделать аутентифицированный запрос в GitHub REST API с помощью `curl`. ### 1. Настройка Необходимо установить `curl` на компьютере. Чтобы проверить `curl` , уже ли установлено, выполните команду `curl --version` в командной строке. * Если выходные данные содержат сведения о версии `curl`, то это означает `curl` , что устанавливается. * Если вы получите сообщение, аналогичное `command not found: curl`, это означает `curl` , что оно не установлено. Загрузите и установите `curl`. Дополнительные сведения см [. на странице](https://curl.se/download.html) скачивания curl. ### 2. Выберите конечную точку для запроса 1. Выберите конечную точку для выполнения запроса. Вы можете изучить GitHub[документацию REST API](/ru/enterprise-server@3.22/rest), чтобы найти конечные точки для взаимодействия с GitHub. 2. Определите метод HTTP и путь конечной точки. Вы отправите их с запросом. Дополнительные сведения см. в разделе ["Метод](#http-method) HTTP" и ["Путь".](#path) Например, конечная [точка](/ru/enterprise-server@3.22/rest/issues/issues#create-an-issue) "Создание проблемы" использует метод `POST` HTTP и путь `/repos/{owner}/{repo}/issues`. 3. Определите все необходимые параметры пути. Требуемые параметры пути отображаются в фигурных скобках `{}` в пути конечной точки. Замените заполнитель каждого параметра требуемым значением. Дополнительные сведения см. в разделе ["Путь](#path)". Например, [конечная точка](/ru/enterprise-server@3.22/rest/issues/issues#create-an-issue) "Создание проблемы" использует путь, а параметры пути `/repos/{owner}/{repo}/issues`— `{owner}` и `{repo}`. Чтобы использовать этот путь в запросе API, замените `{repo}` именем репозитория, в котором вы хотите создать новую проблему, и замените `{owner}` именем учетной записи, которая владеет репозиторием. ### 3. Создание учетных данных проверки подлинности Создайте маркер доступа для проверки подлинности запроса. Вы можете сохранить маркер и использовать его для нескольких запросов. Предоставьте маркеру любые области или разрешения, необходимые для доступа к конечной точке. Этот маркер будет отправлен в заголовке с запросом `Authorization` . Дополнительные сведения см. в разделе [Authenticate to the Speech API](#authentication) (Аутентификация в API речи). ### 4. Создание `curl` запроса Используйте команду `curl` для выполнения запроса. Дополнительные сведения см [. в документации](https://curl.se/docs/manpage.html) по curl. Укажите следующие параметры и значения в запросе: * **`--request` или `-X`** затем метод HTTP в качестве значения. Дополнительные сведения см. в статье [о методе](#http-method) HTTP. * **`--url`** за которым следует полный путь в качестве значения. Полный путь — это URL, включающий базовый URL GitHub REST API (`http(s)://HOSTNAME/api/v3`) и путь конечной точки, вот так: `http(s)://HOSTNAME/api/v3/PATH`. Замените `HOSTNAME` на имя ваш экземпляр GitHub Enterprise Server. Замените `PATH` на путь конечной точки. Дополнительные сведения см. в разделе ["Путь](#path)". Чтобы использовать параметры запроса, добавьте его в конец пути, а затем добавьте `?` имя и значение параметра запроса в форме `parameter_name=value`. Разделите несколько параметров запроса с помощью `&`. Если необходимо отправить массив в строке запроса, используйте параметр запроса один раз на элемент массива и добавьте `[]` его после имени параметра запроса. Например, чтобы предоставить массив двух идентификаторов репозитория, используйте `?repository_ids[]=REPOSITORY_A_ID&repository_ids[]=REPOSITORY_B_ID`. Дополнительные сведения см. в разделе ["Параметры](#query-parameters) запроса". Пример см. в примере [запроса с помощью параметров](#example-request-using-query-parameters-1) запроса. * **`--header` или `-H`:** * **`Accept`:** передайте тип носителя в заголовке `Accept` . Чтобы передать несколько типов мультимедиа в заголовке, разделите типы носителей `Accept` запятыми, например: `Accept: application/vnd.github+json,application/vnd.github.diff` Дополнительные сведения см. в разделе [`Accept`](#accept) и [типах](#media-types) мультимедиа. * **`X-GitHub-Api-Version`:** Передайте версию API в заголовке `X-GitHub-Api-Version`. Для получения дополнительной информации см. [`X-GitHub-Api-Version`](#x-github-api-version). * **`Authorization`:** передайте маркер проверки подлинности в заголовке `Authorization` . Обратите внимание, что в большинстве случаев можно использовать `Authorization: Bearer` или `Authorization: token` передавать маркер. Однако при передаче веб-токена JSON (JWT) необходимо использовать `Authorization: Bearer`. Дополнительные сведения см. в разделе [Authenticate to the Speech API](#authentication) (Аутентификация в API речи). Пример запроса, использующего `Authorization` заголовок, см [. в примере запроса с использованием параметров](#example-request-using-body-parameters-1) текста. * **`--data` или `-d`** все параметры тела в объекте JSON. Если в запросе не требуется указывать параметры текста, опустите этот параметр. Дополнительные сведения см. в разделе ["Параметры](#body-parameters) текста". Пример запроса см. в разделе ["Пример запроса с использованием параметров](#example-request-using-body-parameters-1) текста". #### Пример запроса В следующем примере запроса используется [конечная точка](/ru/enterprise-server@3.22/rest/meta/meta#get-octocat) Get Octocat для возврата октоката в виде искусства ASCII. ```shell copy curl --request GET \ --url "https://api.github.com/octocat" \ --header "Accept: application/vnd.github+json" \ --header "X-GitHub-Api-Version: 2022-11-28" ``` #### Пример запроса с помощью параметров запроса Конечная [точка](/ru/enterprise-server@3.22/rest/activity/events#list-public-events) "Список общедоступных событий" возвращает тридцать проблем по умолчанию. В следующем примере используется `per_page` параметр запроса для возврата двух проблем вместо 30, а `page` параметр запроса для получения только первой страницы результатов. ```shell copy curl --request GET \ --url "http(s)://HOSTNAME/api/v3/events?per_page=2&page=1" \ --header "Accept: application/vnd.github+json" \ --header "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/events ``` #### Пример запроса с использованием параметров текста Следующий пример использует [конечную точку Create](/ru/enterprise-server@3.22/rest/issues/issues#create-an-issue) an issue для создания новой задачи в определённом . Замените `HOSTNAME` на имя ваш экземпляр GitHub Enterprise Server. Замените `REPO-NAME` имя репозитория, где хотите создать новый выпуск, и замените `REPO-OWNER` на имя аккаунта, владеющего репозиторием. Замените `YOUR-TOKEN` на токен, который вы создали на предыдущем этапе. > \[!NOTE] > Если вы используете fine-grained personal access token, вам нужно заменить `REPO-OWNER``REPO-NAME` и на репозиториум, который принадлежит вам или принадлежит организации, членом которой вы являетесь. Маркер должен иметь доступ к этом репозиторию и иметь разрешения на чтение и запись для проблем с репозиторием. Дополнительные сведения см. в разделе [Управление личными маркерами доступа](/ru/enterprise-server@3.22/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens). ```shell copy curl \ --request POST \ --url "http(s)://HOSTNAME/api/v3/repos/REPO-OWNER/REPO-NAME/issues" \ --header "Accept: application/vnd.github+json" \ --header "X-GitHub-Api-Version: 2022-11-28" \ --header "Authorization: Bearer YOUR-TOKEN" \ --data '{ "title": "Created with the REST API", "body": "This is a test issue created by the REST API" }' ```

В этом разделе демонстрируется, как сделать запрос в GitHub REST API с помощью JavaScript и [Octokit.js](https://github.com/octokit/octokit.js). Более подробное руководство см. в разделе [Скриптирование с помощью REST API и JavaScript](/ru/enterprise-server@3.22/rest/guides/scripting-with-the-rest-api-and-javascript). ### 1. Настройка Чтобы использовать библиотеку Octokit.js, показанную в следующих примерах, необходимо установить `octokit` . * Установите `octokit`. Например: `npm install octokit`. Другие способы установки или загрузки `octokit` см. в [Octokit.js README](https://github.com/octokit/octokit.js/#readme). ### 2. Выберите конечную точку для запроса 1. Выберите конечную точку для выполнения запроса. Вы можете изучить GitHub[документацию REST API](/ru/enterprise-server@3.22/rest), чтобы найти конечные точки для взаимодействия с GitHub. 2. Определите метод HTTP и путь конечной точки. Вы отправите их с запросом. Дополнительные сведения см. в разделе ["Метод](#http-method) HTTP" и ["Путь".](#path) Например, конечная [точка](/ru/enterprise-server@3.22/rest/issues/issues#create-an-issue) "Создание проблемы" использует метод `POST` HTTP и путь `/repos/{owner}/{repo}/issues`. 3. Определите все необходимые параметры пути. Требуемые параметры пути отображаются в фигурных скобках `{}` в пути конечной точки. Замените заполнитель каждого параметра требуемым значением. Дополнительные сведения см. в разделе ["Путь](#path)". Например, [конечная точка](/ru/enterprise-server@3.22/rest/issues/issues#create-an-issue) "Создание проблемы" использует путь, а параметры пути `/repos/{owner}/{repo}/issues`— `{owner}` и `{repo}`. Чтобы использовать этот путь в запросе API, замените `{repo}` именем репозитория, в котором вы хотите создать новую проблему, и замените `{owner}` именем учетной записи, которая владеет репозиторием. ### 3. Создание маркера доступа Создайте маркер доступа для проверки подлинности запроса. Вы можете сохранить маркер и использовать его для нескольких запросов. Предоставьте маркеру любые области или разрешения, необходимые для доступа к конечной точке. Этот маркер будет отправлен в заголовке с запросом `Authorization` . Дополнительные сведения см. в разделе [Authenticate to the Speech API](#authentication) (Аутентификация в API речи). ### 4. Создание запроса с помощью Octokit.js 1. Импортируйте `octokit` в скрипт. Например: `import { Octokit } from "octokit";`. Другие способы импорта `octokit` см. в [Octokit.js README](https://github.com/octokit/octokit.js/#readme). 2. Создайте экземпляр `Octokit` с помощью вашего токена. Установите базовый URL на `http(s)://HOSTNAME/api/v3`. Замените `HOSTNAME` на имя ваш экземпляр GitHub Enterprise Server. Замените `YOUR-TOKEN` маркером. ```javascript copy const octokit = new Octokit({ baseUrl: "http(s)://HOSTNAME/api/v3", auth: 'YOUR-TOKEN' }); ``` 3. Используйте `octokit.request` для выполнения запроса. * Отправьте метод HTTP и путь в качестве первого аргумента в `request` метод. Дополнительные сведения см. в разделе ["Метод](#http-method) HTTP" и ["Путь".](#path) * Укажите все параметры пути, запроса и текста в объекте в качестве второго аргумента `request` метода. Дополнительные сведения см. в разделе [Параметры](#parameters). В следующем примере запроса HTTP-метод — это `POST`, путь — `/repos/{owner}/{repo}/issues`, параметры пути — `owner: "REPO-OWNER"` и `repo: "REPO-NAME"`, а параметры тела — `title: "Created with the REST API"` и `body: "This is a test issue created by the REST API"`. Замените `REPO-OWNER` на название аккаунта, владеющего репозиторием, и `REPO-NAME` на название репозитория. > \[!NOTE] > Если вы используете fine-grained personal access token, вам нужно заменить `REPO-OWNER``REPO-NAME` и на репозиториум, который принадлежит вам или принадлежит организации, членом которой вы являетесь. Маркер должен иметь доступ к этом репозиторию и иметь разрешения на чтение и запись для проблем с репозиторием. Дополнительные сведения см. в разделе [Управление личными маркерами доступа](/ru/enterprise-server@3.22/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens). ```javascript copy await octokit.request("POST /repos/{owner}/{repo}/issues", { owner: "REPO-OWNER", repo: "REPO-NAME", title: "Created with the REST API", body: "This is a test issue created by the REST API", }); ``` Метод `request` автоматически передает `Accept: application/vnd.github+json` заголовок. Чтобы передать дополнительные заголовки или другой `Accept` заголовок, добавьте `headers` свойство в объект, передаваемый в качестве второго аргумента. Значение свойства `headers` — это объект с именами заголовков в качестве ключей и значениями заголовков в качестве значений. Например, следующий код отправит заголовок `content-type` со значением `text/plain` и заголовок `X-GitHub-Api-Version` со значением `2026-03-10`. ```javascript copy await octokit.request("GET /octocat", { headers: { "content-type": "text/plain", "X-GitHub-Api-Version": "2026-03-10", }, }); ```

## Использование ответа После выполнения запроса API вернет код состояния ответа, заголовки ответов и потенциально текст ответа. ### Сведения о коде ответа и заголовках Каждый запрос возвращает код состояния HTTP, указывающий на успешность ответа. Дополнительные сведения о кодах ответов см. [в документации по кодам состояния ответов MDN HTTP](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status). Кроме того, ответ будет содержать заголовки, которые предоставляют дополнительные сведения об ответе. Заголовки, которые начинаются с `X-` .`x-`GitHub Например, заголовки `x-ratelimit-remaining` и `x-ratelimit-reset` сообщают, сколько запросов можно выполнить за период времени.

Чтобы просмотреть код состояния и заголовки, используйте `--include` или `--i` параметр при отправке запроса. Например, этот запрос получает список проблем в определённом : ```shell gh api \ --header 'Accept: application/vnd.github+json' \ --method GET /repos/REPO-OWNER/REPO-NAME/issues \ -F per_page=2 --include ``` И он возвращает код ответа и заголовки, которые выглядят примерно так: ```shell HTTP/2.0 200 OK Access-Control-Allow-Origin: * Access-Control-Expose-Headers: ETag, Link, Location, Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Used, X-RateLimit-Resource, X-RateLimit-Reset, X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval, X-GitHub-Media-Type, X-GitHub-SSO, X-GitHub-Request-Id, Deprecation, Sunset Cache-Control: private, max-age=60, s-maxage=60 Content-Security-Policy: default-src 'none' Content-Type: application/json; charset=utf-8 Date: Thu, 04 Aug 2022 19:56:41 GMT Etag: W/"a63dfbcfdb73621e9d2e89551edcf9856731ced534bd7f1e114a5da1f5f73418" Link: ; rel="next", ; rel="last" Referrer-Policy: origin-when-cross-origin, strict-origin-when-cross-origin Server: GitHub.com Strict-Transport-Security: max-age=31536000; includeSubdomains; preload Vary: Accept, Authorization, Cookie, Accept-Encoding, Accept, X-Requested-With X-Accepted-Oauth-Scopes: repo X-Content-Type-Options: nosniff X-Frame-Options: deny X-Github-Api-Version-Selected: 2022-08-09 X-Github-Media-Type: github.v3; format=json X-Github-Request-Id: 1C73:26D4:E2E500:1EF78F4:62EC2479 X-Oauth-Client-Id: 178c6fc778ccc68e1d6a X-Oauth-Scopes: gist, read:org, repo, workflow X-Ratelimit-Limit: 15000 X-Ratelimit-Remaining: 14996 X-Ratelimit-Reset: 1659645499 X-Ratelimit-Resource: core X-Ratelimit-Used: 4 X-Xss-Protection: 0 ``` В этом примере код ответа — `200`, что указывает на успешный запрос.

При выполнении запроса с Octokit.js метод `request` возвращает обещание. Если запрос выполнен успешно, обещание разрешается в объект, включающий код состояния HTTP ответа (`status`) и заголовки ответа (`headers`). Если возникла ошибка, обещание разрешается в объект, включающий код состояния HTTP ответа (`status`) и заголовки ответа (`response.headers`). При возникновении ошибки можно использовать блок `try/catch` для ее перехвата. Например, если запрос в следующем скрипте выполнен успешно, скрипт занесет в журнал код состояния и значение заголовка `x-ratelimit-remaining`. Если запрос не выполнен, скрипт занесет в журнал код состояния, значение заголовка `x-ratelimit-remaining` и сообщение об ошибке. В следующем примере замените `REPO-OWNER` имя учетной записи, владеющей репозиторием, и `REPO-NAME` именем репозитория. ```javascript copy try { const result = await octokit.request("GET /repos/{owner}/{repo}/issues", { owner: "REPO-OWNER", repo: "REPO-NAME", per_page: 2, }); console.log(`Success! Status: ${result.status}. Rate limit remaining: ${result.headers["x-ratelimit-remaining"]}`) } catch (error) { console.log(`Error! Status: ${error.status}. Rate limit remaining: ${error.headers["x-ratelimit-remaining"]}. Message: ${error.response.data.message}`) } ```

Чтобы просмотреть код состояния и заголовки, используйте `--include` или `--i` параметр при отправке запроса. Например, этот запрос получает список проблем в определённом : ```shell curl --request GET \ --url "https://api.github.com/repos/REPO-OWNER/REPO-NAME/issues?per_page=2" \ --header "Accept: application/vnd.github+json" \ --header "Authorization: Bearer YOUR-TOKEN" \ --include ``` И он возвращает код ответа и заголовки, которые выглядят примерно так: ```shell HTTP/2 200 server: GitHub.com date: Thu, 04 Aug 2022 20:07:51 GMT content-type: application/json; charset=utf-8 cache-control: public, max-age=60, s-maxage=60 vary: Accept, Accept-Encoding, Accept, X-Requested-With etag: W/"7fceb7e8c958d3ec4d02524b042578dcc7b282192e6c939070f4a70390962e18" x-github-media-type: github.v3; format=json link: ; rel="next", ; rel="last" access-control-expose-headers: ETag, Link, Location, Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Used, X-RateLimit-Resource, X-RateLimit-Reset, X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval, X-GitHub-Media-Type, X-GitHub-SSO, X-GitHub-Request-Id, Deprecation, Sunset access-control-allow-origin: * strict-transport-security: max-age=31536000; includeSubdomains; preload x-frame-options: deny x-content-type-options: nosniff x-xss-protection: 0 referrer-policy: origin-when-cross-origin, strict-origin-when-cross-origin content-security-policy: default-src 'none' x-ratelimit-limit: 15000 x-ratelimit-remaining: 14996 x-ratelimit-reset: 1659645535 x-ratelimit-resource: core x-ratelimit-used: 4 accept-ranges: bytes content-length: 4936 x-github-request-id: 14E0:4BC6:F1B8BA:208E317:62EC2715 ``` В этом примере код ответа — `200`, что указывает на успешный запрос.

### Сведения о тексте ответа Многие конечные точки возвращают текст ответа. Если не указано иное, текст ответа имеет формат JSON. Пустые поля включаются как `null`, а не пропускаются. Все метки времени возвращаются в формате UTC, формат ISO 8601: `YYYY-MM-DDTHH:MM:SSZ` В отличие от API GraphQL, в котором вы указываете желаемую информацию, REST API обычно возвращает больше информации, чем требуется. При необходимости можно проанализировать ответ, чтобы извлечь определенные данные.

Например, можно использовать `>` для перенаправления ответа в файл. В следующем примере замените `REPO-OWNER` имя учетной записи, владеющей репозиторием, и `REPO-NAME` именем репозитория. ```shell copy gh api \ --header 'Accept: application/vnd.github+json' \ --method GET /repos/REPO-OWNER/REPO-NAME/issues \ -F per_page=2 > data.json ``` Затем можно использовать jq, чтобы получить заголовок и идентификатор автора каждой проблемы: ```shell copy jq '.[] | {title: .title, authorID: .user.id}' data.json ``` Две предыдущие команды возвращают примерно следующее: ```json { "title": "Update index.html", "authorID": 10701255 } { "title": "Edit index file", "authorID": 53709285 } ``` Дополнительные сведения об jq см [. в документации](https://stedolan.github.io/jq/) по jq.

Например, вы можете получить заголовок и идентификатор автора каждой проблемы. В следующем примере замените `REPO-OWNER` имя учетной записи, владеющей репозиторием, и `REPO-NAME` именем репозитория. ```javascript copy try { const result = await octokit.request("GET /repos/{owner}/{repo}/issues", { owner: "REPO-OWNER", repo: "REPO-NAME", per_page: 2, }); const titleAndAuthor = result.data.map(issue => {title: issue.title, authorID: issue.user.id}) console.log(titleAndAuthor) } catch (error) { console.log(`Error! Status: ${error.status}. Message: ${error.response.data.message}`) } ```

Например, можно использовать `>` для перенаправления ответа в файл. В следующем примере замените `REPO-OWNER` на имя аккаунта, владеющего репозиторием, и `REPO-NAME` на название репозитория. Замените `HOSTNAME` на имя ваш экземпляр GitHub Enterprise Server. ```shell copy curl --request GET \ --url "http(s)://HOSTNAME/api/v3/repos/REPO-OWNER/REPO-NAME/issues?per_page=2" \ --header "Accept: application/vnd.github+json" \ --header "Authorization: Bearer YOUR-TOKEN" > data.json ``` Затем можно использовать jq, чтобы получить заголовок и идентификатор автора каждой проблемы: ```shell copy jq '.[] | {title: .title, authorID: .user.id}' data.json ``` Две предыдущие команды возвращают примерно следующее: ```json { "title": "Update index.html", "authorID": 10701255 } { "title": "Edit index file", "authorID": 53709285 } ``` Дополнительные сведения об jq см [. в документации](https://stedolan.github.io/jq/) по jq.

#### Подробные и суммарные представления Ответ может включать все атрибуты ресурса или только подмножество атрибутов в зависимости от того, извлекаете отдельный ресурс или список ресурсов. * При получении отдельного ресурса \_, например определенного \_репозитория, ответ обычно будет включать все атрибуты для этого ресурса. Это "подробное" представление ресурса. * При получении *списка ресурсов*, таких как список нескольких репозиториев, ответ будет включать только подмножество атрибутов для каждого ресурса. Это "сводное" представление ресурса. Обратите внимание, что авторизация иногда влияет на объем сведений, включенных в представление. Причина в том, что некоторые атрибуты вычислительно затратны для предоставления API, поэтому GitHub эти атрибуты исключаются из сводного представления. Чтобы получить эти атрибуты, можно получить подробное представление. В документации приводится пример ответа для каждого метода API. В примере ответа показаны все атрибуты, возвращаемые этим методом. #### Гиперсреда Любой ресурс может иметь одно или несколько свойств `*_url`, содержащих ссылки на другие ресурсы. Они предназначены для предоставления явных URL-адресов, чтобы соответствующим клиентам API не приходилось формировать URL-адреса самостоятельно. Настоятельно рекомендуется, чтобы клиенты API использовали эти свойства. Так разработчикам будет проще обновлять API в будущем. Все URL-адреса должны соответствовать шаблонам URI [RFC 6570](https://datatracker.ietf.org/doc/html/rfc6570). Затем можно расширить эти шаблоны, например, с помощью пакета [uri\_template](https://github.com/hannesg/uri_template): ```ruby >> tmpl = URITemplate.new('/notifications{?since,all,participating}') >> tmpl.expand => "/notifications" >> tmpl.expand all: 1 => "/notifications?all=1" >> tmpl.expand all: 1, participating: 1 => "/notifications?all=1&participating=1" ``` ## Ограничение скорости REST API ограничивает количество запросов, GitHub которые вы можете сделать за определённый промежуток времени. Для получения дополнительной информации о тарифных лимитах и о том, как проверить текущий статус лимита ставки, [смотрите AUTOTITLE.](/ru/enterprise-server@3.22/rest/using-the-rest-api/rate-limits-for-the-rest-api) ## Следующие шаги В этой статье показано, как перечислить и создать проблемы в репозитории. Попрактикуйтесь, прокомментировав проблему, изменив заголовок проблемы или закрыв проблему. Дополнительные сведения см. в [разделе](/ru/enterprise-server@3.22/rest/issues/comments#create-an-issue-comment) "Создание комментария проблемы" и [конечной точки](/ru/enterprise-server@3.22/rest/issues/issues#update-an-issue) "Обновление проблемы". Дополнительные сведения о других конечных точках, которые можно использовать, см. в справочной [документации](/ru/enterprise-server@3.22/rest) по REST.