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

OpenAPI コネクターでは、ユニバーサルな接続を実現するだけでなく、Workato で表示されるユーザーインターフェイスをカスタマイズして、最適なユーザーエクスペリエンスを実現することも可能です。

このガイドでは、以下の方法について紹介します。

1. オブジェクト名とヒントのカスタマイズ
2. API 操作のアクションへの分類のカスタマイズ
3. アクションの入力項目の非表示
4. コネクターのアプリケーション名のカスタマイズ

---

ベストプラクティス

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

1

オブジェクトヒントが表示され、正確であることを確認してください。 情報へのアクセスを簡単にし、理解しやすくしておくと、ユーザーが速やかにコネクターを設定し、使い始めることが可能になります。

Swagger ファイルを直接編集することが可能であれば、必要に応じてオブジェクトヒントや外部リンクを追加してください。

2

カスタムコネクターを構築する場合は 、OpenAPI をアプリケーションの名前で置き換えてください。

3

テスト、テスト、テスト ! カスタムコネクターを作成する場合でも、標準の OpenAPI コネクターのインターフェイスをカスタマイズする場合でも、変更内容を繰り返しテストしましょう。変更を一度に1つずつテストすると、問題の特定が容易になります。

---

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

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

• オブジェクト名フィールドの選択
• オブジェクトヒントとリンクのカスタマイズ
• オブジェクト名とヒントに対する置換ルール
• 静的なオブジェクト名を使用した、オブジェクトと操作へのわかりやすい表示名の割り当て

エンドポイントの例

このページの例では、以下のエンドポイントを使用します。

/*  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
            }
         }
      }
   }
}

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

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

操作するオブジェクトのピックリスト

オブジェクト名は、オブジェクトの summary、description、または operationId フィールドから取得されます。コネクションの設定時、ユーザーはこれらのオプションのいずれかを [Object name] 項目で選択するように求められます。

コネクションの設定 : [Object name] 項目の選択

summary を選択すると、オブジェクト名は「Create a new pet」に基づくことになります (エンドポイントの例を参照)。a や and といった除外される単語が削除されると、得られるオブジェクト名は Pet になります。

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

ただし、この方法を取るよりも、Swagger ファイルを直接編集することの方が推奨されます。

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

オブジェクトヒント とは、オブジェクトピッカー項目の下に表示される短い説明です。

オブジェクトヒント

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

description を選択すると、オブジェクトヒントは「Add a new pet to the store. More information (opens new window)」になります (エンドポイントの例を参照)。

相対パスの使用

オブジェクト項目のヒントに含まれる外部リンクには、以下の2つの形式があります。

• 標準リンク。 これは完全な URL を含み、通常は [link text](url) という形式を取ります。例 : [Workato](https://www.workato.com)。このようなタイプのリンクはそのまま表示されるため、設定は必要ありません。
• カテゴリ別相対リンク。 [link text](key:path) という形式です。key はベース URL を参照し、path との組み合わせにより、完全な URL を形成します。以下に例を示します。
  • ベース URL: https://docs.swagger-store.io/docs/
  • パス: pets/statuses
  • 完全な URL: https://docs.swagger-store.io/docs/pets/statuses

ベース URL の追加

次の例では、「doc」という key を設定します。

/*  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."
  ...
}

ヘルプリンクを完成させるには、ベース URL (https://docs.swagger-store.io/docs/) を指定する必要があります。

Workato のコネクション項目 [External documentation links] を以下のように設定してください。

コネクションの設定 : External documentation links

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

ただし、この方法を取るよりも、Swagger ファイルを直接編集することの方が推奨されます。

置換ルールの使用

オブジェクト名やヒントから、つなぎの単語やキーワードを除いても、最適な結果が得られないことがあります。

たとえば、オブジェクト名に対処しようとしていて、抽出に summary フィールドを使用したいとします。このオブジェクトの summary は "Allows users to create a pet" です。

つなぎの単語とキーワードのみを除くと、結果は Allows users to pet となり、明らかに適切とは言えません。

つなぎの単語やキーワードが取り除かれる前に、[Object name substitutions] 項目と [Object hint substitutions] 項目を利用して、抽出される値を変更できます。

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

説明		値
入力	値はオブジェクトの summary フィールドから抽出されます	Allows users to create a pet
パターン	キャプチャーグループを使用して、Allows users to の後の文字を抽出します	Allows users to (.+)
置き換え	1番目のキャプチャーグループ ( (.+) ) の結果で値を置き換えます	\1
置換結果	置換ルールの適用後の値	Create a pet
最終結果	つなぎの単語 (a、theなど) や既知の単語 (例 : Create) を置換結果から取り除いた最終的なオブジェクト名	Pet

注

複数の置換ルールが存在する場合 :

• ルールは登場順に適用されます。
• 値は一致するすべての pattern ごとに置換されます。
• 後のルールは前のルールの結果を使用します。

加えて、一部のヒントには外部サイトへの相対リンクが含まれています。

静的なオブジェクト名

OpenAPI 仕様で個々の API エンドポイントにわかりやすい名前が付いていない場合は、静的なオブジェクト名を使用して、オブジェクトや操作の説明となる表示名をマッピングしてください。

こちらのエンドポイントの例に含まれる操作を再マッピングするには、「Create a new Pet」 ("operationID": "createPet") のための表示名を指定します。

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

---

API 操作の分類のカスタマイズ

• API 操作の割り当てについて
• デフォルトの API 操作分類ルール
• API 操作に対する置換ルール

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

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

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

一部の API 操作が表示されない

API 操作が想定どおりのアクションに含まれていない場合、 Execute operation アクションでその操作を探してください。

API 操作をマッチングさせることができない場合、コネクターはその操作をこの「フォールバック」アクションへと分類します。詳細については、下記の「デフォルトの API 操作分類ルール」セクションを参照してください。

分類ルールは、以下の2つの要素に基づいています。

• API 操作のサマリーと操作 ID に含まれるキーワード。 レシピアクションを作成するために Swagger ファイルを解析する際、コネクターは API 操作の summary フィールドおよび operationId フィールドに含まれるキーワードの有無もチェックします。コネクターはこれらのキーワードを使用して、操作をレシピアクションに割り当てます。

  たとえば、createPet という操作 ID の操作は、 Create record アクションに割り当てられます。これは、操作 ID に create という単語が含まれるためです。

• 操作の HTTP メソッド。 これは Swagger ファイル内で指定されています。HTTP メソッドは、特定のオブジェクトに対して操作が実行するアクションのタイプ (create (多くの場合は POST) や search (GET) など) を表現しています。

  たとえば、GET メソッドを使用する操作は、 Search records アクションまたは Get record details by ID アクションのいずれかに割り当てられます。

  この分類方法を無効にするには、コネクションの設定時に、 [Use HTTP method semantics for grouping operations] 項目を [No] に設定します。これは API が REST 規格に従っていない場合に有用です。たとえば、どのエンドポイントでも POST メソッドを使用している場合などです。

デフォルトの API 操作分類ルール

以下の表に、OpenAPI コネクターに対するデフォルトの操作分類ルールの詳細を示します。表の各列は以下のとおりです。

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

• 操作キーワード : コネクターが API 操作を分類するために使用するキーワード。API 操作の summary または operationId にこれらのキーワードが含まれる場合、その操作はレシピエディター内で当該アクションにマッピングされます。

  たとえば、summary または operationId に add または adds が含まれる場合、その API 操作は Create record アクションに割り当てられます。

• HTTP メソッド : [Use HTTP method semantics for grouping operations] オプションが有効になっている場合、コネクターはこのメソッドリストを当該アクションに対応付けます。

  たとえば、ある操作が POST メソッドを使用する場合、その操作は Create record アクションや Update record アクションに割り当てられます。

名前と説明	操作キーワード	HTTP メソッド
Create record 指定されたオブジェクトタイプの新しいレコードを作成します。たとえば、pet オブジェクトを選択すると、このアクションにより新しい pet レコードが作成されます。	create、creates update、updates post、posts add、adds upload、uploads new	POST、PUT
Update record 一意の識別子を使用して既存のレコードを更新します。	create、creates update、updates put、puts set、sets upload、uploads modify、modifies manipulate、manipulates	PUT、POST、PATCH
Search records 指定されたオブジェクトタイプのレコードを検索します。	return、returns find、finds list、lists (all) search、searches retrieves objects/records/all get(s) (a) collection (of) get list (of)	GET
Get record details by ID 一意の識別子を使用してレコードを取得します。	get、gets return、returns find、finds show、shows retrieve、retrieves single download、downloads getSingle get-single	GET
Delete record	delete、deletes remove、removes kill、kills	DELETE
Execute operation これは「フォールバック」アクションです。API 操作を特定のアクションにマッチングさせることができない場合、その操作はこのアクションに分類されます。		POST、PUT、GET、DELETE、PATCH

API 操作に対する置換ルール

Swagger ファイル内の操作 ID が createPet や searchPets のように単純ではない場合は、置換ルールを使用して、API 操作の分類を改善またはカスタマイズすることができます。

以下の表は、操作 ID operation-8452/pet-create が置換ルールによって create-pet に変換される流れを示しています。

説明		値
入力	値はオブジェクトの operationId フィールドから抽出されます	operation-8452/pet-create
パターン	キャプチャーグループを使用して、操作 ID のオブジェクト (object) である pet と 動詞 (verb) である create を抽出します	operation-8452/(?<object>.+)-(?<verb>.+)
置き換え	キャプチャーグループの結果で値を置き換えます	\2-\1
最終結果	置換ルール適用後の最終的な操作 ID です	create-pet

このコネクターは、create-pet という改善された操作 ID で、API 操作を Create record アクションに割り当てることが可能になりました。

注

複数の置換ルールが存在する場合 :

• ルールは登場順に適用されます。
• 値は一致するすべての pattern ごとに置換されます。
• 後のルールは前のルールの結果を使用します。

---

アクションの入力項目の無視

Workato のアクションには、その設定時に使用される入力項目があります。コネクションの設定時に [Ignore specific request fields] 項目を使用すると、無視する項目を指定することができます。無視される入力項目は、ユーザーがアクションを設定する際に非表示になります。

たとえば、あるエンドポイントに links という項目が含まれるとします。以下の設定を使用すると、この項目を無視することができます。

ドット表記を使用した項目パスを指定することにより、入れ子になった項目を無視することもできます。たとえば、links の url 項目を無視したい場合は、 [Field name] に links.url と入力します。

---

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

注

このセクションは、カスタム OpenAPI コネクターにのみ当てはまります。

デフォルトのソースコードでは、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 のようなテキストエディターの使用が必要になる場合があります。