REST API 现在已实现版本控制。 更多信息，请参见“关于 API 版本控制”。

自定义属性的 REST API 端点

使用 REST API 创建和管理组织的自定义属性。

关于自定义属性

您可以使用 REST API 创建和管理组织的自定义属性。您可以使用自定义属性向组织中的代码仓库添加元数据。更多信息，请参见“管理组织中代码仓库的自定义属性”。

获取组织的所有自定义属性

获取为组织定义的所有自定义属性。组织成员可以读取这些属性。

“获取组织的所有自定义属性”的细粒度访问令牌

此端点可与以下细粒度令牌类型配合使用:

细粒度令牌必须具有以下权限集

  • “自定义属性”组织权限（读取）

“获取组织的所有自定义属性”的参数

标头
accept 字符串

建议设置为application/vnd.github+json。

路径参数
org 字符串 必填

组织名称。名称不区分大小写。

“获取组织的所有自定义属性”的 HTTP 响应状态代码

状态代码描述
200

OK

403

禁止

404

资源未找到

“获取组织的所有自定义属性”的代码示例

请求示例

get/orgs/{org}/properties/schema
curl -L \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/orgs/ORG/properties/schema

响应

状态：200
[ { "property_name": "environment", "url": "https://api.github.com/orgs/github/properties/schema/environment", "source_type": "organization", "value_type": "single_select", "required": true, "default_value": "production", "description": "生产或开发环境", "allowed_values": [ "production", "development" ], "values_editable_by": "org_actors" }, { "property_name": "service", "url": "https://api.github.com/orgs/github/properties/schema/service", "source_type": "organization", "value_type": "string" }, { "property_name": "team", "url": "https://api.github.com/orgs/github/properties/schema/team", "source_type": "organization", "value_type": "string", "description": "拥有代码仓库的团队" } ]

创建或更新组织的自定义属性

批量创建新的或更新为组织定义的现有自定义属性。

要使用此端点，经过身份验证的用户必须是以下用户之一：

  • 组织管理员。
  • 拥有组织中custom_properties_org_definitions_manager细粒度权限的用户或团队中的用户。

“创建或更新组织的自定义属性”的细粒度访问令牌

此端点可与以下细粒度令牌类型配合使用:

细粒度令牌必须具有以下权限集

  • “自定义属性”组织权限（管理员）

“创建或更新组织的自定义属性”的参数

标头
accept 字符串

建议设置为application/vnd.github+json。

路径参数
org 字符串 必填

组织名称。名称不区分大小写。

主体参数
properties 对象数组 必填

要创建或更新的自定义属性数组。

property_name 字符串 必填

属性的名称

url 字符串

可用于通过 API 获取、更新或删除有关此属性信息的 URL。

source_type 字符串

属性的源类型

可以是以下之一：organization，enterprise

value_type 字符串 必填

属性值的类型

可以是以下之一：string，single_select，multi_select，true_false

required 布尔值

属性是否必填。

default_value null 或字符串或数组

属性的默认值

description 字符串或 null

属性的简短描述

allowed_values 字符串数组或 null

属性允许值的排序列表。属性最多可以有 200 个允许值。

values_editable_by 字符串或 null

谁可以编辑属性的值

可以是以下之一：org_actors，org_and_repo_actors，null

“创建或更新组织的自定义属性”的 HTTP 响应状态代码

状态代码描述
200

OK

403

禁止

404

资源未找到

“创建或更新组织的自定义属性”的代码示例

请求示例

patch/orgs/{org}/properties/schema
curl -L \ -X PATCH \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/orgs/ORG/properties/schema \ -d '{"properties":[{"property_name":"environment","value_type":"single_select","required":true,"default_value":"production","description":"生产或开发环境","allowed_values":["production","development"],"values_editable_by":"org_actors"},{"property_name":"service","value_type":"string"},{"property_name":"team","value_type":"string","description":"拥有代码仓库的团队"}]}'

响应

状态：200
[ { "property_name": "environment", "url": "https://api.github.com/orgs/github/properties/schema/environment", "source_type": "organization", "value_type": "single_select", "required": true, "default_value": "production", "description": "生产或开发环境", "allowed_values": [ "production", "development" ], "values_editable_by": "org_actors" }, { "property_name": "service", "url": "https://api.github.com/orgs/github/properties/schema/service", "source_type": "organization", "value_type": "string" }, { "property_name": "team", "url": "https://api.github.com/orgs/github/properties/schema/team", "source_type": "organization", "value_type": "string", "description": "拥有代码仓库的团队" } ]

获取组织的自定义属性

获取为组织定义的自定义属性。组织成员可以读取这些属性。

“获取组织的自定义属性”的细粒度访问令牌

此端点可与以下细粒度令牌类型配合使用:

细粒度令牌必须具有以下权限集

  • “自定义属性”组织权限（读取）

“获取组织的自定义属性”的参数

标头
accept 字符串

建议设置为application/vnd.github+json。

路径参数
org 字符串 必填

组织名称。名称不区分大小写。

custom_property_name 字符串 必填

自定义属性名称

“获取组织的自定义属性”的 HTTP 响应状态代码

状态代码描述
200

OK

403

禁止

404

资源未找到

“获取组织的自定义属性”的代码示例

请求示例

get/orgs/{org}/properties/schema/{custom_property_name}
curl -L \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/orgs/ORG/properties/schema/CUSTOM_PROPERTY_NAME

响应

状态：200
{"property_name": "environment", "url": "https://api.github.com/orgs/github/properties/schema/environment", "source_type": "organization", "value_type": "single_select", "required": true, "default_value": "production", "description": "生产或开发环境", "allowed_values": ["production", "development"]}

创建或更新组织的自定义属性

创建新的或更新为组织定义的现有自定义属性。

要使用此端点，经过身份验证的用户必须是以下用户之一：

  • 组织管理员。
  • 拥有组织中custom_properties_org_definitions_manager细粒度权限的用户或团队中的用户。

“创建或更新组织的自定义属性”所需的细粒度访问令牌

此端点可与以下细粒度令牌类型配合使用:

细粒度令牌必须具有以下权限集

  • “自定义属性”组织权限（管理员）

“创建或更新组织的自定义属性”的参数

标头
accept 字符串

建议设置为application/vnd.github+json。

路径参数
org 字符串 必填

组织名称。名称不区分大小写。

custom_property_name 字符串 必填

自定义属性名称

主体参数
value_type 字符串 必填

属性值的类型

可以是以下之一：string，single_select，multi_select，true_false

required 布尔值

属性是否必填。

default_value null 或字符串或数组

属性的默认值

description 字符串或 null

属性的简短描述

allowed_values 字符串数组或 null

属性允许值的排序列表。属性最多可以有 200 个允许值。

“创建或更新组织的自定义属性”的HTTP响应状态码

状态代码描述
200

OK

403

禁止

404

资源未找到

“创建或更新组织的自定义属性”的代码示例

请求示例

put/orgs/{org}/properties/schema/{custom_property_name}
curl -L \ -X PUT \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/orgs/ORG/properties/schema/CUSTOM_PROPERTY_NAME \ -d '{"value_type":"single_select","required":true,"default_value":"production","description":"生产或开发环境","allowed_values":["production","development"]}'

响应

状态：200
{"property_name": "environment", "url": "https://api.github.com/orgs/github/properties/schema/environment", "source_type": "organization", "value_type": "single_select", "required": true, "default_value": "production", "description": "生产或开发环境", "allowed_values": ["production", "development"]}

删除组织的自定义属性

删除为组织定义的自定义属性。

要使用此端点，经过身份验证的用户必须是以下用户之一：

  • 组织管理员。
  • 拥有组织中custom_properties_org_definitions_manager细粒度权限的用户或团队中的用户。

“删除组织的自定义属性”所需的细粒度访问令牌

此端点可与以下细粒度令牌类型配合使用:

细粒度令牌必须具有以下权限集

  • “自定义属性”组织权限（管理员）

“删除组织的自定义属性”的参数

标头
accept 字符串

建议设置为application/vnd.github+json。

路径参数
org 字符串 必填

组织名称。名称不区分大小写。

custom_property_name 字符串 必填

自定义属性名称

“删除组织的自定义属性”的HTTP响应状态码

状态代码描述
204

返回一个没有内容的头部。

403

禁止

404

资源未找到

“删除组织的自定义属性”的代码示例

请求示例

delete/orgs/{org}/properties/schema/{custom_property_name}
curl -L \ -X DELETE \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/orgs/ORG/properties/schema/CUSTOM_PROPERTY_NAME

返回一个没有内容的头部。

状态：204

列出组织仓库的自定义属性值

列出所有自定义属性值的组织仓库。组织成员可以读取这些属性。

“列出组织仓库的自定义属性值”所需的细粒度访问令牌

此端点可与以下细粒度令牌类型配合使用:

细粒度令牌必须具有以下权限集

  • “自定义属性”组织权限（读取）

“列出组织仓库的自定义属性值”的参数

标头
accept 字符串

建议设置为application/vnd.github+json。

路径参数
org 字符串 必填

组织名称。名称不区分大小写。

查询参数
per_page 整数

每页结果数（最大100）。更多信息，请参见“REST API中的分页使用”。

默认值：30

page 整数

要获取的结果页数。更多信息，请参见“REST API中的分页使用”。

默认值：1

repository_query 字符串

使用包含一个或多个搜索关键字和限定符的查询查找组织中的仓库。限定符允许您将搜索限制在GitHub的特定区域。REST API支持与GitHub Web界面相同的限定符。要了解查询格式的更多信息，请参见构建搜索查询。有关限定符的详细列表，请参见“搜索仓库”。

“列出组织仓库的自定义属性值”的HTTP响应状态码

状态代码描述
200

OK

403

禁止

404

资源未找到

“列出组织仓库的自定义属性值”的代码示例

请求示例

get/orgs/{org}/properties/values
curl -L \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/orgs/ORG/properties/values

响应

状态：200
[ { "repository_id": 1296269, "repository_name": "Hello-World", "repository_full_name": "octocat/Hello-World", "properties": [ { "property_name": "environment", "value": "production" }, { "property_name": "service", "value": "web" }, { "property_name": "team", "value": "octocat" } ] } ]

创建或更新组织仓库的自定义属性值

批量创建新的或更新属于组织的仓库的现有自定义属性值。每个目标仓库的自定义属性值都将更新为与请求中提供的值匹配。

单个请求最多可以更新30个仓库。

对自定义属性使用null值将删除或“取消设置”仓库中的属性值。

要使用此端点，经过身份验证的用户必须是以下用户之一：

  • 组织管理员。
  • 具有组织中custom_properties_org_values_editor细粒度权限的用户或团队中的用户。

“创建或更新组织仓库的自定义属性值”所需的细粒度访问令牌

此端点可与以下细粒度令牌类型配合使用:

细粒度令牌必须具有以下权限集

  • “自定义属性”组织权限（写入）

“创建或更新组织仓库的自定义属性值”的参数

标头
accept 字符串

建议设置为application/vnd.github+json。

路径参数
org 字符串 必填

组织名称。名称不区分大小写。

主体参数
repository_names 字符串数组 必需

将应用自定义属性值的仓库名称。

properties 对象数组 必填

要应用于仓库的自定义属性名称和关联值的列表。

property_name 字符串 必填

属性的名称

value null或字符串或数组 必需

分配给属性的值

“创建或更新组织仓库的自定义属性值”的HTTP响应状态码

状态代码描述
204

成功创建或更新自定义属性值时，无内容

403

禁止

404

资源未找到

422

验证失败或端点已被滥用。

“创建或更新组织仓库的自定义属性值”的代码示例

请求示例

patch/orgs/{org}/properties/values
curl -L \ -X PATCH \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/orgs/ORG/properties/values \ -d '{"repository_names":["Hello-World","octo-repo"],"properties":[{"property_name":"environment","value":"production"},{"property_name":"service","value":"web"},{"property_name":"team","value":"octocat"}]}'

成功创建或更新自定义属性值时，无内容

状态：204