Phabricator Conduit API介紹
在Phabricator頁面，可以完成建立和編輯Project、Task等操作。但是如果想實現外部系統可以自主操作Phabricator，那麼就需要呼叫Phabricator Conduit API，實現相應的建立和編輯Project、Task等操作。
建立Token
呼叫Phabricator Conduit API，需要token認證。點選右上角的使用者頭像，Settings - Conduit API Tokens - Generate Token，完成後會顯示token資訊。
Conduit API介面
進入Phabricator首頁，選擇More Applications，找到Developer Tools部分， 點選Conduit，在Modern Methods 標籤下，可以看到所有Conduit API介面方法。
點選進入任意一個API介面，發現關於介面的說明分為三個部分：一是介面的概要介紹和相關引數的說明；二是介面的呼叫方法，通過填寫相應的引數，並執行Call Methos，會真實呼叫該API介面，並返回API方法的執行結果；三是把API介面呼叫方法的內容轉化為CURL或PHP方式的範例。
Conduit API 範例
Phabricator中的Project包含多個Column，每個Column包含多個Task，每個Task下可以包含多條Comment。下面使用curl命令列範例介紹相關API如何使用。
Project API
- 建立
其中name是必選的，描述資訊、圖表icon、成員資訊可選。
curl http://HOSTNAME:PORT/api/project.edit \
-d api.token=api-token \
-d transactions[name][type]=name \
-d transactions[name][value]=testProject
- 修改
需要指定project的phid編輯已建立的project。
curl http://HOSTNAME:PORT/api/project.edit \
-d api.token=api-token \
-d transactions[name][type]=name \
-d transactions[name][value]=testNewProject \
-d objectIdentifier=PHID-PROJ-qbht7j3eqmmqlkj2yae6
- 查詢
可以通過queryKey過濾出結果，也可以自定義查詢限制，並對結果排序等。
curl http://HOSTNAME:PORT/api/project.search \
-d api.token=api-token \
-d queryKey=all
Column API
官網上只找到Column的查詢API，未找到建立和修改的API，因此需要在頁面建立和修改Column。
- 查詢
可以通過queryKey過濾出結果，也可以自定義查詢限制，並對結果排序等。通過指定project phid可以查詢該project的column。
curl http://HOSTNAME:PORT/api/project.column.search \
-d api.token=api-token \
-d constraints[projects][0]=PHID-PROJ-qbht7j3eqmmqlkj2yae6
執行結果：
{
"data": [
{
"id": 15,
"type": "PCOL",
"phid": "PHID-PCOL-qsyhs6ubci6cgyd7f6ne",
"fields": {
"name": "testColumn",
"proxyPHID": null,
"project": {
"id": 5,
"phid": "PHID-PROJ-qbht7j3eqmmqlkj2yae6",
"name": "testNewProject"
},
"dateCreated": 1657790074,
"dateModified": 1657790092,
"policy": {
"view": "users",
"edit": "users"
}
}
}
]
...
}
Task API
- 建立
支援多種型別的操作，包括：新增父task，新增子task、新增comment等。需要指定project和column的phid，從而確定在哪個project的哪個column下建立task。
curl http://HOSTNAME:PORT/api/maniphest.edit \
-d api.token=api-token \
-d transactions[title][type]=title \
-d transactions[title][value]=title-test \
-d transactions[description][type]=description \
-d transactions[description][value]=description-test \
-d transactions[column][type]=column \
-d transactions[column][value][0]=PHID-PCOL-5bsishzsn6bj4egkbkup \
-d transactions[projects.set][type]=projects.set \
-d transactions[projects.set][value][0]=PHID-PROJ-zrz7gbb3lxqji3fnqv6k
執行結果：
{
"result":{
"object":{
"id":293,
"phid":"PHID-TASK-upumxxdvq7ah7ery2xab"
},
"transactions":[
{
"phid":"PHID-XACT-TASK-g5hfx6ogfn3xj3x"
}，
...
]
},
"error_code":null,
"error_info":null
}
- 修改
通過指定task phid來確定修改哪個task。
curl http://HOSTNAME:PORT/api/maniphest.edit \
-d api.token=api-token \
-d transactions[title][type]=title \
-d transactions[title][value]=new-title-test \
-d transactions[description][type]=description \
-d transactions[description][value]=new-description-test \
-d objectIdentifier=PHID-TASK-upumxxdvq7ah7ery2xab
通過頁面檢視修改後的task。
- 查詢
可以通過queryKey過濾出結果，也可以自定義查詢限制，並對結果排序等。下面範例為查詢某個column下的task。
curl http://HOSTNAME:PORT/api/maniphest.search \
-d api.token=api-token \
-d queryKey=all \
-d constraints[statuses][0]=open \
-d constraints[statuses][1]=closed \
-d constraints[columnPHIDs][0]=PHID-PCOL-qsyhs6ubci6cgyd7f6ne
執行結果：
{
"result":{
"data":[
{
"id":293,
"type":"TASK",
"phid":"PHID-TASK-upumxxdvq7ah7ery2xab",
"fields":{
"name":"new-title-test",
"description":{
"raw":"new-description-test"
},
"authorPHID":"PHID-USER-6sfzp4rmpmuqbt5y5mtp",
"ownerPHID":null,
"status":{
"value":"open",
"name":"Open",
"color":null
},
"priority":{
"value":90,
"name":"Needs Triage",
"color":"violet"
}
...
}
}
]
},
"error_code":null,
"error_info":null
}
Comment API
官網上只找到Comment的建立API，未找到查詢和修改的API，因此可以在頁面查詢和修改Comment。
- 建立
comment API方法和task一樣，均為maniphest.edit。需要指定task的phid，從而確定為哪個task新增comment。
curl http://HOSTNAME:PORT/api/maniphest.edit \
-d api.token=api-token \
-d transactions[comment][type]=comment \
-d transactions[comment][value]=comment-test \
-d objectIdentifier=PHID-TASK-upumxxdvq7ah7ery2xab
執行結果：
{
"result":{
"object":{
"id":293,
"phid":"PHID-TASK-upumxxdvq7ah7ery2xab"
},
"transactions":[
{
"phid":"PHID-XACT-TASK-uqhri2bc6e3356n"
}
]
},
"error_code":null,
"error_info":null
}
總結
本文主要介紹瞭如何通過Phabricator Conduit API建立、修改、查詢Project、Column、Task、Comment。其它系統通過呼叫Conduit API，可以非常方便地實現自動化操作Phabricator。