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

Squareをデータパイプラインソースとして設定し、支払い、注文、カタログ、顧客、労務レコードを送信先に抽出します。

このガイドを使用して、Squareアクセストークンを生成し、コネクションを設定し、パイプラインを設定し、オブジェクトを追加し、同期動作を確認し、既知の制限事項を理解します。

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

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

• クラウド接続：https://connect.squareup.com/v2を通じてHTTPS経由でSquareに接続します。オンプレミスエージェントは不要です。
• SandboxおよびプロダクションEnvironment：ライブのプロダクションアカウント、またはテスト用のSquare Sandboxアカウントのいずれかに接続します。 Workatoは各モードを別々のEnvironmentとして扱います。
• 完全同期と増分同期: 完全同期モードと増分同期モードをサポートします。増分同期では、それをサポートするオブジェクトに対してタイムスタンプフィルターを使用します。詳細については、同期モードを参照してください。
• オブジェクトレベルの選択：Squareオブジェクトを選択して、送信先の個別のテーブルとして同期します。完全なリストについては、サポートされているオブジェクトを参照してください。
• 論理削除の追跡：カタログオブジェクトにはネイティブの削除済みフラグがあり、Workatoはそれを送信先に保持します。詳細については、削除追跡を参照してください。
• カスタム属性：販売者またはパートナーアプリケーションがCustomers、Locations、Orders、Merchants、およびカタログオブジェクトで定義するカスタム属性は、専用の列として同期されます。詳細については、カスタム属性を参照してください。
• スキーマドリフトの検出と処理: 新しいフィールドを自動同期でスキーマの変更を自動的に検出して適用するか、新しいフィールドをブロックでスキーマを固定します。
• フィールドレベルのデータ保護: 機密フィールドをそのままレプリケートするか、宛先に到達する前にハッシュ化します。
• 構成可能な同期頻度: 時間ベースの間隔またはcron式を使用して同期をスケジュールします。サポートされる最小間隔は15分です。

前提条件 ​

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

• Squareアカウント、またはプロダクションデータに接続する前にパイプラインをテストする場合はSquare Sandboxアカウント
• 選択した認証方法の認証情報:
  • パーソナルアクセストークン：Square Developer Consoleから生成されたSquareパーソナルアクセストークン。設定手順については、Squareパーソナルアクセストークンを生成するを参照してください。
  • OAuth 2.0：サードパーティアプリケーションの認可権限を持つSquareアカウントユーザー。

Squareパーソナルアクセストークンを生成する ​

Workatoでコネクションを作成する前に、Square Developer Consoleでトークンを生成します。 OAuth 2.0で接続する場合は、このセクションをスキップします。

トークンの生成と管理の詳細については、Squareのアクセストークンドキュメントを参照してください。

Workatoは、OAuthコネクションに対して、同期できる各オブジェクトについて読み取り専用スコープをリクエストします。たとえば、PaymentsにはPAYMENTS_READ、CustomersにはCUSTOMERS_READです。接続時にリクエストされる正確なスコープの詳細については、SquareのOAuth Permissions Referenceを参照してください。

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

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

• パーソナルアクセストークン：Square Developer Consoleから生成されたアクセストークンを指定します。このトークンはアカウントへの無制限のアクセスを付与し、単一アカウントの連携に適しています。設定手順については、Squareパーソナルアクセストークンを生成するを参照してください。
• OAuth 2.0：SquareアカウントからWorkatoアクセスを認可して、認可コードグラントを通じて接続します。複数の販売者アカウントを接続する場合に推奨されます。

Squareに接続する ​

Squareに接続するには、次の手順を実行します。

パイプラインの設定 ​

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

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

0 8 * * *

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

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

支払いと返金 ​

注文 ​

顧客 ​

カタログと在庫 ​

カタログオブジェクトはカスタム属性をサポートし、ネイティブの削除済みフラグを保持します。詳細については、カスタム属性および削除追跡を参照してください。 Inventoryは現在の在庫レベルのみを反映し、過去の在庫数の履歴は保持しません。

ロケーションとアカウント ​

労務とチーム ​

ギフトカードとロイヤルティ ​

Loyalty AccountsまたはLoyalty Programsを同期するには、SquareアカウントにLoyaltyプログラムが設定されている必要があります。詳細については、制限事項を参照してください。

請求書発行とサブスクリプション ​

ベンダー ​

同期モード ​

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

フル同期 ​

完全同期では、選択したオブジェクトについてSquareから使用可能なすべてのレコードを読み取り、送信先テーブルのレコードセットを置き換えます。 Square APIに信頼できる変更時刻フィルターがないオブジェクト（Locations、Merchants、Team Members、Vendorsなど）は、完全同期のみをサポートします。

増分同期 ​

増分同期では、最後に成功した実行以降に変更されたレコードのみを抽出します。 Square増分同期では、オブジェクトに応じて次のメカニズムを使用します。

• Payments、Orders、Customers、およびほとんどのカタログオブジェクト（Catalog Items、Catalog Categories、Catalog Discounts、Catalog Taxes、Catalog Modifier Lists、Catalog Pricing Rules）：新規レコードと編集済みレコードの両方をキャプチャするupdated_atフィルター。
• Inventory：各アイテムとロケーションの最新の在庫調整を反映するcalculated_atフィルター。
• Timecards：start_atフィルターに加えて、過去90日間を週次で再読み取りして遡及的な編集を検出します。これは、Squareがタイムカード用のupdated_atフィルターを公開していないためです。詳細については、制限事項を参照してください。
• Refunds、Payouts、Cash Drawer Shifts：作成時刻フィルターのみを使用するため、すでに同期済みのレコードに対するステータス変更はキャプチャされません。詳細については、制限事項を参照してください。
• Gift Card Activities：作成時刻フィルター。ギフトカードアクティビティは追記専用ログであり、作成後に編集されることはありません。

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

削除追跡 ​

削除追跡は、オブジェクトの同期モードによって異なります。完全同期オブジェクトははい（送信先推定）としてマークされます。これは、Workatoが各実行の完全なレコードセットを前回の実行と比較し、表示されなくなったレコードにフラグを付けるためです。 Catalog Itemsとその関連カタログオブジェクトには、オブジェクトが削除されたときにSquareが設定するネイティブのis_deletedフィールドがあるため、Workatoは代わりにこれらをはい（論理削除）としてマークします。

ソース駆動の削除シグナルがなく増分同期されるオブジェクトはいいえとしてマークされます。これは、増分実行では変更されたレコードのみが読み取られ、SquareがRESTリストエンドポイントを通じて削除イベントを発行しないためです。 Inventoryは個別のレコードではなく現在の在庫レベルを反映するため、削除追跡は適用されません。

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

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

データ型 ​

SquareはタイムスタンプをUTCのRFC 3339文字列として返します。支払いのカード詳細など、独自の子テーブルとして同期されないネストされたオブジェクトは、代わりにJSON文字列列として同期されます。 Workatoは、Order Line Items、Catalog Item Variations、Timecard Breaksを個別の子テーブルとして抽出します。 Ordersには常にcustomer_idが含まれるとは限りません。ゲストチェックアウトでは空のままになります。

カスタム属性 ​

Squareの販売者およびパートナーアプリケーションは、Customers、Locations、Orders、Merchants、およびカタログオブジェクトにカスタム属性を定義できます。 Workatoは各定義を検出し、専用のcattr_<key>列として追加します。この列は、選択した場合にのみ送信先に表示されます。 Customers、Locations、Orders、またはMerchantsでカスタム属性列を選択すると、レコードごとにAPI呼び出しが追加され、大量のオブジェクトでは同期時間が長くなります。カタログオブジェクトでは、Squareがカスタム属性値をインラインで返すため、このコストは発生しません。

機密データの処理 ​

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

Squareは、APIを通じて生のカード番号またはCVV値を返しません。 Squareは、Paymentsに対してトークン化およびフィンガープリント化されたカードデータのみを返します。

パイプライン設定中にフィールドレベルのデータ保護でHashオプションを使用し、PIIが宛先に到達する前に保護します。詳細については、パイプラインを構成手順を参照してください。

制限事項 ​

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

一部のオブジェクトは新規レコードのみを検出し、後続の更新は検出しません ​

Refunds、Payouts、Cash Drawer Shiftsは増分同期を作成時刻のみでフィルタリングするため、返金の完了や支払いの失敗などの後続のステータス変更は、レコードの初回同期後にはキャプチャされません。 Timecardsにも、90日間のルックバックウィンドウを超える同じギャップがあります。これらのオブジェクトのいずれかについて特定の日付範囲を復旧するには、When first started, this pipeline should pick up records fromフィールドを影響を受けるレコードより前の日付に設定し、完全同期を再実行します。

Loyalty ProgramsオブジェクトにはSquare Loyaltyプログラムが必要です ​

Squareアカウントに設定できるLoyaltyプログラムは最大1つです。アカウントにLoyalty Programsが設定されていない場合、同期は失敗します。 Squareのロイヤルティ機能を使用しない場合は、このオブジェクトをスキップします。

最小同期頻度 ​

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