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

 メモ:   この記事は、AWS Lambda、Genesys Cloud、Google、Microsoft Dynamics 365、Salesforce、Web サービス、Zendesk データ アクションの統合に適用されます。

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

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

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

生の回答

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

 メモ:   Google Cloud Functionsは、変換マップを処理する前にアクションがJSONに変換する文字列化されたJSON 応答を返します。

翻訳マップ

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

変換マップのデフォルト

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

成功テンプレート

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

解決された回答

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

成功スキーマ

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

ユースケース

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

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

サードパーティーからの応答が成功スキーマと一致する場合は、何も操作せずに生の応答を返します。 この場合は、デフォルトの要求テンプレートを使用してください。 他の値が提供されない場合、 デフォルト要求テンプレートは組み込みを使用します 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}

解決された応答

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

[
    {
      "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 raw 応答から値を抽出し、それらをエイリアスに割り当てます idValue, 支払額, 結果値、そして sourceValue. 変換マップのデフォルト値は設定デフォルトの値を sourceValue. 成功テンプレートは、これらすべてのエイリアスを使用します。

変換マップのデフォルト

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

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

支払プロバイダからの応答は、翻訳マップにソースプロパティを含めることも、含めないこともあります。 私たちは、ソースプロパティを使用することを確実にするために場合は応答 、それを含んでおり、場合、エラーをスローしません応答 、それを含んでいない、セット sourceValue 翻訳マップのデフォルトは 「わからない」.

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

成功テンプレート

成功テンプレートは、エイリアスを参照する有効なJSON 応答を作成します idValue, 支払額、そして 結果値 翻訳マップで作成されたもの。 別名は、成功スキーマと一致するために必要な生の応答内の値を指します。

{
   "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"
}

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

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

統合の詳細については、 データアクションの統合についてをご覧ください。