IBM App Connect Enterprise でのSquare の利用

正方形 は、中小企業がクレジット・カード決済を受け取ったり、POS システムの決済ログとしてタブレット・コンピューターを使用したりできるようにすることを目的とした決済プラットフォームです。 IBM® App Connect Enterprise 「Square Request 」ノードが用意されており、これを使用して Square に接続し、在庫、顧客、注文、請求書、支払い、返金などのオブジェクトに対して操作を実行するリクエストを送信できます。

このタスクの概要

IBM App Connect Enterprise Windows、 AIX、および Linux® システムで利用可能な「 Square Request 」ノードを介して、 Square と同期的に通信します。

「正方形の要求」 ノードを使用して、 「正方形」 に接続し、以下のようなオブジェクトに対してアクションを実行する要求を発行できます。
バッチ変更インベントリー
バッチ変更インベントリーの作成または取得
カスタマー
顧客を作成、取得、更新、または削除します。 顧客の更新または作成
請求書
請求書を作成、取得、更新、または削除します。 請求書の更新または作成
Orders
オーダーを作成、取得、更新、検索、または削除します。 オーダーの更新または作成
決済
支払いを作成、取得、更新、または削除します。 支払いの更新または作成
払い戻し手数料
支払返金の作成または取得

「正方形の要求」 ノードの構成について詳しくは、 正方形の要求ノードを参照してください。

手順

  1. 「 IBM App Connect Enterprise 」ツールキットで、 Square Request ノードを含むフローを作成します。
  2. フロー内の 「正方形の要求」 ノードを選択して、エディターにノード・プロパティーを表示します。
  3. 「基本」 タブで、 「コネクター・ディスカバリーの起動」をクリックします。
    コネクターのディスカバリー中に使用するポリシー・プロジェクトの名前とボールトの詳細を指定するパネルが表示されます。
  4. コネクターのディスカバリー中に使用するポリシー・プロジェクトとボールトの詳細を指定します。
    1. 「ポリシー・プロジェクト」 フィールドに、コネクター・ディスカバリー中に作成されるポリシーを保管するために使用されるポリシー・プロジェクトを指定します。
      あるいは、「新規」をクリックし、新規ポリシー・プロジェクトの名前を指定して、新規ポリシー・プロジェクトを作成することもできます。 次に、「完了」をクリックします。
    2. コネクターのディスカバリー中に使用するボールトを指定します。 デフォルトでは、コネクター・ディスカバリー中に使用される資格情報は、 外部ディレクトリー・ボールトに保管されます。これは、任意の統合サーバーで使用できる App Connect Enterprise ボールトです。 あるいは、資格情報を統合サーバー・ボールトに保管することもできます。統合サーバー・ボールトは、統合サーバーの作業ディレクトリーに作成され、その特定の統合サーバーでのみ使用できます。
      資格情報の保管に使用するボールトを指定するには、以下のいずれかのトピックの 「コネクター・ディスカバリー・ウィザードの使用」 セクションのステップを実行します。
    3. 「ボールト鍵 (Vault key)」 フィールドに、ボールトに保管されている資格情報にアクセスするために使用するボールト鍵を入力します。 ボールト鍵の長さは 8 文字以上でなければなりません。
    4. オプション: デフォルトでは、指定されたボールト・ロケーションとボールト・キーが Toolkit の設定として保存されるため、コネクター・ディスカバリーの起動時に値が事前設定されます。 設定を保存しない場合は、ボールト設定に保存 を選択解除します。
  5. 「ディスカバリーの起動」 をクリックして、 「正方形」 コネクターの「コネクター・ディスカバリー」ウィザードを開始します。
    「コネクター・ディスカバリー」 ウィンドウが表示されます。 既存の 正方形 接続 (アカウント) が使用可能な場合は、それらの接続のリストが表示されます。 既存の接続がない場合、 「正方形」 コネクターの状況は Not connectedとして表示されます。
    • 1 つ以上の 「正方形」 接続 (アカウント) が使用可能な場合は、以下の手順を実行します。
      1. 接続 (アカウント) をクリックして、使用する接続 (アカウント) を選択します。
      2. 必要なオブジェクト・タイプをクリックし、オブジェクトに対して実行するアクションを選択します。 例えば、 「正方形」から顧客を取得するには、 「顧客」 をクリックしてから、 「顧客の取得」をクリックします。
    • 既存の接続 (アカウント) がない場合は、以下のステップを実行します。
      1. 必要なオブジェクト・タイプをクリックし、そのオブジェクトに対して実行するアクションを選択します。 例えば、 「正方形」から顧客を取得するには、 「顧客」 をクリックしてから、 「顧客の取得」をクリックします。
      2. 「接続」 をクリックして、以下のいずれかの許可方式を選択する必要があるメニューを表示します。
        • 使用する App Connect の資格情報を指定します (API キー)
        • 使用する App Connect の資格情報を指定します (BASIC OAUTH)
      3. 許可方式として 「使用する App Connect の資格情報を指定 (API キー)」 を選択した場合は、以下の詳細を入力します。
        1. エンドポイントの URL フィールドに、 Squareインスタンスを認証するための URL を入力します。 例えば、サンドボックス環境では、エンドポイント URL は connect.squareupsandbox.com であり、本番環境プラットフォームでは、エンドポイント URL は connect.squareupsandbox.com です。
        2. 「個人用アクセス・トークン (Personal access token)」 フィールドに、 「正方形」のアプリケーションの資格情報セクションの下に生成された実動アクセス・トークンまたはサンドボックス・アクセス・トークンを入力します。
        3. プロキシ名 ： App Connect がコネクタへの呼び出しを転送するために使用するプロキシの名前を選択または指定します。 このフィールドは、呼び出しをプロキシ経由で行う必要がある場合にのみ必須となります。 IBM App Connect Enterprise ツールキットを使用する際は、プロキシ名を次の形式で指定する必要があります： {PolicyProjectName}:HTTPProxyPolicyName
      4. 許可方式として「 Provide credentials for App Connect to use (BASIC OAUTH) 」を選択した場合は、以下の詳細を入力します。
        1. エンドポイントの URL フィールドに、 Squareインスタンスを認証するための URL を入力します。 例えば、サンドボックス環境では、エンドポイント URL は connect.squareupsandbox.com であり、本番環境プラットフォームでは、エンドポイント URL は connect.squareupsandbox.com です。
        2. 「クライアントID 」フィールドに、 Square のアプリケーション設定の「 OAuth 」セクションで生成された本番用アプリケーションIDまたはサンドボックス用アプリケーションIDを入力してください。
        3. 「アクセス・トークン」 フィールドに、アプリケーション・クライアント ID およびクライアント秘密鍵から生成されたアクセス・トークンを入力します。
        4. 「リフレッシュ・トークン」 フィールドに、アプリケーション・クライアント ID とクライアント秘密鍵から生成されたリフレッシュ・トークンを入力します。
        5. リダイレクト URI フィールドに、認証後に Square がブラウザをリダイレクトする URI（ URL ）を入力します。
        6. プロキシ名 ： App Connect がコネクタへの呼び出しを転送するために使用するプロキシの名前を選択または指定します。 このフィールドは、呼び出しをプロキシ経由で行う必要がある場合にのみ必須となります。 IBM App Connect Enterprise ツールキットを使用する際は、プロキシ名を次の形式で指定する必要があります： {PolicyProjectName}:HTTPProxyPolicyName

        これらの接続情報の取得または生成に関する詳細については、『 IBM 』 の 「継続的デリバリー（CD）」ドキュメントにある「Squareでの IBM の使用方法」 App Connect を参照してください。 App Connect in containers

      5. 「接続」 をクリックします。
  6. ウィザードで必要なコネクター・プロパティーを設定します。
    取得アクションまたは更新アクションの場合、 「条件の追加」 をクリックし、フィルターに掛けるプロパティーを選択することで、データを取得するための条件を追加できます。

    取得アクションまたは更新アクションの条件を追加する場合、オプションで条件フィルターを使用して、適用される条件を絞り込むことができます。 条件フィルタリングを使用するには、「閉じる」ボタン（X）をクリックしてコネクタ検出ウィザードを終了し、「 条件フィルタリングの使用 」の手順に従ってください。

    作成アクションの場合は、オプションで拡張モードを使用できます。 アクションのデフォルトの編集ビューでは、一部のアプリケーションには、一般的なユース・ケースでは必要ないために非表示になっているフィールドがあります。 より高度なユース・ケースでは、拡張モード編集に切り替えることができます。これにより、フローを編集するための追加機能が提供されます。 詳細モードを使用するには、「閉じる」ボタン（X）をクリックしてコネクタ検出ウィザードを終了し、その後「 詳細モードの使用 」の手順に従ってください。

    また、取得するレコードの最大数と、その制限を超えた場合に実行するアクションを指定するプロパティーを設定することもできます。

  7. 「コネクター・ディスカバリー」ウィザードでのプロパティーの指定が完了したら、 「保存」をクリックします。
    「正方形」 への接続に使用される資格情報はボールトに保管され、その他の接続の詳細は 「正方形」 ポリシーに保存されます。 詳細については、 Squareのポリシー をご覧ください。 ウィザードで設定したプロパティの値は、 IBM App Connect Enterprise Toolkit の 「Square Request 」ノードに返されます。
  8. ディスカバリーを終了してプロパティー値を保存したら、ウィンドウの右上隅にある X をクリックするか、 Alt+F4を押して、「コネクター・ディスカバリー」ウィザードを終了します。
  9. 「 IBM App Connect Enterprise 」ツールキットで 「Square Request 」ノードの編集画面に戻る。
    「コネクター・ディスカバリー」ウィザード (ステップ 6) で設定したコネクター・プロパティーが、プロパティー・エディターの 「正方形の要求」 ノードに表示されるようになりました。 「基本」 タブには、ウィザードで設定した 「アクション」 プロパティーと 「オブジェクト」 プロパティーの値が表示されます。 たとえば、ウィザードで [顧客] > [顧客の取得] を選択した場合、そのノードの [基本] タブには以下のプロパティが表示されます：
    • 処置 - RETRIEVEALL
    • オブジェクト - customers

    処置 プロパティーおよび オブジェクト プロパティーの値は、読み取り専用形式で表示されます。 これらの値を変更するには、「コネクター・ディスカバリーの起動」を再度クリックし、「コネクター・ディスカバリー」ウィザードで新しい値を設定します。

    「スキーマ・ベース名」 プロパティーは、 「正方形」 コネクターとの間で送受信される要求メッセージおよび応答メッセージの形式を記述するスキーマ・ファイルのベース名を指定します。 スキーマ・ベース名は、ノードのディスカバリーを初めて実行したときに自動的に設定され、現在のフロー名とノード名に基づいています。 ディスカバリーを初めて実行する前にこのプロパティーを手動で設定した場合は、設定した値が使用されます。 ディスカバリー後にスキーマを名前変更する場合は、このプロパティーを編集して、プロジェクト内の名前変更されたスキーマで使用されるスキーマ・ベース名と一致するようにする必要があります。 ディスカバリー後にこのプロパティーを変更する場合は、一致するようにスキーマ名を変更するか、ディスカバリーを再実行する必要があります。

    「コネクター・ディスカバリー」ウィザードは、ディスカバリー中に選択されたアクションに応じて、要求スキーマと応答スキーマ、または応答スキーマのみのいずれかを生成します。 要求スキーマは、選択されたアクションおよびオブジェクトが要求メッセージを必要とする場合にのみ生成されます。 生成された要求スキーマは、要求メッセージの妥当性検査に使用されます。 アクションが RETRIEVE または DELETEの場合、コネクターによって返されるのは応答スキーマのみです。

    生成されたスキーマ・ファイルはプロジェクトに追加され、入力データまたは出力データを変換するために Mapping ノードで使用できます。 スキーマの完全なファイル名は、スキーマのベース名 ( gen/MyMessageFlow.Square_Requestなど) から派生し、接尾部に response.schema.json または request.schema.jsonが付きます。 「要求スキーマを開く」 または 「応答スキーマを開く」をクリックして、スキーマを開くことができます。

  10. 「正方形の要求」 ノードのプロパティー設定が正しいことを確認してから、メッセージ・フローを保存します。
  11. 「正方形の要求」 ノードの 「接続」 タブで、 「ポリシー」 プロパティーには、接続に使用されるセキュリティー ID の詳細を含むポリシーの名前が表示されます。 ポリシーのタイプは Squareです。
    詳細については、 Squareのポリシー をご覧ください。
  12. オプション: 「接続」 タブの 「タイムアウト」 プロパティーを設定して、ノードが 正方形 による操作の処理を待機する時間 (秒単位) を指定します。
  13. 「正方形の要求」 ノードの 「フィルター」 タブには、メッセージ・フローがデータを選択する方法を制御するプロパティーが含まれています。 これらのプロパティーの初期値は、「コネクター・ディスカバリー」ウィザードで 「正方形」 コネクターに設定されたプロパティー値から取得されます。これには、フィルター・オプション・プロパティーおよび指定された条件 (ステップ 6で説明) が含まれます。 その後、「コネクター・ディスカバリー」ウィザードに戻り、(例えば、新しい条件を追加して) プロパティーの値を変更すると、それらの更新はノード上のプロパティー・セットに反映されます。

    「フィルター・オプション」 プロパティーは、 「正方形の要求」 ノードの実行時にどのオブジェクトを操作するかを制御します。 「フィルター制限」 プロパティーは、取得する項目の最大数と、制限を超えた場合に実行するアクションを制御します。

    値を変更するには、 「フィルター・オプション」 セクションで変更する値の横にある 「編集」 をクリックし、 「フィルター制限」 セクションで設定したプロパティー値を変更します。

    プロパティー値は、実行時に 「正方形の要求」 ノードに渡されるメッセージの内容から解決される、テキスト値、ESQL 式、または XPATH 式のいずれかになります。

  14. 「要求」 タブで、 「データの場所」 プロパティーを設定して、 「正方形」に作成されるオブジェクト・データを含む、着信メッセージ・ツリー内の場所を指定します。 このデータは、 「正方形の要求」 ノードから 「正方形」に送信される要求を形成します。
  15. 「結果」 タブで、 「出力データの場所」 プロパティーを設定して、 「正方形」に作成されたレコードのデータを格納する出力メッセージ・ツリー内の場所を指定します。
  16. デフォルトでは、要求メッセージは、コネクターのディスカバリー中に生成された要求スキーマに照らして検証されます。 「正方形の要求」 ノードの 「検証」 プロパティーを使用して、要求の検証をオフにしたり、検証設定を変更したりすることができます。
  17. メッセージ・フローを 保存 します。