統合の構成

HTTP統合を追加したので、ここで統合を構成します。このエンドポイントデータとサービスアクション構成は、実用的なマイクロアプリを作成するための基盤を形成します。

エンドポイントの追加

関連するデータをキャッシュに読み込むように、データエンドポイントを構成します。ユーザーに表示する(またはイベントやアクションのトリガーに使用する)データはキャッシュする必要があります。

データエンドポイントを追加するには、以下の手順に従います:

  1. [データの読み込み] を選択します。

    新しいエンドポイントの追加

  2. [エンドポイント名] および [エンドポイントURI] を入力します。

  3. [要求メソッド] を設定します。

  4. (オプション)必要に応じて [+パラメーターを追加] を選択し、[PATH][QUERY]、または [HEADER] の各パラメーターを設定します。

    注:

    選択するデータの種類によって、属性の形式が決定されます。この形式によってマイクロアプリのフィールドが決定されます。 パラメーター名を参照するには、波ダッシュタグを使用します。たとえば、のようになります。

  5. [ページネーションの種類] を選択します。

    選択する必要のあるページネーションの種類は、ターゲットアプリケーション統合のAPI標準によって決まります。ターゲットアプリケーション統合のAPIドキュメントを参照して、アプリケーション統合で使用されるページネーション方法を確認してください。HTTP統合では、次の標準的なページネーション方法から選択できます。

    • なし - ページネーションは定義されません。
    • ページ - ページごとに復帰の限度を設定します。

      例: https://example.com?limit=100&page=3

    • オフセット - offsetとLimitの2つのパラメーターを指定します。offsetはスキップするレコードの数を定義し、ページごとに表示するレコードの数を制限します。

      例: https://example.com?limit=100&offset=300

    • リンク - ページネーション方法を定義して、本文の次のページリンクを定義します。

      例:

      {
      “data” […]
      “next”: https://example.com?lpage=3
      }
      
    • ヘッダーリンク - リンクページネーションと似ていますが、URLページヘッダーに基づいてページネーションを定義します。

      例:

      Link: <https://api.github.com/search/code?q=addClass+user%3Amozilla&page=15>; rel="next",
      <https://api.github.com/search/code?q=addClass+user%3Amozilla&page=34>; rel="last"
      
    • カーソル - カーソルのページネーションでは、特定レコードの一意の識別子がクエリする次のレコードへのポインタとして使用され、結果のページを返します。

      例: https://example.com?paginationToken=BFLMPSVZ

    • OData - OData標準のページネーションを実行する場合は、ODataバージョンを選択します。

      エンドポイントのページネーションの種類の設定

  6. [テストサービス] を選択して、エンドポイントが正しく構成されていることを確認します。

    テストが成功したら、次の手順に進みます。エラーメッセージを受け取った場合は、受け取ったエラーメッセージに基づいてトラブルシューティングを行います。

データ構造の取得

[データ構造の取得] セクションでテーブルを作成できるようになりました。

  1. [データ構造の取得] セクションで、作成するテーブルのベース名を入力して、以下のいずれかを選択します:
    • APIから - 定義されたエンドポイントから自動的にデータを取得します。
    • サンプルJSONから - 必要に応じてAPIを貼り付ける場合に「サンプルJSONから」を使用します。たとえば、応答を受け取っているが現在はAPIを呼び出すことができない場合などです。

    同期の設定

  2. プライマリキーを設定するには、[属性の編集] 鉛筆アイコンを選択し、プライマリキーとして使用される属性(たとえば、id)で [プライマリキー] を切り替えます。重要なことに、プライマリキー列にnull値を含めることはできません。データの種類をTIMESTAMPに変更しないでください。

    注:

    カスタマイズされた統合およびマイクロアプリを作成する場合は、必ずプライマリキーを割り当てる必要があり、データを同期するときに完全に上書きするのではなく、正しい増分の読み込みを有効にします。

  3. (オプション)[テーブルの追加] を選択して、該当のターゲットアプリケーションで必要な追加のテーブルプロパティを構成して、[保存] をクリックします。その後、APIエンドポイントからテーブル構造を再ロードできます。

  4. 増分同期

    増分同期を切り替えて同期をセットアップできます。つまり、前回のデータ同期以降に更新されたレコードのみを、より頻繁にダウンロードします。これを行うには、API呼び出しを実行する頻度を設定します。サーバー時間パラメーターを最低1つ入力します。同期スケジュールを設定せずに終了すると、手動で同期を行うよう設定されます。

    カスタムパラメーターが必要となるのは、ターゲットアプリケーションで必要とされる場合だけです。必要に応じて、ターゲットアプリケーション統合ドキュメントを参照してください。

    同期については詳しくは、以下の「データ同期の設定」を参照してください。

  5. [データ構造の取得] セクションで、作成するテーブルのベース名を入力して、以下のいずれかを選択します:
    • APIから - 定義されたエンドポイントから自動的にデータを取得します。
    • サンプルJSONから - 必要に応じてAPIを貼り付けるために、サンプルJSONからの利用は、たとえば次の応答を持っているが、現在はAPIを呼び出すことはできません。

    同期の設定

  6. [追加] を選択します。

データエンドポイントがマップされ、サービスアクションをセットアップできるようになりました。

注:

エンドポイントをセットアップして追加すると、テーブル構造がロックされます。再構築する必要がある場合は、新しくデータ読み込みのエンドポイントを作成して構成する必要があります。

API呼び出しを追加する

アプリケーション統合用のデータエンドポイントを構成する場合、元の親エンドポイントにさらに子エンドポイントを追加して、コールチェーンを有効にすることができます。データエンドポイントを設定したら、さらに関連するエンドポイントを追加できます。

次の手順を実行します:

  1. 子呼び出しを追加する統合のメニューで [編集] を選択します。

    統合の編集メニュー

    統合ページが開きます。

  2. 追加するデータエンドポイントメニューから [子API呼び出しを追加] を選択します:

    子API呼び出しを追加のメニュー

  3. 親テーブルを選択し、前述のデータの読み込みセクションの手順で行ったようにエンドポイントを定義します。

要求メソッドを定義するときに、パスを静的な値または列の値に設定できます。 これで、API呼び出しチェーンが親API呼び出しに関連付けられました。定義した親/子エンドポイントが[データエンドポイント]ページで視覚化されるようになりました。

注:

統合を作成する際には、複数ではなく1つのエンドポイントのみからデータをロードすることをお勧めします。可能な場合、エンドポイント呼び出しを個別に呼び出すバッチを使用してください。

テーブルの構成

構成を新たにセットアップせずに、テーブルのプライマリキーを再構成できるようになりました。この処理を行うには、テーブルの画面で個別のテーブルエントリを削除し、新しいプライマリキーを選択してテーブルを再同期します。

サービスアクションの追加

HTTP統合を構成したら、サービスアクションを構成できます。サービスアクションを使用して、アプリケーション統合のレコードのシステムにライトバックアクションを設定します。上記のデータエンドポイントと同様の方法でサービスアクションを設定します。アプリケーション統合は、任意の数のカスタマイズされた組み合わせになる可能性があるため、サービスアクションの仕組みを説明する一般的なアプローチを採用します。

サービスアクションを追加するには、以下の手順に従います:

  1. [アプリケーション名] で、作成した統合を選択します。
  2. [サービスアクション] および [新しいサービスアクションを追加] を選択します。
  3. これにアクション名を付けて(JIRAチケット情報の取得など)、エンドポイントURIのパスを入力します:(/rest/api/2/issue/)
  4. アプリケーション統合のAPI要件に基づいて、[要求メソッド]を設定します。

    注:

    パラメーター名を参照するには、波ダッシュタグを使用します。たとえば、のようになります。

  5. [追加] を選択してサービスアクションを保存します。必要に応じてさらにサービスアクションを追加できるようになりました。

API要求メソッド

アプリケーション統合APIの要件に基づいて、要求メソッドを構成できます。次のコンポーネントを使用します:

  • GET - アプリケーション統合SORからリソースを取得し、変更しません。
  • POST - アプリケーション統合SORに新しいリソースを作成します。
  • PUT - アプリケーション統合の既存のリソースを更新します。
  • PATCH - リソースを部分的に更新します。
  • DELETE - リソースを削除します。

構成可能な次のAPIパラメーターを使用します:

  • Header - 要求ヘッダーに含められるパラメーターを定義します。通常は承認に関連します。
  • Path - クエリ文字列の前にある、エンドポイントのパス内にパラメーターを定義します。
  • Query - エンドポイントのクエリ文字列にパラメーターを定義します。
  • Body - 要求の本文に含められるパラメーターを定義します。

必要なエンティティの確認

テーブルを使用して、キャッシュに保存されているテーブルおよびそれらのテーブルに適用されるフィルターの現在のリストを確認します。

これで、カスタム関係を作成する必要がない限り、最初のデータ同期を設定して実行する準備ができました。詳しくは、「データ同期の設定」を参照してください。

カスタム関係の作成

[関係] ページを使用して、統合内のテーブル間にカスタム接続を作成します。複数のベースURLがあり、複数の統合が必要な場合、または同じ統合でカスタム関係を作成する場合に、これを使用できます。これは高度なユースケースであり、複数の統合のマップを開始する前に、単一の統合でのマイクロアプリ作成に慣れるようお勧めします。

  1. [マイクロアプリの管理]ページから、エンティティを確認する統合の横にあるメニューを選択します。
  2. [編集] を選択してから [関係] を選択します。
  3. [新しい関係を追加] を選択します。

    [関係の追加]ページが開きます。

  4. プライマリテーブルを外部テーブルにマップできます。
  5. 必要なエイリアスを入力します。

各統合でセットアップしたプライマリキーに基づいて、参照列をマップして追加できるようになりました。

重要:

テーブルを削除すると、関係もすべて削除されます。

データ同期の設定

統合アプリケーションからマイクロアプリプラットフォームにデータをプルして、キャッシュと比較できるようにします。ベストプラクティスとして、完全同期が24時間ごとに実行され、増分同期は5分ごとにプルするように構成できます。

  1. [マイクロアプリの管理]ページから、同期を設定する統合の横にあるメニューを選択します。
  2. [同期] を選択します。

    データ同期の設定方法

  3. [完全] および [増分] のデータ同期の値を設定します。

    • [完全] は、ローカルキャッシュをドロップし、ソースシステムからすべてのデータをプルします。

      重要:

      完全同期の実行には時間がかかる場合があります。完全同期は、夜間または一般的には営業時間外に実行することをお勧めします。[X] アイコンを選択すると、処理中のデータ同期をいつでもキャンセルできます。

    • [増分] は、変更(新規および更新)されたレコードのみをプルします。削除されたデータは読み込まれません。

      重要:

      すべてのAPIが増分同期をサポートしているわけではありません。

      毎日または毎週の同期を指定すると、同期は選択した時間枠内でランダムに発生します。たとえば、「00-04 毎日」の完全同期を選択すると、この期間中にランダムに選択された時間に完全な同期を実行します。

  4. [保存] を選択します。

注:

必要に応じて、矢印アイコンを選択してオンデマンドで統合を実行することもできます。

統合ログの表示

[統合ログ] を使用して、重大度別に分類された変更の履歴を表示します。これを使用して、統合に関する問題のトラブルシューティングを行います。たとえば、同期が失敗したことがわかった場合は、統合ログをチェックして理由を確認します。または、予想されるカードが表示されない場合は、統合ログをチェックして、同期が発生したかどうかを確認します。

統合ログの検索方法

  1. [マイクロアプリの管理]ページから、統合ログを表示する統合の横のメニューを選択します。
  2. [統合ログ] を選択します。
  3. エントリを確認し、必要に応じてメニューを選択してエラーでフィルタリングします。

統合構成のエクスポート

統合構成をエクスポートできます。すべての資格情報が破棄されます。これには、パスワードとクライアントの詳細が含まれます。マイクロアプリサーバーに保存されている構成のみがエクスポートされます。たとえば、エクスポートでユーザー名は保持されますが、パスワードは保持されません。また、エクスポートでOAuth構成は保持されますが、クライアントシークレットは保持されません。

  1. [マイクロアプリの管理]ページから、エクスポートする統合の横にあるメニューを選択します。
  2. [構成のエクスポート] を選択します。

    service.mappファイルがダウンロードされます。

次のステップ

カスタム統合を作成して構成したので、自身のマイクロアプリを構築して、ユーザーのニーズを満たし、毎日のワークフローを合理化する最高のエンドユーザーエクスペリエンスを実現します。詳しくは、「マイクロアプリのカスタマイズ」を参照してください。