Braintreeをデータパイプラインソースとして設定する ​

Braintreeをデータパイプラインソースとして設定し、トランザクション、サブスクリプション、異議申し立て、顧客のレコードをデスティネーションに抽出します。

このガイドを使用して、機能と前提条件の確認、Braintreeのデータパイプラインソースとしての接続、パイプラインの設定、およびサポートされるオブジェクト、同期モード、スキーマ処理、制限事項の理解を行います。

サポートされている機能 ​

Braintreeをパイプラインソースとして使用する場合、次の機能がサポートされます。

• クラウド接続：固定グローバルエンドポイントを通じてHTTPS経由でBraintreeに接続します。オンプレミスエージェントは不要です。
• プロダクションおよびサンドボックスEnvironment：コネクションを設定するときにEnvironmentを選択することで、単一のコネクションからプロダクションEnvironmentまたはサンドボックスEnvironmentのいずれかに接続します。
• 完全同期と増分同期: 完全同期モードと増分同期モードをサポートします。 Braintreeは変更イベントフィードを提供しないため、増分同期では作成タイムスタンプとイベントタイムスタンプをカーソルとして使用します。詳細については、同期モードを参照してください。
• オブジェクトレベルの選択：同期するBraintreeオブジェクトを、デスティネーション内の個別のテーブルとして選択します。完全なリストについては、サポートされているオブジェクトを参照してください。
• 複数のマーチャントアカウント：デフォルトのマーチャントアカウントだけでなく、認証情報でアクセスできるすべてのマーチャントアカウント全体でトランザクションデータを同期します。トランザクションおよび異議申し立てレコードにはmerchantAccountIdフィールドが含まれているため、デスティネーション内の特定のマーチャントアカウントにレコードを関連付けることができます。
• 削除追跡：完全同期するオブジェクトについて、各同期を前回の実行と比較して削除を検出します。詳細については、削除追跡を参照してください。
• スキーマドリフトの検出と処理: 新しいフィールドを自動同期でスキーマの変更を自動的に検出して適用するか、新しいフィールドをブロックでスキーマを固定します。
• フィールドレベルのデータ保護：データがデスティネーションに到達する前に、機密フィールドをハッシュ化するか、そのままレプリケートします。
• 構成可能な同期頻度: 時間ベースの間隔またはcron式を使用して同期をスケジュールします。サポートされる最小間隔は15分です。

前提条件 ​

Braintreeをデータパイプラインソースとして接続するには、次が必要です。

• 同期するプロダクションEnvironmentまたはサンドボックスEnvironmentのBraintreeアカウント
• Merchant ID、Public key、およびPrivate key。設定手順については、Braintree APIキーを生成するを参照してください。

Braintree APIキーを生成する ​

Workatoでコネクションを作成する前に、Braintree Control PanelでMerchant IDを特定し、Public keyとPrivate keyのペアを生成します。

Braintree APIキーを生成するには、次の手順を実行します。

サポートされるコネクションタイプ ​

Braintreeデータパイプラインは、1つの認証方法をサポートしています。

• APIキー：Braintree Control Panelで生成したMerchant ID、Public key、Private keyを指定します。

Braintreeに接続する ​

Braintreeをデータパイプラインソースとして接続するには、次の手順を実行します。

パイプラインの設定 ​

Braintreeをデータパイプラインソースとして設定するには、次の手順を実行します。

[minute] [hour] [day of month] [month] [day of week]

0 8 * * *

サポートされるオブジェクト ​

Braintreeデータパイプラインは、Braintree GraphQL APIおよび従来のBraintreeゲートウェイAPIからデータを同期します。次の表は、サポートされているオブジェクトをカテゴリ別に示しています。各オブジェクトは、宛先内の個別のテーブルとして同期されます。

トランザクション ​

Transactionsはプライマリオブジェクトであり、重要なPIIおよび財務データを含みます。詳細については、機密データの処理を参照してください。

Transaction Line ItemsとTransaction Local Paymentは、それぞれLevel 3データ、およびローカルまたは代替の支払い方法に対してのみ入力されます。 Transaction Add-OnsとTransaction Discountsは、サブスクリプション請求から生成されたトランザクションに対してのみ入力されます。

サブスクリプション ​

Subscription Status Historyには、サブスクリプションのステータス変更ごとに1行が含まれます。 Subscription Add-OnsとSubscription Discountsには、サブスクリプションに現在適用されているアドオンと割引が含まれ、カタログレベルのAdd-OnsおよびDiscountsオブジェクトとは区別されます。

顧客と支払い方法 ​

Braintreeの顧客検索は更新時刻によるフィルタリングをサポートしていないため、Customersには重要なPIIが含まれ、常に完全同期されます。顧客が変更されたかどうかに関係なく、各同期で完全な顧客リストが再抽出されるため、大規模な顧客ベースを持つアカウントでは同期頻度を長めに設定してください。 Payment Methodsには、各顧客に紐付けられた保管済みの支払い方法が含まれます。

異議申し立て ​

Dispute Status Historyには、異議申し立てのステータス変更ごとに1行が含まれます。

返金と検証 ​

Credit Card Verificationsには、各カード検証試行のレコードが含まれます。

請求設定 ​

Plans、Add-Ons、およびDiscountsは、Braintree Control Panelで作成および更新する読み取り専用のカタログ定義です。 Merchant Accountsには、デフォルトアカウントだけでなく、認証情報でアクセスできるすべてのサブマーチャントアカウントが含まれます。

同期モード ​

Braintreeデータパイプラインは、完全同期と増分同期をサポートしています。同期モードは、パイプラインに追加するときにオブジェクトごとに設定されます。増分カーソルがないオブジェクトは、常に完全同期を使用します。

フル同期 ​

完全同期では、選択したオブジェクトについてBraintreeから使用可能なすべてのレコードを読み取り、デスティネーションテーブルを上書きします。各実行で完全な最新スナップショットが必要なオブジェクトには、完全同期を使用します。

増分同期 ​

増分同期では、前回の実行以降に作成または変更されたレコードを抽出します。 Braintreeは変更イベントフィードを提供しないため、Workatoは各オブジェクトの作成タイムスタンプ、または同等のイベントタイムスタンプを増分カーソルとして使用します。

レコードの作成タイムスタンプは、たとえばトランザクションがauthorizedからsettledに移行した場合など、後でステータスが変更されても変わりません。 Workatoは、これらのステータス変更を検出するために、増分実行ごとに直近3日間のウィンドウからレコードを再読み取りします。その結果、増分実行では通常、実際に新しいレコードよりも多くのレコードが抽出されます。このウィンドウは設定できません。

Transaction Line Itemsなど、親オブジェクトとともに処理されるオブジェクトは、その実行の同期ウィンドウに含まれる親レコードについてのみ更新されます。

各オブジェクトでサポートされる同期モードを確認するには、サポートされるオブジェクトの表を参照してください。

削除追跡 ​

Braintreeはどのオブジェクトにも削除シグナルを公開していないため、パイプラインは各完全同期を前回の実行と比較し、削除されたレコードをデスティネーションの_workato_is_deleted列でマークすることで削除を検出します。

増分同期されるオブジェクトは、増分実行で完全なレコードセットを再確認しないため、削除追跡をサポートしません。 Transaction Status HistoryとSubscription Status Historyは追記専用ログであり、Braintreeは過去のステータスイベントを削除しないため、削除追跡をサポートしません。

スキーマとデータ型の処理 ​

Braintreeからデータを同期する場合、スキーマとデータ型には次の考慮事項が適用されます。

金額 ​

Braintreeは金額を最小通貨単位の整数ではなく、たとえば"10.00"のような10進文字列として返します。 Workatoはこれらの値をデスティネーションに10進精度で保存し、通貨換算は行いません。複数通貨のマーチャントには、各金額フィールドとともに同期されるcurrencyIsoCodeフィールドがあります。

カスタムフィールド ​

Transactions、Customers、およびRefundsには、Braintree Control Panelで設定したカスタムフィールドを含めることができます。カスタムフィールドのセットはマーチャントによって異なるため、Workatoはこれらを個別の列ではなくcustom_fieldsJSON文字列列として保存します。

ネストされたデータと子データ ​

トランザクションのステータス履歴、明細項目、アドオン、割引など、1対多の関係を表すBraintreeデータは、個別の子テーブルとして同期されます。トランザクションの支払い方法の詳細、リスクデータ、請求先住所や配送先住所など、繰り返されないネストされたデータは、親オブジェクトのテーブル上のJSON文字列列として同期されます。

機密データの処理 ​

Braintreeオブジェクトには、重要なPIIおよび財務データが含まれる場合があります。次のオブジェクトには、一般的に機密フィールドが含まれます:

Braintreeは、どのオブジェクトについてもAPIを通じて生のカード番号やCVV値を返しません。利用できるのは、カードフィンガープリント、下4桁、およびブランド、有効期限、BINなどのカードメタデータのみです。

パイプライン設定中にフィールドレベルのデータ保護でHashオプションを使用し、PIIが宛先に到達する前に保護します。 Workatoは、PCI-DSS、GDPR、またはCCPAの下で運用されるパイプラインについて、メールアドレス、電話番号、請求先住所および配送先住所のフィールドをハッシュ化することをお勧めします。詳細については、パイプラインを構成手順を参照してください。

制限事項 ​

Braintreeをデータパイプラインソースとして使用する場合、次の制限事項が適用されます。

ステータス変更を取得するための最近のレコードの再同期 ​

Braintreeは変更イベントフィードを提供しないため、Workatoは、そのウィンドウ内で作成されたレコードのステータス変更を取得するために、実行ごとに直近3日間のウィンドウから増分同期されたレコードを再読み取りします。詳細については、増分同期を参照してください。

決済後に支払いフィールドが遅延する場合がある ​

決済済みのTransactionsレコードの支払い日や決済通貨などの支払いフィールドは、決済後に入力されるまで最大2日かかる場合があります。最近決済されたトランザクションで、これらのフィールドのnull値はエラーを示すものではありません。

最小同期頻度 ​

サポートされる最小同期間隔は15分です。これより高い頻度で同期をトリガーすることはできません。