Adobe Workfront Planning API基本需知

最後更新： 2026年5月12日

主題：
Workfront Planning

建立對象：

User
Admin

IMPORTANT

本文資訊說明Adobe Workfront的額外功能Adobe Workfront Planning。

如需存取Workfront Planning的需求清單，請參閱Adobe Workfront Planning存取總覽。

如需Workfront Planning的一般資訊，請參閱開始使用Adobe Workfront Planning。

Adobe Workfront Planning API的目標是引入透過HTTP運作的REST-ful架構，簡化與Planning的整合建置。本檔案假設您熟悉REST和JSON回應，並說明Planning API所採取的方法。

熟悉Workfront Planning綱要將有助於您瞭解可用來從Workfront Planning中提取資料以進行整合的資料庫關係。

您可以從Workfront自訂表單中的外部查詢欄位呼叫Planning API。

如需外部查閱欄位的詳細資訊，請參閱自訂表單中的外部查閱欄位範例。

NOTE

使用Planning API時，所有與使用者相關的資訊將會使用Adobe Identity Management系統(IMS)使用者ID而非Workfront使用者ID傳回。

如需詳細資訊，請參閱在Adobe Admin Console中管理使用者。

Workfront Planning API版本

第1版 — 2024年7月發行

如需詳細資訊，請參閱本文章的Workfront Planning API版本1一節。

Workfront Planning API第1版

Workfront Planning API第1版已於2024年7月發行。

以下小節說明Workfront API版本1中提供的功能。

除非另有指定，否則所有未來的API版本都將包含相同的功能。

作業

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

標準HTTP方法會對應至下列作業：

GET — 依識別碼擷取物件，依查詢搜尋所有物件
貼文 — 插入新物件
PUT — 編輯現有物件
DELETE — 刪除物件

如需每個作業的詳細資訊與範例，請參閱Workfront Planning API開發人員檔案。

欄位型別和搭配使用的搜尋修飾詞

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

使用搜尋修飾元

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

修飾詞

範例

說明

可能的值

$contain

"fieldId": { "$contains": "product" }

傳回其欄位值包含篩選器的記錄

"新產品上市"

$doesNotContain

"fieldId": { "$doesNotContain": "product" }

傳回欄位值不含篩選器的記錄

"新增啟動項"

$is

"fieldId" : { "$is": "new product launch" }
"fieldId" : { "new product launch" }

傳回其欄位值完全符合篩選器的記錄

"新產品上市"

$isNot

"fieldId": { "$isNot": "product" }

傳回欄位值完全不符合篩選器的記錄

"新產品上市"

$isEmpty

"fieldId": "$isEmpty"
"fieldId": { "$isEmpty": null }

傳回欄位值空白的記錄

""
null

$isNotEmpty

"fieldId": "$isNotEmpty"
"fieldId": { "$isNotEmpty": null }

傳回欄位值非空白的記錄

"新產品上市"

$greaterThan

"fieldId": { "$greaterThan": 10 }

傳回欄位值大於篩選器的記錄

$greaterThanOrEqual

"fieldId": { "$greaterThanOrEqual": 10 }

傳回欄位值大於或等於篩選器的記錄

$lessThan

"fieldId": { "$lessThan": 10 }

傳回欄位值小於篩選器的記錄

$lessThanOrEqual

"fieldId": { "$lessThanOrEqual": 10 }

傳回欄位值小於或等於篩選器的記錄

5
9
- 10

$isAfter

"fieldId": { "$isAfter": "2024-05-14T20:00:00.000Z" }

傳回欄位值在篩選器之後的記錄

「2024-05-15T20:00:00.000Z」

$isBefore

"fieldId": { "$isBefore": "2024-05-14T20:00:00.000Z" }

傳回欄位值在篩選器之前的記錄

「2024-05-12T20:00:00.000Z」

$isBetween

"fieldId": { "$isBetween": ["2024-05-10T20:00:00.000Z", "2024-05-15T20:00:00.000Z"] }

傳回欄位值在篩選器之間的記錄

「2024-05-12T20:00:00.000Z」
「2024-05-14T20:00:00.000Z」

$isNotBetween

"fieldId": { "$isNotBetween": ["2024-05-10T20:00:00.000Z", "2024-05-15T20:00:00.000Z"] }

傳回欄位值不在篩選器之間的記錄

「2024-05-09T20:00:00.000Z」
「2024-05-17T20:00:00.000Z」

$isAnyOf

"fieldId": { "$isAnyOf": ["active", "completed"] }

傳回欄位值為任何篩選器的記錄

"active"
"completed"

$isNoneOf

"fieldId": { "$isNoneOf": ["active", "completed"] }

傳回其欄位值不為任何篩選器的記錄

"finished"
"fixed"

$hasAnyOf

"fieldId": { "$hasAnyOf": ["active", "completed"] }

傳回欄位值具有任何篩選器的記錄

["active"， "fixed"]
["fixed"、"completed"、"finished"]

$hasAllOf

"fieldId": { "$hasAllOf": ["active", "completed"] }

傳回其欄位值具有所有篩選器的記錄

["active"， "completed"]
["active"、"completed"、"finished"]

$hasNoneOf

"fieldId": { "$hasNoneOf": ["active", "completed"] }

傳回欄位值不含任何篩選器的記錄

["fixed"， "finished"]

$isExactly

"fieldId": { "$isExactly": ["active", "completed"] }

傳回其欄位值剛好是篩選器的記錄

["active"， "completed"]

欄位類型

以下是支援的欄位型別清單，以及可搭配這些欄位型別使用的搜尋修飾詞

欄位型別

支援的搜尋修飾元

文字

$contains， $doesNotContain， $is， $isNot， $isEmpty， $isNotEmpty

長文字

$contains， $doesNotContain， $is， $isNot， $isEmpty， $isNotEmpty

數字

$is， $isNot， $greaterThan， $greaterThanOrEqual， $lessThan， $lessThanOrEqual， $isEmpty， $isNotEmpty

百分比

$is， $isNot， $greaterThan， $greaterThanOrEqual， $lessThan， $lessThanOrEqual， $isEmpty， $isNotEmpty

貨幣

$is， $isNot， $greaterThan， $greaterThanOrEqual， $lessThan， $lessThanOrEqual， $isEmpty， $isNotEmpty

日期

$is， $isNot， $isAfter， $isBefore， $isBetween， $isNotBetween， $isEmpty， $isNotEmpty

單選

$is， $isNot， $isAnyOf， $isNoneOf， $isEmpty， $isNotEmpty

多選

$hasAnyOf， $hasAllOf， $isExactly， $hasNoneOf， $isEmpty， $isNotEmpty

布林值

$is

使用者

$hasAnyOf， $hasAllOf， $isExactly， $hasNoneOf， $isEmpty， $isNotEmpty

公式

$contains， $doesNotContain， $is， $isNot， $isEmpty， $isNotEmpty

url

$contains， $doesNotContain， $is， $isNot， $isEmpty， $isNotEmpty

建立者

$is， $isNot， $isAnyOf， $isNoneOf

建立時間

$is， $isNot， $isAfter， $isBefore， $isBetween， $isNotBetween

更新者

$is， $isNot， $isAnyOf， $isNoneOf， $isEmpty， $isNotEmpty

更新時間

$is， $isNot， $isAfter， $isBefore， $isBetween， $isNotBetween， $isEmpty， $isNotEmpty

參考

$hasAnyOf， $hasAllOf， $isExactly， $hasNoneOf， $isEmpty， $isNotEmpty

查詢

取決於連結的欄位

使用「And」和「Or」陳述式

在API呼叫中，您可以擁有根據由$and"和"$or"陳述式結合的多項條件的篩選器

{
  "recordTypeId": "recordTypeId",
  "offset": "integer",
  "limit": "integer",
  "filters": [
    {
      "$or": [
        {
          "launch_date": {
            "$isBetween": [
              "2024-03-31T20:00:00.000Z",
              "2024-04-01T20:00:00.000Z"
            ]
          }
        },
        {
          "$and": [
            {
              "launch_date": {
                "$isBetween": [
                  "2024-03-31T20:00:00.000Z",
                  "2024-04-01T20:00:00.000Z"
                ]
              }
            },
            {
              "status": "active"
            }
          ]
        },
        {
          "$and": [
            {
              "launch_date": {
                "$isBetween": [
                  "2024-04-15T00:00:00.000Z",
                  "2024-04-16T00:00:00.000Z"
                ]
              }
            },
            {
              "status": "planned"
            }
          ]
        }
      ]
    }
  ]
}

使用欄位請求引數

您可以使用欄位請求引數來指定應傳回的特定欄位清單（以逗號分隔）。這些欄位名稱會區分大小寫。

例如，請求

/v1/records/search?attributes=data,createdBy

{
    "records": [
        {
            "id": "Rc6527ecb35df57c441d92ba00",
            "createdBy": "61a9cc0500002f9fdaa7a6f824f557e1",
            "createdAt": null,
            "updatedBy": null,
            "updatedAt": null,
            "customerId": null,
            "imsOrgId": null,
            "recordTypeId": null,
            "data": {
                "F666c0b58b6fee61a2ea6ea81": [
                    {
                        "externalId": null,
                        "id": "Rc665728ff95730b58bc757b13",
                        "value": null
                    },
..

會傳回類似下列的回應：

{
    "priority": 2,
    "name": "first task",
    "ID": "4c7c08fa0000002ff924e298ee148df4",
    "plannedStartDate": "2010-08-30T09:00:00:000-0600"
}

排序API中的查詢結果

如果您將以下內容附加至API呼叫，則可以根據任何欄位來排序結果：

/v1/records/search

請求內文：

{
    "recordTypeId": "Rt6527ecb25df57c441d92b9fa",
    "filters": [],
    "sorting": [
        {
            "fieldId": "F6527ecb25df57c441d92b9fc",
            "direction": "asc"
        },
        {
            "fieldId": "F658afcbd4a0273c67c346fd5",
            "direction": "desc"
        }
    ],
    "limit": 500,
    "offset": 0,
    "rowOrderViewId": "V6527ecb75df57c441d92ba03",
    "groupingFieldIds": []
}

查詢限制和分頁回應

依預設，Planning API請求會從清單開頭傳回500個結果。若要覆寫結果數目的預設限制，您可以在要求中使用limit引數，並將其設定為不同的數目，最多2000個結果。

建議您將offset引數新增至您的請求，以針對大型資料集使用分頁回應。分頁回應可讓您指定應傳回的第一個結果的位置。

例如，如果要傳回結果2001-4000，您可以使用以下請求。此範例會從2001年的結果開始，傳回處於作用中狀態的2000筆記錄：

POST /v1/records/search

請求內文：

{
    "recordTypeId": "recordTypeId",
    "offset": "2001",
    "limit": "2000",
    "filters": [
        { "status": "active" }
    ]
}

為確保結果正確分頁，請使用排序引數。如此可讓結果以相同順序傳回，因此分頁不會重複或略過結果。

如需排序的詳細資訊，請參閱本文中的在API中排序查詢結果。

recommendation-more-help

workfront-help-quicksilver