关于使用 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
:读取和写入企业账单数据。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
。
现在可以开始执行查询了。
使用企业账户 API 的查询示例
此 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”。 有关其他信息,如身份验证和速率限制详细信息,请查看指南。