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，

參考資料

1. Phabricator Conduit API官網檔案

2. Phabricator 的 conduit API 使用說明

標籤：其他

上一篇：軟體危機與軟體程序模型

下一篇：Phabricator Conduit API介紹