Управление корпоративными учетными записями

Сведения об управлении корпоративными учетными записями с помощью 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:
- repo
- admin:org
- user
- admin: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
Выберите меню "Проверка подлинности" и щелкните Токен носителя. Если вы ранее выбрали другой метод проверки подлинности, в меню будет указан этот метод, например "Обычная проверка подлинности".
В поле TOKEN введите personal access token из предыдущего шага.
Щелкните Заголовки.
На вкладке Заголовки нажмите кнопку Добавить.
В поле header введите Content-Type.
В поле "значение" введите application/json.

Теперь все готово для выполнения запросов.

Пример запроса с использованием API корпоративных учетных записей

Этот запрос GraphQL должен вернуть общее количество репозиториев private в каждом отделе организации с помощью API корпоративных учетных записей. Чтобы настроить запрос, замените <enterprise-account-name> на дескриптор вашей корпоративной учетной записи. Например, если ваша корпоративная учетная запись находится по адресу https://github.com/enterprises/octo-enterprise, замените <enterprise-account-name> на octo-enterprise.

query privateRepositoriesByOrganization($slug: String!) {
  enterprise(slug: $slug) {
    ...enterpriseFragment
  }
}

fragment enterpriseFragment on Enterprise {
  ... on Enterprise{
    name
    organizations(first: 100){
      nodes{
        name
        ... on Organization{
          name
          repositories(privacy: PRIVATE){
            totalCount
          }
        }
      }
    }
  }
}

# Passing our Enterprise Account as a variable
variables {
  "slug": "<enterprise-account-name>"
}

В следующем примере запроса GraphQL показано, насколько сложно получить количество репозиториев private в каждом отделе без использования API корпоративных учетных записей. Обратите внимание, что API корпоративных учетных записей GraphQL упрощает эту задачу для организаций, так как нужно настроить лишь одну переменную. Чтобы настроить этот запрос, замените <name-of-organization-one>, <name-of-organization-two> и т. д. на названия отделов в вашем экземпляре.

# Each organization is queried separately
{
  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: PRIVATE){
    totalCount
  }
}

Запрос сведения о каждом отделе по отдельности

query privateRepositoriesByOrganization {
  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: PRIVATE){
    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 см. в разделах Общие сведения о GraphQL и Формирование вызовов с помощью GraphQL.

Поля и типы GraphQL для API корпоративных учетных записей

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

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

Справочная документация доступна из обозревателя GraphQL на GitHub. Дополнительные сведения см. в разделе Использование обозревателя. Другие сведения, например о проверке подлинности и ограничении скорости, см. в руководствах.

Управление корпоративными учетными записями

В этой статье