Использование REST API для взаимодействия с проверками - документация GitHub Enterprise Server 310

REST API – это набор методов и соглашений, используемых для взаимодействия между клиентскими приложениями и серверами через интернет. GitHub Enterprise Server 310 предоставляет возможность использования REST API для автоматизированного взаимодействия с проверками.

При использовании REST API вам необходимо знать ряд основных концепций, таких как ресурсы, методы, параметры и коды состояния. Ресурсы представляют собой объекты или коллекции, с которыми вы хотите взаимодействовать, методы определяют тип действия, которое вы хотите выполнить, параметры передают данные, необходимые для выполнения действия, а коды состояния сообщают о результате выполнения запроса.

С помощью REST API GitHub Enterprise Server 310 вы можете выполнять различные операции с проверками, такие как создание, обновление и удаление проверок, а также получение информации о существующих проверках. Вы также можете получать уведомления о статусе проверки или использовать фильтры для поиска интересующих вас проверок.

REST API GitHub Enterprise Server 310 предоставляет мощный инструментарий для автоматизации работы с проверками и повышения эффективности процесса разработки. С его помощью вы можете интегрировать проверки в свои собственные инструменты и системы, создавать собственные пользовательские приложения и многое другое.

Получение проверок

Для получения информации о существующих проверках в репозитории можно использовать следующий запрос:

GET /repos/{owner}/{repo}/check-runs

Этот запрос вернет список проверок в репозитории, включая их статус, результаты и другую информацию.

Вы также можете указать дополнительные параметры в запросе для фильтрации результатов. Например, вы можете указать статус проверки, чтобы получить только проверки с определенным статусом:

GET /repos/{owner}/{repo}/check-runs?status=completed

Этот запрос вернет только завершенные проверки.

Вы также можете указать другие параметры в запросе, такие как ветка репозитория или конкретный коммит, чтобы получить проверки только для этого коммита:

GET /repos/{owner}/{repo}/check-runs?ref={branch}&commit={sha}

Этот запрос вернет проверки только для указанной ветки и коммита.

Полученные результаты будут представлены в виде JSON-объекта, который содержит информацию о каждой проверке, включая ее идентификатор, статус, результаты и другую информацию.

Использование REST API для получения проверок позволяет автоматизировать процесс анализа кода и контроля качества, что облегчает разработку и поддержку проектов на GitHub Enterprise Server 3.10.

Пример API-запроса для получения списка проверок

Для получения списка проверок с сервера GitHub Enterprise Server 310 вы можете использовать следующий API-запрос:

HTTP метод: GET

URL: /repos/{owner}/{repo}/commits/{ref}/check-runs

Здесь:

• {owner} - имя владельца репозитория
• {repo} - имя репозитория
• {ref} - ссылка на коммит, для которого нужно получить список проверок

Пример API-запроса:

GET /repos/octocat/Hello-World/commits/abc123/check-runs

В ответ вы получите список проверок для указанного коммита в формате JSON.

Пример ответа:

{
"check_runs": [
{
"id": 1,
"name": "lint",
"status": "completed",
"conclusion": "success",
"started_at": "2021-01-01T00:00:00Z",
"completed_at": "2021-01-01T00:01:00Z",
"output": {
"title": "Lint check",
"summary": "All files passed linting.",
"text": "No linting errors found."
}
},
{
"id": 2,
"name": "unit-tests",
"status": "completed",
"conclusion": "failure",
"started_at": "2021-01-01T00:01:00Z",
"completed_at": "2021-01-01T00:02:00Z",
"output": {
"title": "Unit tests",
"summary": "Some unit tests failed.",
"text": "Failed tests: test1, test2"
}
}
]
}

Каждая проверка представлена объектом JSON, содержащим следующую информацию:

• id - идентификатор проверки
• name - название проверки
• status - статус выполнения проверки (выполняется, завершено и т. д.)
• conclusion - итог выполнения проверки (успех, неудача и т. д.)
• started_at - дата и время начала проверки
• completed_at - дата и время окончания проверки
• output - результаты проверки

Вы можете использовать эти данные для анализа результатов проверок и предпринятия соответствующих действий.

Получение подробной информации о проверке

Для получения подробной информации о проверке воспользуйтесь методом GET и следующим эндпоинтом:

/repos/{owner}/{repo}/check-runs/{check_run_id}

где:

• {owner} - имя владельца репозитория
• {repo} - имя репозитория
• {check_run_id} - идентификатор проверки

Пример запроса:

GET /repos/octocat/hello-world/check-runs/123

Пример ответа:

{
"id": 123,
"name": "My Check",
"status": "completed",
"conclusion": "success",
"output": {
"title": "Hello World",
"summary": "All checks passed",
"text": "This is the detailed output of my check",
"annotations_count": 0,
"annotations_url": "https://api.github.com/repos/octocat/hello-world/check-runs/123/annotations"
},
"external_resources": []
}

Создание и обновление проверок

Для создания и обновления проверок в GitHub Enterprise Server 3.10 можно использовать REST API. Запросы к API передаются через методы HTTP, такие как GET, POST, PUT и DELETE.

Для создания новой проверки необходимо отправить POST-запрос на эндпоинт /repos/{owner}/{repo}/check-runs. В теле запроса передаются данные о новой проверке, включая название, статус и детали. Для авторизации в запросе можно использовать токен доступа или авторизацию по протоколу OAuth.

Пример запроса для создания новой проверки:

POST /repos/{owner}/{repo}/check-runs
Authorization: token YOUR_TOKEN
Content-Type: application/json
{
"name": "My Check",
"head_sha": "commit_sha",
"status": "in_progress",
"conclusion": "neutral",
"output": {
"title": "Check Details",
"summary": "This is a check summary",
"text": "Additional details about the check"
}
}

Шаги по созданию и обновлению проверки:

1. Определите необходимые параметры для создания или обновления проверки, такие как название, статус, детали.
2. Сформируйте запрос на создание или обновление проверки, включая все необходимые параметры.
3. Отправьте запрос на соответствующий эндпоинт API, указав метод HTTP и авторизацию (если необходимо).
4. Обработайте ответ от сервера для дальнейших действий.

Для обновления существующей проверки используется PUT-запрос на эндпоинт /repos/{owner}/{repo}/check-runs/{check_run_id}. В теле запроса передаются данные для обновления, такие как статус и детали.

Пример запроса для обновления проверки:

PUT /repos/{owner}/{repo}/check-runs/{check_run_id}
Authorization: token YOUR_TOKEN
Content-Type: application/json
{
"status": "completed",
"conclusion": "success",
"output": {
"title": "Check Details",
"summary": "This is a check summary",
"text": "Additional details about the check"
}
}

При обновлении проверки необходимо указать идентификатор проверки (check_run_id) в URL-адресе запроса. Значение идентификатора можно получить из ответа сервера при создании или получении проверки.

После создания или обновления проверки можно получить ее статус и детали, используя соответствующий эндпоинт API.

Создание новой проверки

Для создания новой проверки вам понадобится выполнить POST-запрос к эндпоинту /repos/{owner}/{repo}/check-runs. В запросе необходимо указать следующие параметры:

owner: имя владельца репозитория

repo: название репозитория

Тело запроса должно содержать следующую информацию:

• name: имя проверки, должно быть уникальным
• head_sha: SHA-хэш коммита, для которого создается проверка
• status: статус проверки, может принимать значения "queued", "in_progress" или "completed"
• conclusion: заключение проверки, может принимать значения "success", "failure", "neutral", "cancelled" или "timed_out"
• output: объект с информацией о результате проверки, содержащий поля "title", "summary" и "text"

Пример тела запроса:

{
"name": "My Check",
"head_sha": "a12b34c56d78e90f12a34b56c78d90e1f23a45b6",
"status": "queued",
"conclusion": "neutral",
"output": {
"title": "Check Result",
"summary": "The check passed with warnings",
"text": "Some additional details about the check"
}
}

После успешного выполнения запроса вы получите ответ с информацией о созданной проверке.

Обратите внимание, что для создания проверки необходимо иметь достаточные права доступа к репозиторию.

Обновление состояния проверки

Для обновления состояния проверки в вашем репозитории на GitHub Enterprise Server 310 вы можете использовать REST API.

Чтобы обновить состояние проверки, вам понадобится выполнить HTTP-запрос по адресу:

POST /repos/{owner}/{repo}/statuses/{sha}

Где:

• {owner} - имя владельца репозитория
• {repo} - имя репозитория
• {sha} - идентификатор коммита SHA

В теле запроса вы должны указать JSON-объект с параметрами, включающими информацию о состоянии проверки. Пример запроса:

{
"state": "success",
"description": "Проверка выполнена успешно",
"context": "continuous-integration"
}

Доступные состояния проверки:

• pending - проверка выполняется
• success - проверка выполнена успешно
• failure - проверка не выполнена
• error - ошибка при выполнении проверки

После отправки запроса, состояние проверки будет обновлено в вашем репозитории на GitHub Enterprise Server 310.

Удаление проверок

Для удаления проверки необходимо выполнить HTTP-запрос методом DELETE по указанному URL-адресу. В запросе необходимо указать заголовок Authorization со значением токена доступа, полученного с использованием механизмов аутентификации GitHub.

URL-адрес для удаления проверки состоит из базового URL-адреса GitHub Enterprise Server, имя владельца репозитория, имя репозитория и номер проверки. Ниже приведен пример URL-адреса для удаления проверки:

DELETE /repos/{owner}/{repo}/check-runs/{check_run_id}

После успешного выполнения запроса проверка будет удалена из указанного репозитория. В случае возникновения ошибки будет возвращен соответствующий статус и сообщение об ошибке.

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

Удаление проверок с помощью REST API GitHub Enterprise Server дает возможность автоматизировать процесс управления проверками и интегрировать его в ваши рабочие процессы разработки.

Более подробную информацию о методах и параметрах удаления проверок можно найти в официальной документации GitHub.

Удаление одной или нескольких проверок

Чтобы удалить одну или несколько проверок в репозитории, вы можете использовать метод DELETE для конкретного эндпоинта проверок.

Чтобы удалить одну проверку, отправьте GET-запрос по эндпоинту /repos/{owner}/{repo}/checks/{check_id} и затем отправьте DELETE-запрос по тому же эндпоинту. В ответе будет возвращен код состояния 204 No Content, что означает успешное удаление проверки.

DELETE /repos/{owner}/{repo}/checks/{check_id}

Чтобы удалить несколько проверок, отправьте POST-запрос по эндпоинту /repos/{owner}/{repo}/check-suites/{check_suite_id}/rerequests с указанием списка идентификаторов проверок для удаления. В ответе будет возвращен код состояния 200 OK, что означает успешное удаление проверок.

Пример запроса для удаления нескольких проверок:

POST /repos/{owner}/{repo}/check-suites/{check_suite_id}/rerequests
{
"check_names": [
"check1",
"check2",
"check3"
]
}

Обратите внимание, что для выполнения указанных запросов вам потребуется соответствующая авторизация. Подробную информацию о передаче токена авторизации в хедере запроса смотрите в соответствующей статье в документации.

После удаления проверок, у вас будет возможность создать новые проверки или повторно запустить удаленные.