マイクロアプリ

統合の構成

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

エンドポイントの追加

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

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

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

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

  2. [データエンドポイントの設定] で、エンドポイント名を入力します。
  3. (オプション)必要に応じて、テンプレート変数を追加します。このフィールドは、HTTP要求定義内で使用される動的値を提供します。[テンプレート変数]を使用すると、次のいずれかの状況における元のエンドポイント定義の全パラメーターを上書きまたは変更できます:

    • アクション前またはアクション後の更新
    • アクション呼び出し
    • 増分同期

    たとえば、増分同期中にテンプレート変数の動的値を使用できます。

    テンプレート変数

    1. [変数の追加] を選択します。
    2. 新しい変数の名前を入力します。
    3. データ型]と [ソース] を選択します。選択したデータ型によって、ソースの選択肢が変わります。

      1. データ型 [DATETIME] でソースに [静的な値] を選択した場合は、を入力します。
      2. データ型が [DATETIME] でソースに [相対日付] を選択した場合は、期間を選択します。
    4. [構成] メニューを選択し、必要に応じて [Datetime][書式の種類] の詳細を入力します。
    5. [保存] を選択します。

    作成した新しい変数は、HTTP要求で使用できるようになります。変数を波ダッシュタグで挟んで入力すると、入力した変数が存在しない場合は、変数が存在しないという警告が表示されます。この変数にカーソルを合わせると、ポップアップから [変数の作成] を選択してこの変数を追加できます。

    注:

    テンプレート変数値は、標準のHTTPエンコード規則に従ってパーセントエンコーディングされます。 これを発生させたくない場合、または値が既にパーセントエンコーディングされていることがわかっている場合は、二重エンコーディングを防ぐために、通常の二重中括弧ではなく三重中括弧タグを使用する必要があります。たとえば、を}に変更します。

    テンプレート変数を構成したら、次に説明するように、要求メソッド、ページネーションの種類を定義し、[完全同期]セクションと [増分同期] セクションの両方についてサービスをテストする必要があります。

  4. 要求メソッドとURLを構成します。

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

    注:

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

  6. [ページネーションの種類] を選択します。選択する必要のあるページネーションの種類は、ターゲットアプリケーション統合の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バージョンを選択します。

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

  7. [パラメーターを指定してテスト] を選択して、エンドポイントが正しく構成されていることを確認します。テストするページ数を選択し、[サービスをテスト]を選択します。[完了] を選択してブレードを閉じます。
  8. (オプション)戻されたレコードの条件を定義する必要がある場合は、Pagination boundary を切り替えます。これは、ページネーションの種類が [ページ][オフセット] の場合にのみ存在し、ターゲットのSoR要件によって異なります。
  9. 読み込む最大ページ数の変数を設定します(デフォルトは1000で、範囲は1から100000)。この変数を使用して、必要に応じてSoRから戻されるレコードの量を制限します。この値は、エンドポイントごとに個別に構成できます。
  10. [テストサービス] を選択して、エンドポイントが正しく構成されていることを確認します。

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

スクリプト変換

スクリプト変換の設定の詳細については、「スクリプト変換」を参照してください。

データ構造の取得

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

  1. [テーブルの生成] を選択します。
  2. [APIから] または [JSONから] を選択します:
    • APIから - 定義されたエンドポイントから自動的にデータを取得します。
    • JSONから - 必要に応じてAPIを貼り付ける場合に「サンプルJSONから」を使用します。たとえば、応答を受け取っているが現在はAPIを呼び出すことができない場合などです。 (オプション)定義されたエンドポイントからの別のルートが必要な場合は、ルートパスを定義します。ルートパスは、JSONポインタ表記で定義する必要があります。
  3. [テーブルの生成] を選択します。
  4. プライマリキーを設定するには、[属性の編集] 鉛筆アイコンを選択し、プライマリキーとして使用される属性(たとえば、id)で [プライマリキー] を切り替えます。重要なことに、プライマリキー列にnull値を含めることはできません。データ型をTIMESTAMPに変更しないでください。

    注:

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

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

  6. 増分同期

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

    カスタムパラメーターが必要となるのは、ターゲットアプリケーションで必要とされる場合だけです。必要に応じて、ターゲットアプリケーション統合ドキュメントを参照してください。同期用のカスタム文字列を作成する場合は、角かっこで入力する必要があります。例:[updated >=] ‘YYY-MM-DD HHmm’。

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

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

    同期の設定

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

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

注:

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

API呼び出しの追加

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

次の手順を実行します:

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

    統合の編集メニュー

    統合ページが開きます。

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

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

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

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

注:

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

テーブルのマージ

子API呼び出しを構成するとき、以下のオプションのいずれかを選択することにより、子テーブルを親テーブルにマージできます:

親テーブルと子テーブルをマージしない場合は、[マージしない] を選択します。

[詳細としてマージ] を選択すると、レコードシステムからすべてのタスクと要求を要求の詳細とともに取得し、それらをマージします。以下は、親テーブルと子テーブルの場合の例です:

/request-list
{
“id”: 123,
“Title”: “Car”,
“Role”: “Order”,
“Category”: “Sales”
}

And:

/request-detail/123
{
“id”: 123,
“Title”: “Car”,
“Desc”: “Cabriolet”,
“Date”: “2020-01-01”
}

[詳細としてマージ] が選択されると、次の内容が返されます:

Id 役職 役割 カテゴリ 説明 日付
123 Car Order Sales Cabriolet 2020-01-01

[サブリストとしてマージ] を選択して各子テーブルを個別に親テーブルに追加します。上記の例を使用して、サブリストとしてマージすると、次のような結果になります:

Id 役職 役割 カテゴリ id 役職 説明 日付
123 Car Order Sales 123 Car Cabriolet 2020-01-01

テーブルの構成

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

サポートされる時刻形式

HTTP統合では、レコードシステムデータで次の時刻形式をサポートしています:

  • ISO日付形式
  • OData形式
  • "yyyy-M-dd HH:mm:ss.SSS",
  • "M/d/yy h:mm a",
  • "M/d/yyyy h:mm:ss a",
  • "dd/MM/yy HH:mm",
  • "MMM d, yyyy h:mm:ss a",
  • "dd-MMM-yyyy HH:mm:ss",
  • "MMMM d, yyyy h:mm:ss a",
  • "dd MMMM yyyy HH:mm:ss",
  • "EEEE, MMMM d, yyyy h:mm:ss a",
  • "EEEE, d MMMM yyyy HH:mm:ss 'o''clock'",
  • "h:mm a",
  • "HH:mm",
  • "h:mm:ss a",
  • "HH:mm:ss"

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

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

サービスアクションパラメーターとテンプレート変数を設定する場合、次の文字はサポートされません:

  • Whitespace ! " # % & ' ( ) * + , . / ; < = > @ [ \ ] ^ { | } ~ truefalseelsenullundefinedthis

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

  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 - 要求の本文に含められるパラメーターを定義します。

スクリプト変換

スクリプト変換の設定の詳細については、「スクリプト変換」を参照してください。

アクション実行前のデータ更新

(オプション)アクション実行前にデータ更新を構成して、マイクロアプリのエンドユーザーがアクションを実行するときにデータが完全に同期されるようにします。たとえば、アクション可能なマイクロアプリに表示される金額が承認する正しい金額であり、作成から承認までの間は更新されないようにするとします。

重要:

このアクション実行前のデータ更新機能は、テキストコンポーネントでのみ機能します。つまり、アクション実行前の他のデータ変更は、エンドユーザーに表示されません。同様に、テキストコンポーネントのページロジックに値が入力された場合、チェックは実行されません。Workspaceユーザーが同時に変更を行う場合、警告は表示されません。

実行前にデータ更新を設定するには、次の手順を実行します:

  1. 更新されたレコードを取得する既存の [データエンドポイント] を選択します。
  2. (オプション)更新されたレコードの完全な詳細を取得するために子データエンドポイントが必要な場合にのみ、[子エンドポイントを含める] を有効にします。
  3. (オプション)単一のレコードを取得する更新が許可される場合、通常の [エンドポイントURI] を拡張します。たとえば、データエンドポイントURI https://domain/api/itemshttps://domain/api/items/itemIdに更新できます。新しいエンドポイントURIが返すデータは、元のエンドポイントURIの場合と同じデータ構造である必要があります。そうしないと、データ解析が失敗します。

注:

この初期セットアップ後にエンドポイント設定が変更された場合、変更内容はここに自動的には反映されません。

  1. (オプション)単一レコードのフィルタリングが有効な場合、要求パラメーターを [追加のパラメーターを追加] で拡張します。
  1. [パラメーターを指定してテスト] を選択して、エンドポイントが正しく構成されていることを確認します。テストするページ数を選択し、[サービスをテスト]を選択します。[完了] を選択してブレードを閉じます。

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

構成が完了したら、[保存] を選択します。

アクション実行後のデータ更新

(オプション)アクションの実行後にデータが完全に同期されるようにするには、ターゲットアプリケーションのレコードシステムから新しいデータを取得するようにデータ更新を構成できます。

データ更新をアクション実行後に設定するには、次の手順を実行します:

  1. 更新されたレコードを取得する既存の [データエンドポイント] を選択します。
  2. (オプション)更新されたレコードの完全な詳細を取得するために子データエンドポイントが必要な場合にのみ、[子エンドポイントを含める] を有効にします。
  3. (オプション)単一のレコードを取得する更新が許可される場合、通常の [エンドポイントURI] を拡張します。たとえば、データエンドポイントURI https://domain/api/itemshttps://domain/api/items/itemIdに更新できます。新しいエンドポイントURIが返すデータは、元のエンドポイントURIの場合と同じデータ構造である必要があります。そうしないと、データ解析が失敗します。
  4. (オプション)単一レコードのフィルタリングが有効な場合、要求パラメーターを [追加のパラメーターを追加] で拡張します。

  5. [パラメーターを指定してテスト] を選択して、エンドポイントが正しく構成されていることを確認します。テストするページ数を選択し、[サービスをテスト]を選択します。[完了] を選択してブレードを閉じます。

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

構成が完了したら、[保存] を選択します。

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

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

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

カスタム関係の作成

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

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

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

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

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

重要:

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

データ同期の設定

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

同期ルール、スケジュールを満たさない同期、および拒否ルールの詳細については、「データの同期」を参照してください。

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

    データ同期の設定方法

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

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

      重要:

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

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

      重要:

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

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

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

注:

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

統合ログの表示

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

統合ログの検索方法

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

統合構成のエクスポート

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

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

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

次のステップ

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