管理企业帐户

关于使用 GraphQL 管理企业帐户

为帮助您监测和更改组织以保持合规性，可以使用企业帐户 API 和审核日志 API，这些 API 仅以 GraphQL API 的形式提供。

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

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

使用审核日志 API，您可以监视何时有人：

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

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

通过企业帐户 API，可以：

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

有关企业帐户 API 可用的字段的列表，请参阅管理企业帐户。

企业帐户 GraphQL 入门指南

请参阅使用 GraphQL 客户端，以开始使用 GraphQL 管理企业帐户。

如需一些示例查询，请参阅使用企业帐户 API 的示例查询。

1.选择身份验证方法

建议对支持它的企业 GraphQL 操作使用 GitHub App 。 GitHub Apps 提供精细的权限和生存期较短的令牌，而无需依赖企业所有者的 personal access token。并非所有企业 GraphQL 查询和变更都支持 GitHub Apps。对不支持personal access token的操作使用personal access token。

使用 GitHub App

注册一个GitHub App，并选择操作所需的企业权限。请参阅“注册GitHub应用”。
在您要管理的企业中安装该应用。如果你不是企业所有者，则需要要求企业所有者安装它。请参阅“在企业上安装 GitHub App”。
根据操作以及应用是否需要代表用户执行操作，使用安装访问令牌或用户访问令牌进行身份验证。下面的 Insomnia 说明使用用户访问令牌。

企业安装仅授予企业权限。它不授予对企业中的组织或存储库的访问权限。对于组织或存储库操作，应用需要在相关组织中单独安装，并具备适当的权限。在这些组织中安装后，应用可以使用用户访问令牌通过 GraphQL 查询跨这些组织运行。安装令牌锁定到单个企业或组织帐户，不能跨帐户边界使用。

使用 personal access token

如果所需的操作不支持 personal access token，或者要构建自动化以在单个 GraphQL 查询中访问多个组织或存储库数据，请使用一个 GitHub Apps。

若要使用 personal access token 进行 GraphQL 身份验证，请在开发人员设置中创建一个。有关详细信息，请参阅管理个人访问令牌。
授予你的 personal access token 对你希望访问的企业区域的 admin 和完全控制权限。若要获得对私有仓库、组织、团队、用户数据以及企业计费和个人资料数据的完整访问权限，我们建议为您的 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 或可用于配置基准 URL 的其他独立 GraphQL 客户端。

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

接下来将使用 Insomnia。

3. 配置 Insomnia 以使用 GitHub GraphQL API 与企业帐户集成

将基 url 和 POST 方法添加至 GraphQL 客户端。使用 GraphQL 请求信息（查询）、更改信息（突变）或使用 GitHub API 传输数据时，默认 HTTP 方法POST，基 URL 遵循以下语法：
- 针对您的企业实例：https://<HOST>/api/graphql
- 对于 GitHub Enterprise Cloud：https://api.github.com/graphql
- 对于具有数据驻留的 GitHub Enterprise Cloud：https://api.SUBDOMAIN.ghe.com/graphql

使用 a GitHub App 进行身份验证

此过程使用 OAuth 2.0 授权代码流来获取 GitHub App用户访问令牌，而不是安装访问令牌。

在应用的设置中，将 回调 URL 设置为 http://localhost。这必须与在 Insomnia 中使用的 重定向 URL 完全匹配。
复制应用的 Client ID，而不是应用 ID。生成并复制客户端密钥。确保机密安全，不要在屏幕截图或源代码中共享它。此流不使用应用的私钥。
在“Insomnia”中，选择 “身份验证” 选项卡，然后选择 “OAuth 2.0”。如果以前选择了其他身份验证方法，该选项卡可能会标有该方法。

使用自己的应用的凭据配置这些设置。

设置	Value
已启用	✔️
授予类型	授权代码
授权 URL	`https://github.com/login/oauth/authorize`
访问令牌 URL	`https://github.com/login/oauth/access_token`
客户端 ID	您的应用的客户端 ID
客户端密码	应用的客户端密钥
使用 PKCE

如果使用GitHub Enterprise Cloud数据驻留，请将两个 OAuth URL 中的 https://github.com 替换为 https://SUBDOMAIN.ghe.com，其中 SUBDOMAIN 是您的企业子域。使用 Web URL，而不是 api.SUBDOMAIN.ghe.com 主机名。

单击“提取令牌”，登录，并以具有所需企业权限的用户身份授权该应用。用户访问令牌仅限于用户和应用可以访问的权限和资源。 Insomnia 将提取的令牌用于你的请求。

有关详细信息，请参阅为 GitHub 应用生成用户访问令牌。

使用 a personal access token 进行身份验证

如果改用 personal access token，请配置 Bearer 身份验证。

选择 Auth 菜单，然后单击 Bearer Token。如果之前选择了其他身份验证方法，则菜单将改为使用该方法（例如“基本身份验证”）进行标记。
在“TOKEN”字段中，输入你在前一步中获得的 personal access token。

Insomnia 中“持有者”身份验证设置的屏幕截图。 “令牌”字段以深橙色框出。

设置内容类型

配置身份验证方法后，设置请求的内容类型。

单击“标头”。

Insomnia 中的“设置”选项卡的屏幕截图。 “标头”选项卡以深橙色框出。

在“标头”选项卡下，单击“添加”。
在“标头”字段中，输入 Content-Type。
在“值”字段中，输入 application/json。

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

使用企业账户 API 的查询示例

此 GraphQL 查询使用 Enterprise Accounts API 请求每个设备的组织中 public 存储库的总数。要自定义此查询，请用企业帐户的标识替换 <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 查询示例显示了在不使用企业帐户 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 定义。

可以通过 GraphQL 客户端访问参考文档。有关详细信息，请参阅使用 GraphQL 客户端。有关身份验证和速率限制详细信息等其他信息，请查看 guides。

在本文中