執行 REST 指令

許多不同的程式可以執行 REST 指令。若要執行該指令，您可以針對 REST 資源呼叫方法並以 JSON 格式傳遞參數或要求。

註：使用 REST 指令需要使用 Web 介面所需的相同許可權。如需許可權的相關資訊，請參閱角色及許可權。

範例：使用 curl 執行簡式 REST 指令

Linux 程式 curl 是執行 REST 指令的簡式方法。若要執行 REST 指令，請將其中一個 REST 資源的 URL 放置在一起，指定要使用的方法，然後新增任何參數。例如，下列 curl 指令會擷取所有提案的清單。該指令呼叫 initiatives 資源的 GET 方法：

curl -k -u jsmith:passw0rd 
  https://hostname:port/initiatives/ 
  -X GET -H "Accept: application/json"

註：您必須在單行中輸入這個指令。在這裡分成多行以方便您看清楚。

註：此範例使用 -k 參數，在不檢查 SSL 憑證有效性的情況下連接伺服器。若要設定鑑別，請參閱進行鑑別以執行 REST 指令。

這個範例利用使用者名稱 jsmith 及密碼 passw0rd。在大多數情況下，請對要使用的 REST 指令建立專用使用者帳戶，並授與該帳戶適當的權限。

對於 hostname 和 port，使用伺服器的主機名稱和埠。例如，如果主機名稱是 ucrelease.example.org，埠是預設值 8080，則 curl 指令可能類似於下面的範例：

curl -k -u jsmith:passw0rd
  https://ucrelease.example.org:8080/initiatives/ 
  -X GET -H "Accept: application/json"

此指令的回應是伺服器上所有提案的 JSONArray 清單，如下面的範例中所示：

[
  {
    "description": "My init",
    "name": "InitA",
    "id": "c1e7dd8f-b1fc-41ea-8d73-a120da8d9999",
    "version": 0,
    "dateCreated": 1413559219120
  },
  {
    "description": "Another init",
    "name": "InitB",
    "id": "30873ef0-c9f3-4af3-a4dd-eedda71c9bbf",
    "version": 0,
    "dateCreated": 1413559224354
  }
]

將參數傳遞給 REST 指令

許多 REST 指令具有一個以上的參數。一些參數新增至 URL 的基本部分，另一些參數新增至 URL 的末尾。

例如，/initiatives/{id} 資源的 GET 方法傳回提案的相關資訊。此方法在其 URL 的基本部分中有一個參數。參數 {id} 是指提案的 ID。要使用此資源的 GET 方法，您必須取代 URL 中提案的 ID。例如，如果提案 ID 是 c1e7dd8f-b1fc-41ea-8d73-a120da8d9999，則您必須執行下列指令：

curl -k -u jsmith:passw0rd
  https://ucrelease.example.org:8080/initiatives/
  c1e7dd8f-b1fc-41ea-8d73-a120da8d9999" 
  -X GET -H "Accept: application/json"

部分方法接受 URL 末尾的參數。例如，initiatives 資源的 GET 方法接受 format 參數。此參數指定所傳回 JSON 的格式。例如，若要顯示有關伺服器上提案的其他詳細資料，請將值 detail 傳遞給 format 參數，如下面的範例中所示：

curl -k -u jsmith:passw0rd 
  https://ucrelease.example.org:8080/initiatives/
  ?format=detail 
  -X GET -H "Accept: application/json"

與省略該參數相比，產生的 JSON 程式碼的詳細程度較高。在此情況下，它包括與每一個提案相關聯的應用程式、發行和變更。如需 format 參數的有效值，請參閱該方法的參考頁面。

註：所有參數值都必須採用 URL 編碼。例如，如果參數包括空格，則必須用 URL 編碼值 %20 取代。

將 JSON 字串傳遞給指令

對於較複雜的指令，您必須傳送 JSON 字串或檔案，而不傳送參數，或者除了參數之外，還傳送 JSON 字串或檔案。

例如，initiatives 資源的 POST 方法可建立提案。要使用此指令，您必須傳遞 JSON 字串以指定新提案的名稱和說明。此指令的 JSON 字串必須遵循以下範本：

{
  "name": "Initiative name",
  "description": "Initiative description"
}

此範本列在指令的參考資訊中。請參閱REST 指令。

若要將此 JSON 字串傳遞至 initiatives 資源，您可以將字串儲存到檔案中或將它包括在指令中。例如，如果您將該字串儲存到名為 newInitiative.json 的檔案中，則指令類似於下面的範例：

curl -k -u jsmith:passw0rd 
  https://ucrelease.example.org:8080/initiatives/
  -d @newInitiative.json 
  -X POST -H "Content-Type: application/json"

您還可以將字串直接傳遞給指令，如下面的範例中所示：

curl -k -u jsmith:passw0rd 
  https://ucrelease.example.org:8080/initiatives/
  -d '{"name":"Initiative B","description":"Description of Initiative B"}' 
  -X POST -H "Content-Type: application/json"

註：您傳遞給指令的字串必須是有效的 JSON 字串。

回應

指令成功之後，大部分指令都會傳回簡式字串值或 JSON 字串。

除了指令的結果外，這些指令還傳回標準 HTTP 狀態碼。下列清單包括 REST 指令傳回的最常見狀態碼。

200

指令已成功。

400

您無權執行該指令。
您未指定某個必要參數。
URL 中的資源路徑不正確。

404

您嘗試擷取的物件不存在。

405

HTTP 方法名稱不正確。

415

要求標頭中的內容類型不正確。

500

伺服器遇到了錯誤。

意見