团队同步

团队同步 API 允许您管理 GitHub Enterprise Cloud 团队与外部身份提供程序 (IdP) 组之间的连接。

关于团队同步 API

要使用此 API，经过身份验证的用户必须是团队维护员或与团队关联的组织的所有者。用于身份验证的令牌还需要获得授权才能与 IdP (SSO) 提供程序一起使用。更多信息请参阅“授权个人访问令牌用于 SAML 单点登录组织”。

您可以通过 IdP 通过团队同步管理 GitHub 团队成员。必须启用团队同步才能使用团队同步 API。更多信息请参阅“在身份提供程序与 GitHub 之间同步团队”。

注意： 团队同步 API 不能与企业托管用户一起使用。要了解有关管理具有托管用户的组织的更多信息，请参阅“外部组 API”。

List IdP groups for an organization

Team synchronization is available for organizations using GitHub Enterprise Cloud. For more information, see GitHub's products in the GitHub Help documentation.

List IdP groups available in an organization. You can limit your page results using the per_page parameter. GitHub generates a url-encoded page token using a cursor value for where the next page begins. For more information on cursor pagination, see "Offset and Cursor Pagination explained."

参数

标头
名称, 类型, 描述
`accept`string Setting to `application/vnd.github+json` is recommended.
路径参数
名称, 类型, 描述
`org`string必选 The organization name. The name is not case sensitive.
查询参数
名称, 类型, 描述
`per_page`integer The number of results per page (max 100). 默认值: `30`
`page`string Page token

HTTP 响应状态代码

状态代码	描述
`200`	OK

代码示例

get/orgs/{org}/team-sync/groups

curl \
  -H "Accept: application/vnd.github+json" \ 
  -H "Authorization: token <TOKEN>" \
  https://api.github.com/orgs/ORG/team-sync/groups

Response

Status: 200

{
  "groups": [
    {
      "group_id": "123",
      "group_name": "Octocat admins",
      "group_description": "The people who configure your octoworld."
    },
    {
      "group_id": "456",
      "group_name": "Octocat docs members",
      "group_description": "The people who make your octoworld come to life."
    }
  ]
}

List IdP groups for a team

Team synchronization is available for organizations using GitHub Enterprise Cloud. For more information, see GitHub's products in the GitHub Help documentation.

List IdP groups connected to a team on GitHub.

Note: You can also specify a team by org_id and team_id using the route GET /organizations/{org_id}/team/{team_id}/team-sync/group-mappings.

参数

标头
名称, 类型, 描述
`accept`string Setting to `application/vnd.github+json` is recommended.
路径参数
名称, 类型, 描述
`org`string必选 The organization name. The name is not case sensitive.
`team_slug`string必选 The slug of the team name.

HTTP 响应状态代码

状态代码	描述
`200`	OK

代码示例

get/orgs/{org}/teams/{team_slug}/team-sync/group-mappings

curl \
  -H "Accept: application/vnd.github+json" \ 
  -H "Authorization: token <TOKEN>" \
  https://api.github.com/orgs/ORG/teams/TEAM_SLUG/team-sync/group-mappings

Response

Status: 200

{
  "groups": [
    {
      "group_id": "123",
      "group_name": "Octocat admins",
      "group_description": "The people who configure your octoworld."
    },
    {
      "group_id": "456",
      "group_name": "Octocat docs members",
      "group_description": "The people who make your octoworld come to life."
    }
  ]
}

Create or update IdP group connections

Team synchronization is available for organizations using GitHub Enterprise Cloud. For more information, see GitHub's products in the GitHub Help documentation.

Creates, updates, or removes a connection between a team and an IdP group. When adding groups to a team, you must include all new and existing groups to avoid replacing existing groups with the new ones. Specifying an empty groups array will remove all connections for a team.

Note: You can also specify a team by org_id and team_id using the route PATCH /organizations/{org_id}/team/{team_id}/team-sync/group-mappings.

参数

标头

名称, 类型, 描述

acceptstring

Setting to application/vnd.github+json is recommended.

路径参数

名称, 类型, 描述

orgstring必选

The organization name. The name is not case sensitive.

team_slugstring必选

The slug of the team name.

正文参数

名称, 类型, 描述

groupsarray of objects

The IdP groups you want to connect to a GitHub team. When updating, the new groups object will replace the original one. You must include any existing groups that you don't want to remove.

Properties of thegroupsitems

名称, 类型, 描述
`group_id`string必选 ID of the IdP group.
`group_name`string必选 Name of the IdP group.
`group_description`string必选 Description of the IdP group.

HTTP 响应状态代码

状态代码	描述
`200`	OK

代码示例

patch/orgs/{org}/teams/{team_slug}/team-sync/group-mappings

curl \
  -X PATCH \
  -H "Accept: application/vnd.github+json" \ 
  -H "Authorization: token <TOKEN>" \
  https://api.github.com/orgs/ORG/teams/TEAM_SLUG/team-sync/group-mappings \
  -d '{"groups":[{"group_id":"123","group_name":"Octocat admins","group_description":"string"}]}'

Response

Status: 200

{
  "groups": [
    {
      "group_id": "123",
      "group_name": "Octocat admins",
      "group_description": "The people who configure your octoworld."
    },
    {
      "group_id": "456",
      "group_name": "Octocat docs members",
      "group_description": "The people who make your octoworld come to life."
    }
  ]
}

List IdP groups for a team (Legacy)

Deprecation Notice: This endpoint route is deprecated and will be removed from the Teams API. We recommend migrating your existing code to use the new List IdP groups for a team endpoint.

Team synchronization is available for organizations using GitHub Enterprise Cloud. For more information, see GitHub's products in the GitHub Help documentation.

List IdP groups connected to a team on GitHub.

参数

标头
名称, 类型, 描述
`accept`string Setting to `application/vnd.github+json` is recommended.
路径参数
名称, 类型, 描述
`team_id`integer必选 The unique identifier of the team.

HTTP 响应状态代码

状态代码	描述
`200`	OK
`403`	Forbidden
`404`	Resource not found

代码示例

get/teams/{team_id}/team-sync/group-mappings

curl \
  -H "Accept: application/vnd.github+json" \ 
  -H "Authorization: token <TOKEN>" \
  https://api.github.com/teams/TEAM_ID/team-sync/group-mappings

Response

Status: 200

{
  "groups": [
    {
      "group_id": "123",
      "group_name": "Octocat admins",
      "group_description": "The people who configure your octoworld."
    },
    {
      "group_id": "456",
      "group_name": "Octocat docs members",
      "group_description": "The people who make your octoworld come to life."
    }
  ]
}

Create or update IdP group connections (Legacy)

Deprecation Notice: This endpoint route is deprecated and will be removed from the Teams API. We recommend migrating your existing code to use the new Create or update IdP group connections endpoint.

Team synchronization is available for organizations using GitHub Enterprise Cloud. For more information, see GitHub's products in the GitHub Help documentation.

Creates, updates, or removes a connection between a team and an IdP group. When adding groups to a team, you must include all new and existing groups to avoid replacing existing groups with the new ones. Specifying an empty groups array will remove all connections for a team.

参数

标头

名称, 类型, 描述

acceptstring

Setting to application/vnd.github+json is recommended.

路径参数

名称, 类型, 描述

team_idinteger必选

The unique identifier of the team.

正文参数

名称, 类型, 描述

groupsarray of objects必选

The IdP groups you want to connect to a GitHub team. When updating, the new groups object will replace the original one. You must include any existing groups that you don't want to remove.

Properties of thegroupsitems

名称, 类型, 描述
`group_id`string必选 ID of the IdP group.
`group_name`string必选 Name of the IdP group.
`group_description`string必选 Description of the IdP group.
`id`string
`name`string
`description`string

synced_atstring

HTTP 响应状态代码

状态代码	描述
`200`	OK
`403`	Forbidden
`422`	Validation failed

代码示例

patch/teams/{team_id}/team-sync/group-mappings

curl \
  -X PATCH \
  -H "Accept: application/vnd.github+json" \ 
  -H "Authorization: token <TOKEN>" \
  https://api.github.com/teams/TEAM_ID/team-sync/group-mappings \
  -d '{"groups":[{"group_id":"123","group_name":"Octocat admins","description":"The people who configure your octoworld.","group_description":"string"}]}'

Response

Status: 200

{
  "groups": [
    {
      "group_id": "123",
      "group_name": "Octocat admins",
      "group_description": "The people who configure your octoworld."
    }
  ]
}