Adobe Workfront計画 API の基本

最終更新日： 2024年8月27日

トピック：

作成対象：

ユーザー
管理者

IMPORTANT

この記事では、Adobe Workfrontの追加機能であるAdobe Workfront Planning について説明します。

Workfront Planning にアクセスするには、次のものが必要です。

新しいWorkfront パッケージおよびライセンス。 Workfront Planning は、従来のWorkfront パッケージまたはライセンスでは使用できません。
Workfront Planning パッケージ。
組織のWorkfront インスタンスは、Adobe Unified Experience にオンボーディングされる必要があります。

Workfront Planning へのアクセス要件の完全なリストについては、アクセスの概要を参照してください。

Workfront計画の詳細については、Adobe Workfront計画の概要を参照してください。

Adobe Workfront Planning API の目標は、HTTP 経由で動作する REST-ful アーキテクチャを導入することで、Planning との統合を簡単に構築することです。このドキュメントは、REST 応答と JSON 応答に精通していることを前提としており、Planning API によるアプローチについて説明しています。

Workfront Planning スキーマをよく理解しておくと、統合を目的としてWorkfront Planning からデータを取り出す際に利用できるデータベースの関係を理解しやすくなります。

Workfront カスタムフォームの外部参照フィールドから Planning API を呼び出すことができます。

外部検索フィールドについて詳しくは、「カスタムフォームにおける外部検索フィールドの例」を参照してください。

Workfront計画 API の URL

操作

オブジェクトは、一意の URI に HTTP リクエストを送信して操作します。実行する操作は、HTTP メソッドで指定します。

標準の HTTP メソッドは、次の操作に対応しています。

GET - ID でオブジェクトを取得し、クエリですべてのオブジェクトを検索します
POST - 新しいオブジェクトを挿入
PUT - 既存のオブジェクトを編集
DELETE - オブジェクトを削除

各操作の詳細と例については、Workfront Planning API 開発者向けドキュメントを参照してください。

フィールドタイプと、それらで使用される検索修飾子

フィールドに修飾子とフィルターを使用して、結果で返されるデータを制御できます。

検索修飾子の使用

Workfront Planning では、次の検索修飾子をサポートしています。

修飾子	例	説明	可能な値
$contains	`"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 }`	フィールド値が空でないレコードを返します	"" ヌル
$isNotEmpty	`"fieldId": "$isNotEmpty"` `"fieldId": { "$isNotEmpty": null }`	フィールド値が空でないレコードを返します	「新製品の発売」
$greaterThan	`"fieldId": { "$greaterThan": 10 }`	フィールド値がフィルターよりも大きいレコードを返します	20 25
$greaterThanOrEqual	`"fieldId": { "$greaterThanOrEqual": 10 }`	フィールドの値がフィルターよりも大きいか等しいレコードを返します	10 20 25
$lessThan	`"fieldId": { "$lessThan": 10 }`	フィールド値がフィルターよりも小さいレコードを返します	5 9
$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"] }`	フィールド値がフィルターのいずれかであるレコードを返します	"アクティブ" "completed"
$isNoneOf	`"fieldId": { "$isNoneOf": ["active", "completed"] }`	フィールド値がフィルターのいずれでもないレコードを返します	"完了" "fixed"
$hasAnyOf	`"fieldId": { "$hasAnyOf": ["active", "completed"] }`	フィールド値にフィルターのいずれかが含まれているレコードを返します	["アクティブ", "固定"] ["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