データアクションの応答設定

注意：この記事は、AWS Lambda、Microsoft Dynamics 365、PureCloud、Salesforce、Webサービス、およびZendeskデータアクション統合に適用されます。

データアクション統合用のカスタムアクションを作成できます。カスタムアクションは、その設定にリクエストとレスポンスを含みます。詳細については、 カスタムアクションを作成するを参照してください。

この記事では、回答の一部について説明します。要求については、設定を要求するを参照してください。

カスタムアクションは、トランスレーションマップと成功テンプレートを使用して、リモートWebサービスまたはAWS Lambda関数からの生の応答を、定義された成功スキーマに準拠する解決済み応答に変換します。これらの成功テンプレートはマクロの使用をサポートしています。詳細については、 データアクション用の速度マクロ。

生の回答

データアクション統合に対してアクションが実行されると、リモートWebサービスまたはAWS Lambda関数からの出力全体が生の応答と呼ばれます。ただし、生の応答が必ずしもアクションの成功スキーマで定義されている形式と一致するとは限りません。生の応答が一致しない場合は、変換マップと成功テンプレートを使用してデータを再フォーマットできます。

翻訳マップ

変換マップには、JSONPath式の評価から返された値（またはオブジェクト）にプロパティ名をマッピングするキーと値のペアが含まれています。

変換マップのデフォルト

トランスレーションマップのデフォルトには、トランスレーションマップのキーをデフォルト値に設定するキーと値のペアが含まれています。トランスレーションマップで設定されたJSONPath式が値の解決に失敗した場合は、デフォルト値が使用されます。 NULL値はデフォルトにフォールバックしません。

成功テンプレート

成功テンプレートは、速度テンプレート言語からの変数表記法を使用します。成功テンプレートは、トランスレーションマップからのプロパティ名を使用して、JSONPath式によって返されたデータを挿入します。一般に、成功テンプレート内のすべてのデータは、出力ではリテラルとして扱われます。$ {}内の項目は、トランスレーションマップからの値への参照です。詳細については、 Apache Velocity Projectのドキュメントをご覧ください。

解決された回答

成功テンプレートは、成功スキーマに準拠しなければならない解決済みの応答を作成します。そうでなければ、エラーが発生します。

成功スキーマ

成功スキーマは、アクションの応答に必要な形式を定義します。

ユースケース

次のような状況では、翻訳マップと成功テンプレートを使用して未加工の回答を変換することがよくあります。

  • 生の応答には複数のオブジェクトが含まれています。解決された出力が成功スキーマと一致するには、複数のオブジェクトを別のオブジェクトのメンバーとして返す必要があります。
  • 生の応答には、離散値に変換する値や配列などの変換型が含まれています。
  • 特定のデータのサブセットのみを返します。
  • 返された属性の順序を保証する必要があります。

サードパーティーからの応答が成功スキーマと一致する場合は、何も操作せずに生の応答を返します。この場合は、デフォルトの要求テンプレートを使用してください。他に値が指定されていない場合、デフォルトのリクエストテンプレートは組み込みのrawResultコンテキスト値を使用します。成功テンプレートは、値を抽出するために変換マップを使用せずに結果全体を渡します。

${rawResult}

Salesforce GetContactByPhoneNumberアクションの例

生の反応

以下は、Salesforce GetContactByPhoneNumberアクションが実行されたときのSalesforceからの生の応答の例です。

{
  "searchRecords": [
    {
      "attributes": {
        "type": "Contact",
        "url": "/services/data/v37.0/sobjects/Contact/003G000001LrjlTIAR"
      },
      "Email": null,
      "FirstName": "Jack",
      "HomePhone": null,
      "Phone": "(317) 555-0123",
      "Id": "003G000001LrjlTIAR",
      "LastName": "Teller",
      "MobilePhone": null,
      "OtherPhone": null,
      "MailingStreet": null,
      "MailingCity": null,
      "MailingState": null,
      "MailingCountry": null,
      "MailingPostalCode": null
    }
  ]
}

生の応答にはルートノード（searchRecords）が含まれています。searchRecordsオブジェクトは、Salesforceから返された連絡先情報を表します。

翻訳マップ

変換マップは、生の応答からデータのセグメントを引き出します。この場合、ノード全体のsearchRecordsを取得します。

メモ：
  • 変換マップ内のプロパティ名は、英字（az、AZ）で始まり、英字、数字（0-9）、ハイフン（ - ）、または下線（_）のみを含める必要があります。
  • 値の名前にスペースが含まれている場合は、名前の前後に角かっこと一重引用符を追加します（例：“ contact”）。“ $。[’検索レコード]]。

"translationMap": {
  "contact": "$.searchRecords"
}

JSONPath式$.searchRecordsは、生の応答からsearchRecordsオブジェクトを抽出し、それにエイリアス“ contact”を割り当てます。成功テンプレートは別名を使用します。

成功テンプレート

成功テンプレートは、トランスレーションマップで作成されたエイリアス「contact」を参照します。別名は、成功スキーマと一致するために必要なすべての値を含む生の応答内のオブジェクトを指します。

${contact}

解決された応答

成功テンプレートは、アクションに対する解決された応答を作成します。解決された応答は、アクションが返す応答です。

[
    {
      "attributes": {
        "type": "Contact",
        "url": "/services/data/v37.0/sobjects/Contact/003G000001LrjlTIAR"
      },
      "Email": null,
      "FirstName": "Jack",
      "HomePhone": null,
      "Phone": "(317) 555-0123",
      "Id": "003G000001LrjlTIAR",
      "LastName": "Teller",
      "MobilePhone": null,
      "OtherPhone": null,
      "MailingStreet": null,
      "MailingCity": null,
      "MailingState": null,
      "MailingCountry": null,
      "MailingPostalCode": null
    }
]

支払いプロバイダで使用するためのアクション例

生の反応

以下は、クレジットカードに請求したときのアクションに対する未処理のレスポンスの例です。

{
  "id": "ch_1AS7Iv2eZvKYlo2CmgEX0bHw",
  "object": "charge",
  "amount": 999,
  "amount_refunded": 0,
  "application": null,
  "application_fee": null,
  "balance_transaction": "txn_1AS7Iv2eZvKYlo2CjrARHR6C",
  "captured": true,
  "created": 1496854005,
  "currency": "usd",
  "customer": "cus_AFEwvtMn3H17af",
  "description": null,
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": "in_1AS6Mf2eZvKYlo2C9QEibbxz",
  "livemode": false,
  "metadata": {
  },
  "on_behalf_of": null,
  "order": null,
  "outcome": {
    "network_status": "approved_by_network",
    "reason": null,
    "risk_level": "normal",
    "seller_message": "Payment complete.",
    "type": "authorized"
  },
  "paid": true,
  "receipt_email": null,
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [
 
    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_1AS7Iv2eZvKYlo2CmgEX0bHw/refunds"
  },
  "review": null,
  "shipping": null,
  "source": {
    "id": "card_19ukSY2eZvKYlo2CHlYUs1DM",
    "object": "card",
    "address_city": null,
    "address_country": null,
    "address_line1": null,
    "address_line1_check": null,
    "address_line2": null,
    "address_state": null,
    "address_zip": "94301",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": "cus_AFEwvtMn3H17af",
    "cvc_check": null,
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2018,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": null,
    "tokenization_method": null
  },
  "source_transfer": null,
  "statement_descriptor": null,
  "status": "succeeded",
  "transfer_group": null
}

翻訳マップ

変換マップは、生の応答からデータのセグメントを引き出します。この場合、生の応答から4つのフィールドを取り出します。

"translationMap": {
  "idValue": "$.id",
  "paidValue": "$.paid",
  "outcomeValue": "$.outcome",
  "sourceValue": "$.source"
}

JSONPath式の$.id、$.paid、$。outcome、および$.sourceは、生の応答から値を抽出し、それらをエイリアスidValue、payValue、outcomeValue、およびsourceValueに割り当てます。トランスレーションマップのデフォルトは、sourceValueのデフォルト値を設定します。成功テンプレートは、これらすべてのエイリアスを使用します。

変換マップのデフォルト

トランスレーションマップのデフォルトは、トランスレーションマップのキーをデフォルト値に設定します。この場合、応答にはソースプロパティが含まれていなかったので、sourceValueをデフォルト値「UNKNOWN」に設定します。

"translationMapDefaults": {
  "sourceValue": "\"UNKNOWN\""
}

支払プロバイダからの応答は、翻訳マップにソースプロパティを含めることも、含めないこともあります。レスポンスに含まれる場合はsourceプロパティを使用し、レスポンスが含まない場合はエラーをスローしないようにするには、トランスレーションマップのsourceValueをデフォルトの「UNKNOWN」に設定します。

応答に翻訳マップの他のフィールドが含まれていない場合、アクションは失敗します。

成功テンプレート

成功テンプレートは、トランスレーションマップで作成されたエイリアスIdValue、paidValue、およびoutcomeValueを参照する有効なJSONレスポンスを作成します。別名は、成功スキーマと一致するために必要な生の応答内の値を指します。

{
   "id": ${idValue},
   "outcome": ${outcomeValue},
   "paid": ${paidValue},
   "source": ${sourceValue}
}
注意：$ {}の外側のテキストはリテラルとして扱われます。

解決された応答

成功テンプレートは、アクションに対する解決された応答を作成します。解決された応答は、アクションが返す応答です。

{
   "id": "ch_1AS7Iv2eZvKYlo2CmgEX0bHw",
   "outcome": {
      "network_status": "approved_by_network",
      "reason": null,
      "risk_level": "normal",
      "seller_message": "Payment complete.",
      "type": "authorized"
   },
   "paid": true,
   "source": "UNKNOWN"
}

カスタムアクションの設定については、 設定を追加 そして 構成を変更するを参照してください。

詳細については、 統合のカスタムアクションについて。

統合について詳しくは、AWS Lambdaデータアクション統合について、 Microsoft Dynamics 365データアクション統合について、 PureCloudデータアクション統合について、 Salesforceデータアクション統合について、 Web サービス データアクションの統合について、そして Zendeskデータアクション統合についてを参照してください。