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

Сведения об управлении корпоративными учетными записями с помощью 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. Выбор метода проверки подлинности

Мы рекомендуем использовать для корпоративных операций GitHub App GraphQL, которые поддерживают его. GitHub Apps предоставьте точные разрешения и короткие маркеры без использования владельца personal access tokenпредприятия. Не все корпоративные запросы GraphQL и изменения поддерживаются GitHub Apps. Используйте для операций personal access token , которые не поддерживают их.

Использование GitHub App

GitHub App Зарегистрируйте и выберите корпоративные разрешения, необходимые для ваших операций. См . раздел AUTOTITLE.
Установите приложение на предприятии, которым требуется управлять. Если вы не являетесь владельцем предприятия, вам потребуется попросить владельца предприятия установить его. См . раздел AUTOTITLE.
Проверка подлинности с помощью маркера доступа установки или маркера доступа пользователей в зависимости от операции и того, должно ли приложение действовать от имени пользователя. Приведенные ниже инструкции по бессоннице используют маркер доступа пользователя.

Корпоративная установка предоставляет только корпоративные разрешения. Он не предоставляет доступ к организациям или репозиториям в организации. Для операций организации или репозитория приложение нуждается в отдельных установках в соответствующих организациях и соответствующих разрешениях. После установки в организациях приложение может работать с ними в запросе GraphQL с помощью маркера доступа пользователя. Маркеры установки блокируются для одной учетной записи предприятия или организации и не могут использоваться в пределах учетной записи.

Использование personal access token

Используйте, personal access token если операция, необходимая не поддерживается GitHub Apps, или если вы создаете автоматизацию для доступа к нескольким организациям или данным репозитория в одном запросе GraphQL.

Чтобы выполнить проверку подлинности с помощью 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: Читайте и записывая данные корпоративного биллинга.
- read:enterprise: чтение данных профиля организации.
Скопируйте свой personal access token и храните в надёжном месте, пока не добавите в клиент GraphQL.

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

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

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

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

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

Добавьте базовый 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

Проверка подлинности с помощью GitHub App

Эта процедура использует поток кода авторизации OAuth 2.0 для получения GitHub Appмаркера доступа пользователя, а не маркера доступа к установке.

В параметрах приложения задайте URL-адресhttp://localhostобратного вызова. Это должно точно соответствовать URL-адресу перенаправления , используемому в бессоннице.
Скопируйте идентификатор клиента приложения, а не его идентификатор приложения. Создайте и скопируйте секрет клиента. Защитите секрет и не делитесь им в снимках экранах или исходном коде. Этот поток не использует закрытый ключ приложения.
В бессоннице выберите вкладку "Аутентификация ", а затем выберите OAuth 2.0. Если вы ранее выбрали другой метод проверки подлинности, вкладка может быть помечена этим методом.

Настройте эти параметры с помощью учетных данных собственного приложения.

Setting	Value
Enabled	✔️
Тип гранта	Код авторизации
URL-адрес авторизации	`https://github.com/login/oauth/authorize`
URL-адрес маркера доступа	`https://github.com/login/oauth/access_token`
идентификатор клиента	Идентификатор клиента приложения
Секрет клиента	Секрет клиента приложения
Использование PKCE

Выбранные | | | | Метод вызова кода | SHA-256 | | | | URL-адрес перенаправления | http://localhost | | Использование браузера по умолчанию | Оставьте флажок без проверки, если ваше предприятие не включило единый вход, который может завершиться ошибкой в встроенном браузере Бессонницы. Если у него включен единый вход, установите этот флажок и следуйте указаниям по обновлению URL-адреса перенаправления приложения. | | Scope | Оставьте пустым. GitHub Apps используйте разрешения для регистрации приложения, а не области OAuth. |

Если вы используете GitHub Enterprise Cloud для размещения данных, замените https://github.com оба URL-адреса https://SUBDOMAIN.ghe.comOAuth на , где SUBDOMAIN находится поддомен вашего предприятия. Используйте веб-URL-адрес, а не api.SUBDOMAIN.ghe.com имя узла.

Щелкните "Получить маркеры", войдите и авторизовать приложение в качестве пользователя с необходимыми корпоративными разрешениями. Маркер доступа пользователя ограничен разрешениями и ресурсами, к которым может получить доступ пользователь и приложение. Бессонница использует маркер получения для ваших запросов.

Для получения дополнительной информации см. Генерация токена доступа пользователя для приложения GitHub.

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

Если вы используете personal access token вместо этого, настройте проверку подлинности носителя.

Выберите меню проверки подлинности и щелкните маркер носителя. Если вы ранее выбрали другой метод проверки подлинности, меню будет помечено этим методом, например "Базовая проверка подлинности", вместо этого.
В поле «TOKEN» введите свой personal access token с более раннего шага.

Снимок экрана: параметры проверки подлинности "Носителя" в бессоннице. Поле 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
            }
          }
        }
      }
    }
  }
}

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

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

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

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