本文演示如何使用 GraphQL API 来管理项目。 有关如何在 GitHub Actions 工作流程中使用 API 的详细信息,请参阅“自动化项目(测试版)”。 有关可用数据类型的完整列表,请参阅“参考”。
注意: 项目(测试版)目前处于公开测试阶段,可能会有所变化。
身份验证
在所有下面的 cURL 示例中, 将 TOKENN
替换为具有 read:org
范围(对于查询)或 write:org
范围(对于查询和突变)的令牌。 令牌可以是用户的个人访问令牌,也可以是 GitHub 应用程序 的安装访问令牌。 有关创建个人访问令牌的更多信息,请参阅“创建个人访问令牌”。 有关为 GitHub 应用程序 创建安装访问令牌的详细信息,请参阅“使用 GitHub 应用程序 进行身份验证”。
要了解有关 GitHub CLI 的更多信息,请参阅“关于 GitHub CLI”。
在运行 GitHub CLI 命令之前,必须通过运行 gh auth login --scopes "write:org"
进行身份验证。 如果只需要读取项目,但不需要编辑项目,则可以省略 --scopes
参数。 有关命令行身份验证的更多信息,请参阅 "gh auth login"。
使用变量
在以下所有示例中,您可以使用变量来简化脚本。 使用 -F
传递是数字、布尔值或空值的变量。 对其他变量使用 -f
。 例如,
my_org="octo-org"
my_num=5
gh api graphql -f query='
query($organization: String! $number: Int!){
organization(login: $organization){
projectNext(number: $number) {
id
}
}
}' -f organization=$my_org -F number=$my_num
更多信息请参阅“使用 GraphQL 创建调用”。
查找项目信息
使用查询获取项目数据。 更多信息请参阅“关于查询。”
查找组织项目的节点 ID
要通过 API 更新您的项目,您需要知道项目的节点 ID。
如果您知道组织名称和项目编号,则可以找到组织项目的节点 ID。 将 ORGANIZATION
替换为您的组织名称。 例如 octo-org
。 将 NUMBER
替换为项目编号。 要查找项目编号,请查看项目 URL。 例如,https://github.com/orgs/octo-org/projects/5
有一个编号为 5 的项目。
curl --request POST \
--url https://api.github.com/graphql \
--header 'Authorization: token TOKEN' \
--data '{"query":"query{organization(login: \"ORGANIZATION\") {projectNext(number: NUMBER){id}}}"}'
gh api graphql -f query='
query{
organization(login: "ORGANIZATION"){
projectNext(number: NUMBER) {
id
}
}
}'
您也可以在组织中找到所有项目的节点 ID。 下面的示例将返回组织中前 20 个项目的节点 ID 和标题。 将 ORGANIZATION
替换为您的组织名称。 例如 octo-org
。
curl --request POST \
--url https://api.github.com/graphql \
--header 'Authorization: token TOKEN' \
--data '{"query":"{organization(login: \"ORGANIZATION\") {projectsNext(first: 20) {nodes {id title}}}}"}'
gh api graphql -f query='
query{
organization(login: "ORGANIZATION") {
projectsNext(first: 20) {
nodes {
id
title
}
}
}
}'
查找用户项目的节点 ID
要通过 API 更新您的项目,您需要知道项目的节点 ID。
如果您知道项目编号,则可以找到用户项目的节点 ID。 将 USER
替换为您的用户名。 例如 octocat
。 将 NUMBER
替换为项目编号。 要查找项目编号,请查看项目 URL。 例如,https://github.com/users/octocat/projects/5
有一个编号为 5 的项目。
curl --request POST \
--url https://api.github.com/graphql \
--header 'Authorization: token TOKEN' \
--data '{"query":"query{user(login: \"USER\") {projectNext(number: NUMBER){id}}}"}'
gh api graphql -f query='
query{
user(login: "USER"){
projectNext(number: NUMBER) {
id
}
}
}'
您还可以找到所有项目的节点 ID。 以下示例将返回前 20 个项目的节点 ID 和标题。 将 USER
替换为您的用户名。 例如 octocat
。
curl --request POST \
--url https://api.github.com/graphql \
--header 'Authorization: token TOKEN' \
--data '{"query":"{user(login: \"USER\") {projectsNext(first: 20) {nodes {id title}}}}"}'
gh api graphql -f query='
query{
user(login: "USER") {
projectsNext(first: 20) {
nodes {
id
title
}
}
}
}'
查找字段的节点 ID
要更新字段的值,您需要知道字段的节点 ID。 此外,您还需要知道单个选择字段的选项 ID 和迭代字段的迭代 ID。
下面的示例将返回项目中前 20 个字段的 ID、名称和设置。 将 PROJECT_ID
替换为项目的节点 ID。
curl --request POST \
--url https://api.github.com/graphql \
--header 'Authorization: token TOKEN' \
--data '{"query":"query{node(id: \"PROJECT_ID\") {... on ProjectNext {fields(first: 20) {nodes {id name settings}}}}}"}'
gh api graphql -f query='
query{
node(id: "PROJECT_ID") {
... on ProjectNext {
fields(first: 20) {
nodes {
id
name
settings
}
}
}
}
}'
响应将类似于以下示例:
{
"data": {
"node": {
"fields": {
"nodes": [
{
"id": "MDE2OlByb2plY3ROZXh0RmllbGQxMzE1OQ==",
"name": "Title",
"settings": "null"
},
{
"id": "MDE2OlByb2plY3ROZXh0RmllbGQxMzE2MA==",
"name": "Assignees",
"settings": "null"
},
{
"id": "MDE2OlByb2plY3ROZXh0RmllbGQxMzE2MQ==",
"name": "Status",
"settings": "{\"options\":[{\"id\":\"f75ad846\",\"name\":\"Todo\",\"name_html\":\"Todo\"},{\"id\":\"47fc9ee4\",\"name\":\"In Progress\",\"name_html\":\"In Progress\"},{\"id\":\"98236657\",\"name\":\"Done\",\"name_html\":\"Done\"}]}"
},
{
"id": "MDE2OlByb2plY3ROZXh0RmllbGQ3NTEwNw==",
"name": "Iteration",
"settings": "{\"configuration\":{\"duration\":7,\"start_day\":5,\"iterations\":[{\"id\":\"c4d8e84d\",\"title\":\"Iteration 2\",\"duration\":7,\"start_date\":\"2021-10-08\",\"title_html\":\"Iteration 2\"},{\"id\":\"fafa9c9f\",\"title\":\"Iteration 3\",\"duration\":7,\"start_date\":\"2021-10-15\",\"title_html\":\"Iteration 3\"}],\"completed_iterations\":[{\"id\":\"fa62c118\",\"title\":\"Iteration 1\",\"duration\":7,\"start_date\":\"2021-10-01\",\"title_html\":\"Iteration 1\"}]}}"
}
]
}
}
}
}
每个字段都有 ID。 此外,单个选择字段和迭代字段有设置
值。 在单选设置中,您可以找到单选的每个选项的 ID。 在迭代设置中,您可以找到迭代的持续时间、迭代的开始日期(从星期一的 1 到星期日的 7)、未完成迭代的列表以及已完成迭代的列表。 对于迭代列表中的每个迭代,您可以找到迭代的 ID、标题、持续时间和开始日期。
查找项目中各项的信息
您可以查询 API 来查找项目中各项的信息。
注意:API 不会返回有关草稿议题的信息。
下面的示例将返回项目中前 20 个字段的名称和 ID。 对于每个项目,它还将返回项目前 8 个字段的值和名称。 如果项目是议题或拉取请求,它将返回前 10 个受理人的登录名。 将 PROJECT_ID
替换为项目的节点 ID。
curl --request POST \
--url https://api.github.com/graphql \
--header 'Authorization: token TOKEN' \
--data '{"query":"query{node(id: \"PROJECT_ID\") {... on ProjectNext {items(first: 20) {nodes{title id fieldValues(first: 8) {nodes{value projectField{name}}} content{...on Issue {assignees(first: 10) {nodes{login}}} ...on PullRequest {assignees(first: 10) {nodes{login}}}}}}}}}"}'
gh api graphql -f query='
query{
node(id: "PROJECT_ID") {
... on ProjectNext {
items(first: 20) {
nodes{
title
id
fieldValues(first: 8) {
nodes{
value
projectField{
name
}
}
}
content{
...on Issue {
assignees(first: 10) {
nodes{
login
}
}
}
...on PullRequest {
assignees(first: 10) {
nodes{
login
}
}
}
}
}
}
}
}
}'
项目可能包含用户无权查看的项。 在这种情况下,响应将包括已编辑的项。
{
"node": {
"title": "You can't see this item",
...
}
}
更新项目
使用突变来更新项目。 更多信息请参阅“关于突变。”
注意: 您不能在同一调用中添加和更新项。 您必须使用 addProjectNextitem
来添加项,然后使用 updateProjectNextItemfield
来更新项。
添加项到项目
以下示例将向您的项目添加议题或拉取请求。 将 PROJECT_ID
替换为项目的节点 ID。 将 CONT_ID
替换为议题的节点 ID 或您想要添加的拉取请求。
curl --request POST \
--url https://api.github.com/graphql \
--header 'Authorization: token TOKEN' \
--data '{"query":"mutation {addProjectNextItem(input: {projectId: \"PROJECT_ID\" contentId: \"CONTENT_ID\"}) {projectNextItem {id}}}"}'
gh api graphql -f query='
mutation {
addProjectNextItem(input: {projectId: "PROJECT_ID" contentId: "CONTENT_ID"}) {
projectNextItem {
id
}
}
}'
响应将包含新建项目的节点 ID。
{
"data": {
"addProjectNextItem": {
"projectNextItem": {
"id": "MDE1OlByb2plY3ROZXh0SXRlbTM0MjEz"
}
}
}
}
如果您尝试添加已经存在的项,则返回现有项 ID。
更新项目的设置
以下示例将更新项目的设置。 将 PROJECT_ID
替换为项目的节点 ID。 将 public
设置为 true
,以便在 GitHub 上公开您的项目。 修改 description
以对项目的 README 进行更改。
curl --request POST \
--url https://api.github.com/graphql \
--header 'Authorization: token TOKEN' \
--data '{"query":"mutation { updateProjectNext(input: { projectId: \"PROJECT_ID\", title: \"Project title\", public: false, description: \"# Project README\n\nA long description\", shortDescription: \"A short description\"}) { projectNext { id, title, description, shortDescription }}}"}'
gh api graphql -f query='
mutation {
updateProjectNext(
input: {
projectId: "PROJECT_ID",
title: "Project title",
public: false,
description: "# Project README\n\nA long description",
shortDescription: "A short description"
}
) {
projectNext {
id
title
description
shortDescription
}
}
}'
更新自定义文本、数字或日期字段
下面的示例将更新项目的日期字段值。 将 PROJECT_ID
替换为项目的节点 ID。 将 ITEM_ID
替换为您想要更新的项的节点 ID。 将 FIELD_ID
替换为您想要更新的字段的 ID。
curl --request POST \
--url https://api.github.com/graphql \
--header 'Authorization: token TOKEN' \
--data '{"query":"mutation {updateProjectNextItemField(input: {projectId: \"PROJECT_ID\" itemId: \"ITEM_ID\" fieldId: \"FIELD_ID\" value: \"2021-5-11\"}) {projectNextItem {id}}}"}'
gh api graphql -f query='
mutation {
updateProjectNextItemField(
input: {
projectId: "PROJECT_ID"
itemId: "ITEM_ID"
fieldId: "FIELD_ID"
value: "2021-5-11"
}
) {
projectNextItem {
id
}
}
}'
注意: 您不能使用 updateProjectNextItemField
更改 Assignees
、Labels
、Milestone
或 Repository
,因为这些字段是拉取请求和议题,而不是项目项的属性。 相反,您必须使用 addAssigneesToAssignable、removeAssigneesFromAssignable、addLabelsToLabelable、removeLabelsFromLabelable、updateIssue、updatePullRequest 或 transferIssue 突变。
更新单选字段
下面的示例将更新项的单选字段值。
PROJECT_ID
- 用项目节点 ID 替换。ITEM_ID
- 替换为您想要更新的项的节点 ID。FIELD_ID
- 替换为您想要更新的单选字段的 ID。OPTION_ID
- 替换为所需单选选项的 ID。
curl --request POST \
--url https://api.github.com/graphql \
--header 'Authorization: token TOKEN' \
--data '{"query":"mutation {updateProjectNextItemField(input: {projectId: \"PROJECT_ID\" itemId: \"ITEM_ID\" fieldId: \"FIELD_ID\" value: \"OPTION_ID\"}) {projectNextItem {id}}}"}'
gh api graphql -f query='
mutation {
updateProjectNextItemField(
input: {
projectId: "PROJECT_ID"
itemId: "ITEM_ID"
fieldId: "FIELD_ID"
value: "OPTION_ID"
}
) {
projectNextItem {
id
}
}
}'
更新迭代字段
下面的示例将更新项的迭代字段值。
PROJECT_ID
- 用项目节点 ID 替换。ITEM_ID
- 替换为您想要更新的项的节点 ID。FIELD_ID
- 替换为您想要更新的迭代字段的 ID。ITERATION_ID
- 替换为所需迭代的 ID。 这可以是活动迭代(来自iterations
数组)或已完成迭代(来自completed_iterations
数组)。
curl --request POST \
--url https://api.github.com/graphql \
--header 'Authorization: token TOKEN' \
--data '{"query":"mutation {updateProjectNextItemField(input: {projectId: \"PROJECT_ID\" itemId: \"ITEM_ID\" fieldId: \"FIELD_ID\" value: \"ITERATION_ID\"}) {projectNextItem {id}}}"}'
gh api graphql -f query='
mutation {
updateProjectNextItemField(
input: {
projectId: "PROJECT_ID"
itemId: "ITEM_ID"
fieldId: "FIELD_ID"
value: "ITERATION_ID"
}
) {
projectNextItem {
id
}
}
}'
从项目中删除项
下面的示例将从项目中删除一个项。 将 PROJECT_ID
替换为项目的节点 ID。 将 ITEM_ID
替换为您想要删除的项的节点 ID。
curl --request POST \
--url https://api.github.com/graphql \
--header 'Authorization: token TOKEN' \
--data '{"query":"mutation {deleteProjectNextItem(input: {projectId: \"PROJECT_ID\" itemId: \"ITEM_ID\"}) {deletedItemId}}"}'
gh api graphql -f query='
mutation {
deleteProjectNextItem(
input: {
projectId: "PROJECT_ID"
itemId: "ITEM_ID"
}
) {
deletedItemId
}
}'