Сведения об управлении корпоративными учетными записями с помощью GraphQL
Чтобы отслеживать отделы, вносить в них изменения и обеспечивать соответствие требованиям, можно использовать API корпоративных учетных записей и API журнала аудита, которые доступны только в виде API GraphQL.
Конечные точки корпоративной учетной записи работают как для облака GitHub Enterprise, так и для сервера GitHub Enterprise.
GraphQL позволяет вам запрашивать и возвращать только указанные данные. Например, вы можете создать запрос GraphQL или запросить сведения, чтобы увидеть всех новых участников, добавленных в вашу организацию. Вы также можете внести изменения, чтобы пригласить администратора в вашу корпоративную учетную запись.
С помощью API журнала аудита вы можете отслеживать, когда кто-то:
- Обращается к параметрам вашей организации или репозитория.
- Изменяет разрешения.
- Добавляет или удаляет пользователей в организации, репозитории или команде.
- Повышает уровень пользователей до администраторов.
- Изменяет разрешения приложения GitHub.
API журнала аудита позволяет сохранять копии данных вашего журнала аудита. Для запросов, выполненных с помощью API журнала аудита, ответ GraphQL может содержать данные давностью до 90–120 дней. Список полей, доступных в API журнала аудита, см. в разделе "Интерфейсы".
API корпоративных учетных записей обеспечивает следующие возможности:
- вывод списка и просмотр всех отделов и репозиториев, принадлежащих вашей корпоративной учетной записи;
- изменение параметров корпоративной учетной записи;
- настройка политик для параметров корпоративной учетной записи и ее отделов;
- приглашение администраторов в корпоративную учетную запись;
- создание отделов в корпоративной учетной записи.
Список полей, доступных в API корпоративных учетных записей, см. в разделе "Управление корпоративными учетными записями".
Начало работы с GraphQL для корпоративных учетных записей
Чтобы приступить к использованию GraphQL для управления корпоративными учетными записями, выполните указанные ниже действия.
- Проверка подлинности с помощью personal access token
- Выберите клиент GraphQL или используйте обозреватель GraphQL.
- Настройте Insomnia для использования API GraphQL.
Примеры запросов см. в разделе Пример запроса с использованием API корпоративных учетных записей.
1. Проверка подлинности с помощью personal access token
-
Чтобы выполнить проверку подлинности с помощью GraphQL, необходимо создать personal access token из параметров разработчика. Дополнительные сведения см. в разделе Управление личными маркерами доступа.
-
Предоставьте администраторам и разрешениям на полный контроль для ваших personal access token для областей вашего предприятия, к которым вы хотите получить доступ. Для полного разрешения на частные репозитории, организации, команды, пользовательские данные и доступ к корпоративным данным выставления счетов и профилей рекомендуется выбрать эти области для personal access token:
repoadmin:orguseradmin:enterprise
Области, относящиеся к корпоративной учетной записи:
admin:enterprise: обеспечивает полный контроль над предприятиями (включаяmanage_runners:enterprise``manage_billing:enterpriseиread:enterprise)manage_billing:enterprise: чтение и запись корпоративных данных выставления счетов.manage_runners:enterprise: доступ к управлению корпоративными средствами выполнения GitHub Actions и их группами;read:enterprise: чтение данных профиля организации.
-
Скопируйте данные personal access token и сохраните его в безопасном месте, пока не добавите его в клиент GraphQL.
2. Выбор клиента GraphQL
Мы рекомендуем использовать GraphiQL или другой автономный клиент GraphQL, который позволяет настроить базовый URL-адрес.
Возможные варианты клиентов GraphQL:
Далее будет использоваться клиент Insomnia.
3. Настройка Insomnia для использования API GraphQL для GitHub с корпоративными учетными записями
-
Добавьте базовый URL-адрес и метод
POSTв клиент GraphQL. При использовании GraphQL для запроса сведений, изменения сведений или передачи данных с помощью API GitHub методом HTTP по умолчанию являетсяPOST, а базовый URL-адрес соответствует следующему синтаксису:- Для экземпляра Enterprise:
https://<HOST>/api/graphql - Для облака GitHub Enterprise:
https://api.github.com/graphql
- Для экземпляра Enterprise:
-
Выберите меню "Аутентификация" и щелкните маркер носителя. Если вы ранее выбрали другой метод проверки подлинности, меню будет помечено этим методом, например "Базовая проверка подлинности", вместо этого.
-
В поле "TOKEN" введите personal access token на предыдущем шаге.
-
Щелкните заголовки.
-
На вкладке "Заголовки" нажмите кнопку "Добавить".
-
В поле "заголовок" введите
Content-Type. -
В поле "значение" введите
application/json.
Теперь все готово для выполнения запросов.
Пример запроса с использованием API корпоративных учетных записей
Этот запрос GraphQL запрашивает общее количество public репозиториев в каждой организации устройства с помощью API корпоративных учетных записей. Чтобы настроить запрос, замените <enterprise-account-name> на дескриптор вашей корпоративной учетной записи. Например, если ваша корпоративная учетная запись находится по адресу https://github.com/enterprises/octo-enterprise, замените <enterprise-account-name> на octo-enterprise.
query publicRepositoriesByOrganization($slug: String!) {
enterprise(slug: $slug) {
...enterpriseFragment
}
}
fragment enterpriseFragment on Enterprise {
... on Enterprise{
name
organizations(first: 100){
nodes{
name
... on Organization{
name
repositories(privacy: PUBLIC){
totalCount
}
}
}
}
}
}
# Passing our Enterprise Account as a variable
variables {
"slug": "<enterprise-account-name>"
}
В следующем примере запроса GraphQL показано, насколько сложно получить количество public репозиториев в каждой организации без использования API корпоративной учетной записи. Обратите внимание, что API корпоративных учетных записей GraphQL упрощает эту задачу для организаций, так как нужно настроить лишь одну переменную. Чтобы настроить этот запрос, замените <name-of-organization-one>, <name-of-organization-two> и т. д. на названия отделов в вашем экземпляре.
# Each organization is queried separately
{
organizationOneAlias: organization(login: "nameOfOrganizationOne") {
# How to use a fragment
...repositories
}
organizationTwoAlias: organization(login: "nameOfOrganizationTwo") {
...repositories
}
# organizationThreeAlias ... and so on up-to lets say 100
}
## How to define a fragment
fragment repositories on Organization {
name
repositories(privacy: PUBLIC){
totalCount
}
}
Запрос сведения о каждом отделе по отдельности
query publicRepositoriesByOrganization {
organizationOneAlias: organization(login: "<name-of-organization-one>") {
# How to use a fragment
...repositories
}
organizationTwoAlias: organization(login: "<name-of-organization-two>") {
...repositories
}
# organizationThreeAlias ... and so on up-to lets say 100
}
# How to define a fragment
fragment repositories on Organization {
name
repositories(privacy: PUBLIC){
totalCount
}
}
Этот запрос GraphQL должен вернуть последние пять записей журнала для отдела организации. Чтобы настроить этот запрос, замените <org-name> и <user-name>.
{
organization(login: "<org-name>") {
auditLog(last: 5, query: "actor:<user-name>") {
edges {
node {
... on AuditEntry {
# Get Audit Log Entry by 'Action'
action
actorLogin
createdAt
# User 'Action' was performed on
user{
name
email
}
}
}
}
}
}
}
Дополнительные сведения о начале работы с GraphQL см. в разделе "[AUTOTITLE" и "Общие сведения о GraphQL](/graphql/guides/forming-calls-with-graphql)".
Поля и типы GraphQL для API корпоративных учетных записей
Дополнительные сведения о новых запросах, изменениях и определенных в схеме типов, доступных для использования с API корпоративных учетных записей, см. на боковой панели с подробными определениями GraphQL на любой странице справки по GraphQL.
Справочная документация доступна из обозревателя GraphQL на GitHub. Дополнительные сведения см. в разделе Использование обозревателя. Другие сведения, например о проверке подлинности и ограничении скорости, см. в руководствах.