Adobe Workfront Planning API基本需知

Adobe Workfront Planning API的目標是引入透過HTTP運作的RESTful架構，簡化與Planning的整合建置。 本檔案假設您熟悉REST和JSON回應。

如需完整的端點參考、要求/回應結構描述和版本特定詳細資訊，請參閱Workfront Planning API開發人員檔案。

Authentication

Workfront Planning API使用OAuth 2.0進行驗證。 認證是透過Adobe Developer Console設定的。

根據您的整合型別，我們支援下列兩個流程：

若要開始使用，請在Adobe Developer Console中建立專案，並新增Workfront Planning API以取得您的認證。

若要設定認證，請在Workfront中建立OAuth2應用程式。

如需詳細資訊，請參閱為Workfront整合建立OAuth2應用程式。

API版本設定

Planning API是透過URL路徑建立版本。

以下是目前支援的版本：

如需目前支援版本的詳細資訊，請參閱文章Workfront Planning API開發人員檔案。

我們建議在所有整合中明確鎖定版本：

https://{customer-domain}/maestro/api/v2/...

發行新的主要版本時，在傳達淘汰日期之前，將繼續提供舊版。

請依照Workfront發行說明操作，及時瞭解API變更。

URL結構和操作

透過傳送HTTP請求至物件的唯一URI來控制物件。 操作由HTTP方法指定。

如需完整的端點路徑和要求/回應範例，請參閱developer.adobe.com/wf-planning上的​API參考。

HTTP狀態碼

Planning API會傳回標準HTTP狀態代碼：

錯誤處理

Planning API會以一致的格式傳回錯誤。 每個錯誤回應都包含可讀取的訊息、機器可讀取的錯誤代碼以及支援升級的請求ID。

範例錯誤回應：

json
{
  "title": "Validation failed",
  "status": 400,
  "detail": "Request validation failed. See 'errors' for details.",
  "errorCode": "VALIDATION_FAILED",
  "requestId": "req-123",
  "errors": [
    { "field": "name", "message": "must not be blank" }
  ]
}

使用errorCode （非status）來驅動程式化錯誤處理。 它提供最具體的失敗分類。

篩選記錄

在記錄搜尋要求中使用filter引數，僅傳回符合特定條件的記錄。 對於POST要求，filter是要求內文中的JSON屬性。 對於GET要求，filter是包含JSON編碼篩選群組的查詢引數。 篩選器使用具有明確邏輯運運算元的型別化複合結構。

json
{
  "filter": {
    "operator": "AND",
    "conditions": [
      { "fieldId": "<fieldId>", "condition": "IS", "value": "Active" },
      { "fieldId": "<fieldId>", "condition": "CONTAINS", "value": "marketing" }
    ]
  }
}

篩選器可以使用AND / OR運運算元巢狀化以建置複合條件：

json
{
  "filter": {
    "operator": "OR",
    "conditions": [
      {
        "operator": "AND",
        "conditions": [
          { "fieldId": "<fieldId>", "condition": "BETWEEN", "value": ["2024-03-31T20:00:00.000Z", "2024-04-01T20:00:00.000Z"] },
          { "fieldId": "<fieldId>", "condition": "IS", "value": "active" }
        ]
      },
      {
        "operator": "AND",
        "conditions": [
          { "fieldId": "<fieldId>", "condition": "IS_BETWEEN", "value": ["2024-04-15T00:00:00.000Z", "2024-04-16T00:00:00.000Z"] },
          { "fieldId": "<fieldId>", "condition": "IS", "value": "planned" }
        ]
      }
    ]
  }
}

欄位型別和搜尋修飾詞

您可以使用包含欄位的修飾詞和篩選器來控制要在結果中傳回哪些資料。

如需範例，請參閱Workfront Planning API開發人員檔案。

使用搜尋修飾元

Workfront Planning支援下列搜尋修飾元：

依欄位型別支援的篩選條件

依人員欄位篩選

人員欄位篩選器(user、created-by、updated-by、approved-by)同時接受Adobe IMS使用者ID和Workfront使用者ID。 純字串值會解譯為Adobe IMS使用者ID。

若要設定識別碼型別以檢查Workfront使用者識別碼，您必須明確傳遞id和idType引數。 idType支援的值在Workfront使用者ID為"WF"，在Adobe IMS使用者ID為"IMS"。

{
  "filter": {
   "operator": "AND",
    "conditions": [
      {
        "fieldId": "<userFieldId>",
        "condition": "HAS_ANY_OF",
        "value": [
          { "id": "63e3b13000078c1795146248182d15dc", "idType": "WF" }
        ]
      }
    ]
  }
}

依外部ID篩選外部參考欄位

外部參考欄位會將記錄連結到其他Adobe系統（例如Workfront專案或AEM Assets）中的物件。 在內部，Planning會將Planning記錄ID指定給這些物件。 若要直接依原始物件識別碼篩選這些欄位，請新增"matchExternalId": true至篩選條件。

此旗標僅適用於referenceOptions.isExternal為true的參考欄位；非外部參考欄位會忽略此旗標。 如果無法解析單一字串值，則要求會失敗，並產生400 Bad Request。 如果提供清單值，未解析的專案會透過未變更且完全不相符。

{
  "filter": {
    "operator": "AND",
    "conditions": [
      {
        "fieldId": "<externalReferenceFieldId>",
        "condition": "IS_ANY_OF",
        "value": [
          "5f6a4f6e00000123456789abcdef0123",
          "/content/dam/wknd/en/adventures/bali-surf-camp"
        ],
        "matchExternalId": true
      }
    ]
  }
}

外部連線欄位

Planning記錄型別可以託管外部參考欄位，這些欄位將記錄連結到其他Adobe系統中的物件，而不是其他Planning記錄型別。

若要透過API建立外部參考欄位，請將新REFERENCE欄位上的referenceOptions.recordTypeId設定為所需外部記錄型別的識別碼。 伺服器會自動從目標籤錄型別衍生referenceOptions.isExternal=true和連線中繼資料(connectionName, objectName)。

支援的外部物件型別包括Workfront物件（專案、工作、方案、產品組合、公司、群組、團隊、使用者）和AEM Assets （資產、內容片段）。

排序

在您的要求中加入sort陣列，依任何欄位排序結果：

json
{
  "sort": [
    { "fieldId": "F6527ecb25df57c441d92b9fc", "direction": "asc" },
    { "fieldId": "F658afcbd4a0273c67c346fd5", "direction": "desc" }
  ]
}

系統會依順序評估多個排序欄位。 編頁時一律套用排序，以確保跨頁面順序一致。

若要將結果分組，請在排序時加入群組陣列：

{
  "sort": [{ "fieldId": "F001", "direction": "asc" }],
  "group": [{ "fieldId": "F002", "direction": "asc" }]
}

欄位投影

若要限制回應中傳回的欄位，請使用逗號分隔清單中的fieldIds或fieldAliases查詢引數。 這樣會減少回應裝載大小，建議用於高容量或對延遲敏感的整合。

分頁

Planning API支援分頁回應，以管理大型資料集。

例如，使用以下請求，從記錄搜尋中擷取500筆記錄的第二頁：

POST /v2/record-types/{recordTypeId}/records/search?page=1&size=500
{
  "sort": [{ "fieldId": "F6527ecb25df57c441d92b9fc", "direction": "asc" }],
  "filter": { "operator": "AND", "conditions": [
    { "fieldId": "<fieldId>", "condition": "IS", "value": "active" }
  ] }
}

所有分頁回應都包含一個結構化信封，指示是否有更多可用結果。 編頁時一律套用排序，以確保跨頁面順序一致。

大量作業

Planning API支援大量建立、更新、修補及刪除單一請求中的記錄。 如需端點路徑、要求格式和每個作業的記錄限制，請參閱developer.adobe.com/wf-planning的​API參考。

權限

實體的許可權透過專用許可權API進行管理，與資源端點本身分開。 這可讓您讀取目前許可權、管理共用清單，以及獨立於資料作業處理存取請求。 如需詳細資訊，請參閱文章Workfront Planning API中的「API參考」一節。

搭配Workfront自訂表單使用Planning API

您可以從Workfront自訂表單中的外部查閱欄位呼叫Planning API，以直接在Workfront物件中呈現Planning資料。 如需詳細資訊，請參閱自訂表單🔗中的外部查閱欄位範例。

相關資源

如需更多API相關檔案，另請參閱下列文章：