管理企业帐户

关于使用 GraphQL 管理企业帐户

为帮助您监测和更改组织并保持合规性，可以使用只能作为 GraphQL API 的企业帐户 API 和审核日志 API。

企业帐户端点适用于 GitHub Enterprise Cloud 和 GitHub Enterprise Server。

使用 GraphQL 可以请求并仅返回指定的数据。例如，可以创建 GraphQL 查询或请求信息，以查看添加到组织的所有新组织成员。或者，可以做出更改，以邀请管理员加入企业帐户。

使用审核日志 API，可以监视下列行为：

访问组织或存储库设置。
更改权限。
在组织、存储库或团队中添加或删除用户。
将用户提升为管理员。
更改 GitHub 应用权限。

使用审核日志 API 可以保留审核日志数据的副本。对于使用审核日志 API 执行的查询，GraphQL 响应最多可包含 90 至 120 天的数据。有关审核日志 API 提供的字段列表，请参阅“接口”。

通过企业帐户 API，可以：

列出并审查属于企业帐户的所有组织和仓库。
更改企业帐户设置。
配置企业帐户及其组织的设置策略。
邀请管理员加入您的企业帐户。
在企业帐户中创建新组织。

有关企业帐户 API 提供的字段列表，请参阅“管理企业帐户”。

开始将 GraphQL 用于企业帐户

按照以下步骤开始利用 GraphQL 管理企业帐户：

使用 personal access token 进行身份验证
选择 GraphQL 客户端或使用 GraphQL Explorer
设置 Insomnia 以使用 GraphQL API

如需一些示例查询，请参阅“使用企业帐户 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 或可用于配置基准 URL 的其他独立 GraphQL 客户端。

也可以考虑使用以下 GraphQL 客户端：

接下来将使用 Insomnia。

3. 设置 Insomnia，将 GitHub GraphQL API 用于企业帐户

将基 url 和 POST 方法添加至 GraphQL 客户端。使用 GraphQL 请求信息（查询）、更改信息（突变）或使用 GitHub API 传输数据时，默认 HTTP 方法为 POST，基 url 遵循此语法：
- 对于企业实例：https://<HOST>/api/graphql
- 对于 GitHub Enterprise 云：https://api.github.com/graphql
选择“身份验证”菜单，然后单击“持有者令牌”。如果之前选择了其他身份验证方法，则菜单将改为使用该方法（例如“基本身份验证”）进行标记。
在“令牌”字段中，输入前面步骤中的 personal access token。
单击“标头”。
在“标头”选项卡下，单击“添加”。
在“标头”字段中，输入 Content-Type。
在“值”字段中，输入 application/json。

现在可以开始执行查询了。

此 GraphQL 查询使用 Enterprise Accounts API 请求每个设备的组织中 public 存储库的总数。要自定义此查询，请用企业帐户的句柄替换 <enterprise-account-name>。例如，如果企业帐户位于 https://github.com/enterprises/octo-enterprise，请用 octo-enterprise 替换 <enterprise-account-name>。

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 查询示例显示了在不使用企业帐户 API 的情况下检索每个组织中的 public 存储库总数的难度。请注意，GraphQL 企业账户 API 已使企业执行此任务变得更简单，因为您只需要自定义单个变量。要自定义此查询，请将 <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 查询用于请求企业组织的最后 5 个日志条目。要自定义此查询，请替换 <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 建立调用”。

企业账户 API 的 GraphQL 字段和类型

有关可与企业帐户 API 结合使用的新查询、突变和架构定义类型的详细信息，请参阅任何 GraphQL 参考页面含有详细 GraphQL 定义的边栏。

您可以从 GitHub 的 GraphQL explorer 访问参考文档。有关详细信息，请参阅“使用 Explorer”。有关其他信息，如身份验证和速率限制详细信息，请查看指南。

本文内容