Adobe Workfront Planning API の基本

Adobe Workfront Planning APIの目的は、HTTP経由で動作するRESTful アーキテクチャを導入することで、Planningとの統合を構築することを簡素化することです。 このドキュメントでは、RESTおよびJSON応答に精通していることを前提としています。

エンドポイントの完全なリファレンス、リクエスト/レスポンスのスキーマ、バージョン固有の詳細については、Workfront Planning API開発者ドキュメント ​を参照してください。

認証

Workfront Planning APIは、認証にOAuth 2.0を使用します。 資格情報は、Adobe Developer Consoleを使用して設定します。

統合タイプに応じて、次の2つのフローをサポートしています。

初めに、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構造と操作

オブジェクトは、一意の URI に HTTP リクエストを送信して操作します。 操作は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を確認するために識別子の種類を設定するには、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をこれらのオブジェクトに割り当てます。 これらのフィールドを元のオブジェクト IDで直接フィルターするには、フィルター条件に"matchExternalId": trueを追加します。

このフラグは、referenceOptions.isExternalがtrueの参照フィールドに対してのみ有効です。外部参照フィールド以外では無視されます。 1つの文字列値を解決できない場合、リクエストは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
      }
    ]
  }
}

外部接続フィールド

プランニングレコードタイプは、レコードを他のプランニングレコードタイプではなく、他のAdobe システムのオブジェクトにリンクする外部参照フィールドをホストできます。

APIを介して外部参照フィールドを作成するには、新しいREFERENCE フィールドのreferenceOptions.recordTypeIdを、目的の外部レコードタイプのIDに設定します。 サーバーは、ターゲット レコード タイプから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 レコードの2番目のページを取得します。

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は、1回のリクエストでのレコードの一括作成、更新、パッチ適用、削除をサポートしています。 エンドポイントパス、リクエスト形式、操作ごとのレコードの制限については、developer.adobe.com/wf-planningの​ API リファレンス ​を参照してください。

権限

エンティティへの権限は、リソースエンドポイント自体とは別に、専用の権限APIを使用して管理されます。 これにより、現在の権限を読み取り、共有リストを管理し、データ操作とは独立してアクセス要求を処理できます。 詳しくは、Workfront Planning APIの「API リファレンス」の節を参照してください。

Workfront カスタムフォームでのPlanning APIの使用

Workfront カスタムフォームの外部ルックアップフィールドからPlanning APIを呼び出して、Workfront オブジェクト内に直接Planning データを表示できます。 詳細については、​ カスタムフォームの外部ルックアップフィールドの例を参照してください。

関連リソース

API関連の詳細なドキュメントについては、次の記事も参照してください。