コンポジット要求の構成

変数の宣言

コンポジット変数は、サブ要求の vars セクションで宣言します。変数にはそれぞれ name と path があります。name は任意の文字列です。path は変数の設定内容を指定します。サブ要求の応答ペイロードの値を特定する JSON path 式に設定されます。

例えば、以下の内容のアクティビティを作成するサブ要求があるとします。

      "vars": [
        {
          "name": "newActivityId",
          "path": "$.data.attributes.id"
        }
      ]

ここでは、newActivityId という名前の変数が作成され、この変数は data セクションの attributes セクションで id フィールド（通常は新規作成されたアクティビティの ID）の値に設定されます。

変数の参照

変数を参照するには、以下の構文を使用します。

${<varName>}

変数は、サブ要求の本文で任意の場所に使用できます。変数値の最も一般的な使用場所は、以下のとおりです。

• attributes フィールド内
• uri のパス内
• クエリパラメータの一部

例えば、アクティビティを作成するサブ要求があり、その後に備考・経緯を作成するサブ要求があるとします。1 つ目のサブ要求は、前述のように、newActivityId 変数を作成します。2 つ目のサブ要求の uri は以下のとおりです。

"uri": "/common/v1/activities/${newActivityId}/notes"

これにより、1 つ目のサブ要求でアクティビティの子として、新しい備考・経緯が作成されます。

前述の例でコードの全体像は、以下のとおりです。

{
  "requests": [
    {
      "method": "post",
      "uri": "/claim/v1/claims/cc:34/activities",
      "body": {
        "data": {
          "attributes": {
              "activityPattern": "contact_insured",
              "subject": "Cloud API activity"
          }
        }
      },
      "vars": [
        {
          "name": "newActivityId",
          "path": "$.data.attributes.id"
        }
      ]
    },    
    {
      "method": "post",
      "uri": "/common/v1/activities/${newActivityId}/notes",
      "body": {
        "data": {
          "attributes": {
            "body": "Cloud API note #1."
          }
        }
      }
    }
  ]
}

データのコミットの際に値を生成するフィールド

各サブ要求のサブ応答はそれぞれ、技術的にコミットされていないデータを指定しています。ただし、データがコミットされるまで生成されない値が、一部のフィールドに含まれています。

コミットの一部として生成される値がサブ応答に含まれていると、Cloud API では、コミットされるデータをできるだけ一致させようとします。例えば、コンポジット要求は ID 値を予約することで、これらの ID をサブ応答で提示してデータベースにコミットできるようにします。

ただし、Cloud API で値の一致を実行できないフィールドがいくつかあります。例えば、createTime と updateTime の値は、コミット前に決定できません。この種類のフィールドは、サブ要求のサブ応答からは常に省略されます。しかし、サブ選択で取得できます。

サブ応答の詳細の抑制

場合によっては、特定のオブジェクトが複数のサブ要求によって変更されることがあります。これにより、中間サブ応答が不必要に作成され、そのサブ応答によりコンポジット応答のサイズが不必要に増加して、コンポジット応答の解析が困難になる可能性があります。

1 つ以上のサブ要求に対して返される情報の量を抑制することで、コンポジット応答を簡素化できます。これを行うには、該当する各サブ要求で以下を含めます。

"includeResponse": false

例：

{
  "requests": [   
    {
      "method": "post",
      "uri": "/common/v1/activities/xc:202/notes",
      "body": {
        "data": {
          "attributes": {
            "body": "Cloud API note #1."
          }
        }
      },
      "includeResponse": false
    },
    ...    

コンポジット応答には、サブ要求のサブ応答が含まれます。ただし、サブ応答はエンドポイントのデフォルト応答を提示するのではなく、以下のようになります。

{
    "responseIncluded": false
},

responseIncluded フィールドのデフォルトは true です。特定のサブ要求に対して詳細な応答が必要な場合は、単純に responseIncluded の参照を省略します。

サブ要求でのクエリパラメータの使用

POST または PATCH のサブ要求では、返されるフィールドをカスタマイズすることもできます。これを行うには、fields クエリパラメータを使用します。構文は以下のとおりです。

{
  "requests": [
    {
      "method": "<post/patch>",
      "uri": "<path>",
      "body": {
        "data": {
          "attributes": {
            "<field1>": "<value1>",
            "<field2>": "<value2>",
            ...
            }
        }
      },
      "parameters" : {
        "fields" : "<value>"
      }
    }, 
    ...
  ]
}

例えば、以下のコードスニペットはアクティビティを作成します。サブ応答では、アクティビティの ID とアサインユーザーのみが含まれるように指定します。

{
  "requests": [
    {
      "method": "post",
      "uri": "/claim/v1/claims/cc:34/activities",
      "body": {
        "data": {
          "attributes": {
              "activityPattern": "contact_insured",
              "subject": "Cloud API activity"
          }
        }
      },
      "parameters" : {
        "fields" : "id,assignedUser"
      }
    },
  ...  

特定の API に対して、コンポジット要求で使用できるすべてのクエリパラメータを網羅したリストは、GET /openapi.json の呼び出しを実行することで表示できます。クエリパラメータでコンポジット要求を使用できる場合、OpenAPI の出力に含まれる行は、「"x-gw-allowForCompositeApi": true」です。

selections セクションでのクエリパラメータの使用

各サブ選択には、特定のクエリパラメータを使用できます。これには、以下が含まれます。

• fields
• filter
• includeTotal
• pageOffset
• pageSize
• sort

各サブ選択は互いに独立しています。各サブ選択に対して異なるクエリパラメータを使用でき、クエリパラメータを含むサブ選択と、含まないサブ選択を用意できます。

サブ選択にクエリパラメータを追加する構文は以下のとおりです。

  "selections": [
    {
      "uri": "<pathForFirstQuery>",
      "parameters" : {
        "fields" : "<value>",
        "filter" : [<value>],
        "includeTotal" : <value>,
        "pageOffset" : <value>,
        "pageSize" : <value>,
        "sort" : [<value>]
      }
    },
    ....
  ]

次の点に注目します。

• fields は、1 つ以上のフィールドの単一文字列をカンマで区切って指定します。文字列全体は引用符で囲みます。
  • 例："assignedUser,dueDate,priority,subject"
• filter と sort は、文字列化された配列であり、1 つ以上の式で構成されます。個々の式はそれぞれ引用符で囲みます。その上で、式のリストを [ と ] で囲みます。
  • 例： ["dueDate:gt:2022-12-20","status:in:open,complete"]
• includeTotal、pageOffset、および pageSize はブール値または整数値のいずれかなので、引用符は使用しません。

例えば、アクティビティのクエリを行う際、アサインされたユーザー、期日、優先度、および件名のフィールドのみを返す場合は、以下のようになります。

    {
      "uri": "/common/v1/activities",
      "parameters" : {
        "fields" : "assignedUser,dueDate,priority,subject"
      }

期日が 2022 年 12 月 20 日以降のオープンなアクティビティと完了したアクティビティのみを返す場合は、以下のようになります。

    {
      "uri": "/common/v1/activities",
      "parameters" : {
        "filter" : ["dueDate:gt:2022-12-20","status:in:open,complete"]      }

複数の条件に基づいてアクティビティを返す場合は、以下のようになります。

    {
      "uri": "/common/v1/activities",
      "parameters" : {
        "fields" : "assignedUser,dueDate,priority,subject",
        "filter" : ["dueDate:gt:2022-12-20","status:in:open,complete"],
        "includeTotal" : true,
        "pageSize" : 5,
        "sort" : ["dueDate"]
      }

特定の API に対して、コンポジット要求で使用できるすべてのクエリパラメータを網羅したリストは、GET /openapi.json の呼び出しを実行することで表示できます。クエリパラメータでコンポジット要求を使用できる場合、OpenAPI の出力に含まれる行は、「"x-gw-allowForCompositeApi": true」です。

クエリのみを実行するコンポジット要求

データの作成や変更を行わずにデータのクエリのみを行うコンポジット要求を作成できます。これを実行するには、selections セクションのみを含んで requests セクションを含まないコンポジット要求を作成します。この場合、selections セクションの GET は常に実行されます。

selections サブ要求に対する応答

コンポジット要求に selections セクションが含まれる場合、応答にも selections セクションが含まれます。このセクションの構造は、responses セクションと同じです。各サブ選択に対してサブ応答が 1 つ含まれます。サブ応答にはそれぞれ 3 つのセクションがあります。

• body セクションにはデフォルトで、対応エンドポイントで定義されるデフォルト応答データが含まれます。
• headers セクションには、カスタムヘッダーがある場合、当該ヘッダーが含まれます。
• status フィールドは、サブ応答のステータスコードを示します。