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

Вы можете управлять корпоративной учетной записью и организациями, которыми она владеет, с помощью API GraphQL.

В этой статье

Сведения об управлении корпоративными учетными записями с помощью GraphQL

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

Конечные точки корпоративных аккаунтов работают как для GitHub Enterprise Cloud, так и для GitHub Enterprise Server.

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

С помощью API журнала аудита вы можете отслеживать, когда кто-то:

  • Обращается к параметрам вашей организации или репозитория.
  • Изменяет разрешения.
  • Добавляет или удаляет пользователей в организации, репозитории или команде.
  • Повышает уровень пользователей до администраторов.
  • Меняет права доступа приложения GitHub.

API журнала аудита позволяет сохранять копии данных вашего журнала аудита. Для запросов, выполненных с помощью API журнала аудита, ответ GraphQL может содержать данные давностью до 90–120 дней. Список полей, доступных в API журнала аудита, см. в разделе AUTOTITLE.

API корпоративных учетных записей обеспечивает следующие возможности:

  • вывод списка и просмотр всех отделов и репозиториев, принадлежащих вашей корпоративной учетной записи;
  • изменение параметров корпоративной учетной записи;
  • настройка политик для параметров корпоративной учетной записи и ее отделов;
  • приглашение администраторов в корпоративную учетную запись;
  • создание отделов в корпоративной учетной записи.

Список полей, доступных в API Enterprise Accounts, см. Управление корпоративными учетными записями.

Getting started с использованием GraphQL для корпоративных аккаунтов

См. Использование клиентов GraphQL чтобы get started использование GraphQL для управления корпоративными аккаунтами.

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

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

  1. Чтобы выполнить проверку подлинности с помощью GraphQL, необходимо создать personal access token из параметров разработчика. Для получения дополнительной информации см. Управление личными маркерами доступа.

  2. Предоставьте администраторам и полные права контроля вашим personal access token для тех областей вашего предприятия, которые вы хотите access. Для получения полного разрешения на частные репозитории, организации, команды, пользовательские данные и access для корпоративных биллингов и профилей рекомендуем выбрать следующие области для вашего personal access token:

    • repo
    • admin:org
    • user
    • admin:enterprise

    Области, относящиеся к корпоративной учетной записи: * admin:enterprise: обеспечивает полный контроль над предприятиями (включая manage_runners:enterprise``manage_billing:enterprise иread:enterprise) * manage_billing:enterprise: чтение и запись корпоративных данных выставления счетов. * read:enterprise: чтение данных профиля организации.

  3. Скопируйте данные personal access token и сохраните его в безопасном месте, пока не добавите его в клиент GraphQL.

2. Выбор клиента GraphQL

Мы рекомендуем использовать GraphiQL или другой автономный клиент GraphQL, который позволяет настроить базовый URL-адрес.

Возможные варианты клиентов GraphQL: * Insomnia * GraphiQL * Postman

Далее будет использоваться клиент Insomnia.

3. Настройка Insomnia для использования API GitHub GraphQL с корпоративными аккаунтами

  1. Добавьте базовый URL-адрес и метод POST в клиент GraphQL. При использовании GraphQL для запроса информации (запросов), изменения информации (мутаций) или передачи данных с помощью GitHub API по умолчанию используется HTTP-метод POST, а базовый URL соответствует следующему синтаксису:

    • Для экземпляра Enterprise: https://<HOST>/api/graphql
    • Для GitHub Enterprise Cloud: https://api.github.com/graphql
    • Для GitHub Enterprise Cloud с Data Residency: https://api.SUBDOMAIN.ghe.com/graphql

  2. Выберите меню "Аутентификация" и щелкните маркер носителя. Если вы ранее выбрали другой метод проверки подлинности, меню будет помечено этим методом, например "Базовая проверка подлинности", вместо этого.

           ![Снимок экрана: развернутое меню "Аутентификация" в Бессоннице. Метка меню", "Auth" и параметр "Токен носителя" описаны в темно-оранжевый цвет.](/assets/images/developer/graphql/insomnia-bearer-token-option.png)

  3. В поле "TOKEN" введите personal access token на предыдущем шаге.

           ![Снимок экрана: параметры проверки подлинности "Носителя" в бессоннице. Поле TOKEN описывается в темно-оранжевый цвет.](/assets/images/developer/graphql/insomnia-base-url-and-pat.png)

  4. Щелкните заголовки.

           ![Снимок экрана: вкладки "Параметры" в "Бессонница". Вкладка "Заголовки" выделена темно-оранжевым цветом.](/assets/images/developer/graphql/json-content-type-header.png)

  5. На вкладке "Заголовки" нажмите кнопку "Добавить".

  6. В поле "заголовок" введите Content-Type.

  7. В поле "значение" введите 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
            }
          }
        }
      }
    }
  }
}

Для получения дополнительной информации о getting started с GraphQL см. Общие сведения о GraphQL и Формирование вызовов с помощью GraphQL.

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

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

Вы можете access к справочным документам внутри клиентов GraphQL. Для получения дополнительной информации см. Использование клиентов GraphQL. Для другой информации, например, аутентификации и ограничения скорости, посмотрите guides.