OpenAPIコネクタのユーザーインターフェイスのカスタマイズ ​

ユニバーサルコネクティビティに加えて、OpenAPIコネクタでは、最適なユーザーエクスペリエンスを実現するためにWorkatoでユーザーインターフェイスをカスタマイズすることもできます。

このガイドでは、次の方法について説明します。

1. オブジェクト名とヒントのカスタマイズ
2. API操作をアクションにグループ化する方法のカスタマイズ
3. アクション入力フィールドを非表示にする
4. コネクタのアプリケーション名のカスタマイズ

ベストプラクティス ​

OpenAPIコネクタのユーザーインターフェイスをカスタマイズする場合は、次のベストプラクティスに従うことをお勧めします。

オブジェクトのカスタマイズ ​

オブジェクトの詳細は、エンドポイントフィールドから自動的に抽出されます。 このセクションでは、次について説明します。

• オブジェクト名フィールドの選択
• オブジェクトヒントとリンクのカスタマイズ
• オブジェクト名とヒントの置換ルール
• 静的オブジェクト名を使用して、オブジェクトと操作にユーザーフレンドリーな表示名をマッピングする

エンドポイントの例 ​

この記事の例では、次のエンドポイントを使用します。

/*  swagger-petstore-1-1.json */

{
   "paths":{
      "/pet":{
         "post":{
            "tags":[
               "pet"
            ],
            "summary":"Create a new pet",
            "description":"Add a new pet to the store. [More information](https://app.swaggerhub.com/apis/Colon-Org/Swagger-PetStore-3.0/1.1)",
            "operationId":"createPet",
            "requestBody":{
               "description":"Add a new pet to the store",
               "content":{ ... },
               "required":true
            }
         }
      }
   }
}

オブジェクト名のカスタマイズ ​

オブジェクト名とは、petやuserなど、APIが操作するレコードのタイプを指します。 レシピエディタで、ユーザーはアクションが操作するオブジェクトのタイプを選択できます。

操作対象オブジェクトの選択リスト

オブジェクト名は、オブジェクトのsummary、description、またはoperationIdフィールドから派生します。 コネクションを設定するとき、ユーザーはObject nameフィールドでこれらのオプションのいずれかを選択するよう求められます。

コネクション設定: オブジェクト名フィールドの選択

summaryを選択した場合、オブジェクト名は_"Create a new pet"_に基づきます（エンドポイントの例を参照）。 除外された単語（aやandなど）が削除された後、結果のオブジェクト名はPetになります。

注: カスタムコネクタを開発している場合は、オブジェクト名フィールドをハードコードできます。 詳細については、OpenAPIコネクタを使用したカスタムコネクタの作成ガイドを参照してください。

ただし、代わりにSwaggerファイルを直接編集することをお勧めします。

オブジェクトヒントとリンクのカスタマイズ ​

オブジェクトヒントは、オブジェクトピッカーフィールドの下に表示される短い役立つ説明です。

オブジェクトヒント

デフォルトでは、ユーザーはオブジェクトのsummaryまたはdescriptionフィールドをオブジェクト名として使用できます。 コネクションを設定するとき、ユーザーはObject hintフィールドでこれらのオプションのいずれかを選択するよう求められます。

descriptionを選択した場合、オブジェクトヒントは_"Add a new pet to the store. 詳細情報"_になります（エンドポイントの例を参照）。

/*  swagger-petstore-1-1.json */

{
  ...
  "description":"Multiple status values can be provided with comma separated strings. See [documentation](doc:pets/statuses) for all possible statuses."
  ...
}

注: カスタムコネクタを開発している場合は、オブジェクトヒントフィールドをハードコードできます。 詳細については、OpenAPIコネクタを使用したカスタムコネクタの作成ガイドを参照してください。

ただし、代わりにSwaggerファイルを直接編集することをお勧めします。

置換ルールの使用 ​

場合によっては、オブジェクト名とヒントからフィラー語とキーワードを削除しても、最適な結果にならないことがあります。

オブジェクト名を扱っており、抽出にsummaryフィールドを使用するとします。 オブジェクトのsummaryは"Allows users to create a pet"です。

フィラー語とキーワードだけを削除すると、結果はAllows users to petになります。明らかに理想的な結果ではありません。

キーワードとフィラー語が削除される前に、オブジェクト名の置換フィールドとオブジェクトヒントの置換フィールドを使用して、抽出された値を変更できます。

次の表は、Allows users to create a petからAllows users to を取り除く置換ルールによって、最終結果がどのように改善されるかを示しています。

静的オブジェクト名 ​

OpenAPI仕様で個々のAPIエンドポイントにユーザーフレンドリーな名前が指定されていない場合は、静的オブジェクト名を使用して、各オブジェクトと操作にわかりやすい表示名をマッピングします。

エンドポイントの例の操作を再マッピングするために、"Create a new Pet"（"operationID": "createPet"）の表示名を指定します。

コネクション設定: 静的オブジェクト名の追加

API操作のグループ化のカスタマイズ ​

• API操作の割り当てについて
• デフォルトのAPI操作グループ化ルール
• API操作の置換ルール

API操作の割り当てについて ​

OpenAPIコネクタには、API操作をレシピアクションにグループ化するためのデフォルトルールセットが含まれています。 これらのルールは、アクションの設定時にオブジェクトピッカーに表示されるオブジェクトも制御します。

次の画像は、Swaggerファイルの2つのAPI操作がレシピエディタのアクションにどのようにマッピングされるかを示しています。

グループ化ルールは次の2つの要因に基づきます。

• API操作の概要と操作ID内のキーワード。 コネクタがSwaggerファイルを解析してレシピアクションを作成するとき、API操作のsummaryフィールドとoperationIdフィールド内のキーワードも確認します。 コネクタはこれらのキーワードを使用して、操作をレシピアクションに割り当てます。

  たとえば、操作IDがcreatePetの場合、その操作はレコードの作成アクションに割り当てられます。 これは、操作IDにcreateという単語が含まれているためです。

• 操作のHTTPメソッド。これはSwaggerファイルで指定されます。 HTTPメソッドは、create（通常はPOST）や検索（GET）など、特定のオブジェクトに対して操作が実行するアクションのタイプを表します。

  たとえば、GETメソッドを使用する操作は、レコードの検索またはIDによるレコード詳細の取得アクションのいずれかに割り当てられます。

  このグループ化方法を無効にするには、コネクションの設定時にUse HTTP method semantics for grouping operationsフィールドをNoに設定します。 これは、APIがREST標準に従っていない場合に役立ちます。 たとえば、すべてのエンドポイントがPOSTメソッドを使用している場合です。

デフォルトのAPI操作グループ化ルール ​

次の表では、OpenAPIコネクタのデフォルトの操作グループ化ルールについて詳しく説明します。 表の列は次のとおりです。

• 名前と説明: アクションの名前と説明

• 操作キーワード: コネクタがAPI操作のグループ化を実行するために使用するキーワード。 API操作のsummaryまたはoperationIdにこれらのキーワードが含まれている場合、レシピエディタでこのアクションにマッピングされます。

  例: summaryまたはoperationIdにaddまたはaddsが含まれている場合、API操作はレコードの作成アクションに割り当てられます。

• HTTPメソッド: Use HTTP method semantics for grouping operationsオプションが有効な場合、コネクタはメソッドリストをこのアクションに照合します。

  例: 操作がPOSTメソッドを使用する場合、レコードの作成およびレコードの更新アクションに割り当てられます。

API操作の置換ルール ​

Swaggerファイル内の操作IDがcreatePetやsearchPetsほど単純でない場合は、置換ルールを使用してAPI操作のグループ化を改善またはカスタマイズできます。

置換ルールの適用方法 ​

置換ルールは、グループ化ロジックの前に指定されたフィールドに適用されます。 フィールドに計画したグループ化と一致しない特定のパターンが含まれている場合は、それらを優先する用語または構造に置き換えるルールを作成できます。

API操作の詳細に置換ルールを適用

置換ルールを適用するには、Workatoで次のフィールドに入力します。

次の表は、置換ルールによって操作IDoperation-8452/pet-createがcreate-petにどのように変換されるかを示しています。

これで、コネクタは改善された操作IDcreate-petを使用して、API操作をレコードの作成アクションに割り当てることができます。

文字列置換 ​

文字列置換は、組み込みキーワードルールの適用より前に行われます。 これらの置換は、操作のsummary、operationId、description、pathを変更し、エンドポイント属性がアクションマッピングの想定キーワードと一致するようにします。

次の表では、文字列置換後のOpenAPIコネクタの操作グループ化ルールについて詳しく説明します。

New/updateトリガーの要件 ​

New/updateトリガーが関連するAPI操作を正しく識別するには、各操作が次の条件を満たす必要があります。

• レコード検索アクション条件を満たす: レコードの検索アクションに設定された要件に一致していること。
• タイムスタンプリクエストパラメータ: 通常update、change、modify、time、stamp、since、またはstartという名前のタイムスタンプリクエストパラメータを含むこと。
• レスポンス内のタイムスタンプ: レスポンスに最終更新時刻を記録するタイムスタンプフィールドが含まれていること。 一般的なフィールド名はupdate、change、create、modify、modified、time、またはstampです。
• レスポンス内の識別子: レスポンスに通常idまたはnameという名前の識別子フィールドが含まれていること。

HTTPメソッドベースのグループ化 ​

OpenAPIコネクタのuse_operation_names_for_grouping設定は、HTTPメソッドが操作のグループ化にどのように影響するかを決定します。

この設定が有効な場合、HTTPメソッドに基づいて次のルールが適用されます。

• レコードの作成アクション: HTTPメソッドがPOSTまたはPUTの場合、エンドポイントを割り当てます。
• レコードの更新アクション: HTTPメソッドがPOSTまたはPUTの場合、エンドポイントを割り当てます。
• レコードの削除アクション: HTTPメソッドがDELETEの場合、エンドポイントを割り当てます。
• レコードの検索アクション: HTTPメソッドがGETの場合、エンドポイントを割り当てます。
• IDによるレコード詳細の取得アクション: 操作がレコードの検索アクションの条件を満たさない場合に、HTTPメソッドがGETならエンドポイントを割り当てます。
• 操作の実行アクション: レコードの検索、レコードの作成、レコードの更新、IDによるレコード詳細の取得、またはレコードの削除アクションに適合しない場合、エンドポイントを割り当てます。
• New/updateトリガー: HTTPメソッドがGETの場合、エンドポイントを割り当てます。

この設定が無効な場合、操作のグループ化には次のルールが適用されます。

• レコードの更新アクション: エンドポイントがレコードの作成アクションに分類されていない場合にのみ使用できます。
• レコードの削除アクション: エンドポイントがレコードの作成またはレコードの更新アクションに分類されていない場合にのみ使用できます。
• レコードの検索アクション: エンドポイントがレコードの削除、レコードの作成、またはレコードの更新アクションに分類されていない場合にのみ使用できます。
• IDによるレコード詳細の取得アクション: エンドポイントがレコードの削除、レコードの検索、レコードの作成、またはレコードの更新アクションに分類されていない場合にのみ使用できます。
• 操作の実行アクション: レコードの検索、レコードの作成、レコードの更新、IDによるレコード詳細の取得、またはレコードの削除アクションに適合しないエンドポイントで使用できます。

APIエンドポイントのフィルタリング ​

このセクションでは、APIエンドポイントを効果的にフィルタリングする方法について説明します。

ルールのリスト ​

各ルールを設定してエンドポイントを表示または非表示にすることで、APIエンドポイントの可視性を管理するルールを定義できます。 これにより、表示されるエンドポイントを制御できます。

APIエンドポイントフィルタールールの表示と管理

ルールの定義方法 ​

フィルタリングルールを定義するには、Workatoで次のフィールドに入力します。

フィルタリングルールの詳細を定義

各エンドポイントが、包含または除外のために指定されたすべての条件を満たしていることを確認します。 システムはルール処理でANDロジックを適用します。

設定サンプル ​

{
  ...
  "advanced" => {
    "endpoint_filter_rules" => [
      {
        "type" => "include",
        "operation_id" => "createPet"
      },
      ...
    ]
  }
  ...
}

アクション入力フィールドの無視 ​

Workatoのアクションには、アクションを設定するために使用される入力フィールドが含まれています。 コネクションの設定時にIgnore specific request fieldsフィールドを使用して、無視するフィールドを指定できます。 無視された入力フィールドは、ユーザーがアクションを設定するときに表示されません。

たとえば、エンドポイントにlinksフィールドが含まれているとします。 次の設定を使用すると、このフィールドを無視できます。

ドット表記を使用してフィールドパスを指定することで、ネストされたフィールドも無視できます。 たとえば、linksに無視したいurlフィールドがある場合は、Field nameとしてlinks.urlを入力します。

アプリケーション名のカスタマイズ ​

デフォルトのソースコードでは、OpenAPIが複数の場所で使用されています。 カスタムコネクタを作成するときは、この値をアプリケーション名に置き換えることをお勧めします。

アプリケーション名の変更に加えて、他のテキスト要素を変更してユーザーエクスペリエンスを向上させることができます。 たとえば、viaをinに変更します。

create_recordアクションを使用した例を見てみましょう。 この場合、OpenAPIはアクションのサブタイトルで使用されます。

create_record: {
  title: 'Create record',
  subtitle: 'Create record via OpenAPI',
  description: lambda do |_input, picklist_label|
    record = picklist_label['object_for_create'] || 'record'
    "Create <span class='provider'>#{record}</span> " \
      'via <span class="provider">OpenAPI</span>'
  end,
  [...]

すると、レシピエディタでアクションは次のように表示されます。

アクションのサブタイトルに加えて、アプリケーション名をアプリケーションの名前に変更すると、レシピエディタの次のような複数の要素に影響する場合があります。

• オブジェクトフィールドヒント:

  

• レシピアクションの説明:

  

OpenAPIをアプリケーション名に置き換える作業を簡単にするには、ソースコードで大文字と小文字を区別する検索と置換を実行します。 注: このアクションを実行するには、Sublime Textのようなテキストエディターを使用する必要がある場合があります。