OpenAPI のデフォルトのコネクション項目についてのリファレンス ​

OpenAPI コネクターを使用してカスタムコネクターを作成する場合、コネクションの設定時にエンドユーザーに表示される項目は、コネクターの作成者が制御します。

このガイドは、ユニバーサル OpenAPI コネクターのデフォルトのコネクション項目についてのリファレンスです。

項目リファレンスドキュメント ​

このガイドでは、OpenAPI コネクターの各コネクション項目に、それぞれ独自のセクションが割り当てられています。各セクションには次の情報が含まれています。

必須項目 ​

コネクション項目はカスタマイズ可能ですが、カスタム OpenAPI コネクターを正しく設定するには、connection.fields または adjust_connection に以下の項目が指定されている必要があります。

• Authentication ｍethod (auth_method)
• Basic auth user (basic_auth_user) *
• Document content (definition_content) *
• OpenAPI document source (definition_mode)
• Document URL (definition_url) *
• Header authorization (auth_headers) *
• OAuth2 authorization URL (authorization_url) *
• OAuth2 token URL (token_url) *
• Client ID (client_id) *
• Client Secret (client_secret) *
• Username (username) *
• Password (username) *
• Query param authorization (query_params) *
• Server URL (base_url)

* は、その項目が別の項目に依存していることを示しています。詳細については、その項目のドキュメントを参照してください。

Allow Long Field Hints ​

No に設定すると、オブジェクトヒントが1段落に切り詰められます。デフォルトは No です。

Authentication Method ​

コネクションが使用する認証方法です。 この項目の値により、認証のためにユーザーが指定する必要があるその他の値が決まります。

• none (その他の入力は不要)
• basic (Basic auth user および Basic auth password を参照)
• header (Header authorization を参照)
• query (Query param authorization を参照)
• oauth2_client_credentials (OAuth2 token URL、How does the API require credentials to be sent to request a token?、Client ID、Client Secret および Scopes を参照)
• oauth2_authorization_code (OAuth2 authorization URL、OAuth2 token URL、How does the API require credentials to be sent to request a token?、Client ID、Client Secret および Scopes を参照)
• oauth2_resource_owner_password (OAuth2 token URL、Client ID、Client Secret、Username、Password および Scopes を参照)

サポートされている認証方法の詳細については、「OpenAPI コネクターの認証」ガイドを参照してください。

Basic Auth User ​

アプリケーションのユーザー名またはアカウント名。

Basic Auth Password ​

ユーザーのパスワード。ユーザーパスワードの代わりに、アカウント設定から取得した API キーまたは API トークンを使用することもできます。

この情報は秘密にしておく必要があります。

Schema Depth Limit ​

入出力スキーマの記述に含まれる、入れ子になった項目の最大深度を定義します。

Schema Recursion Limit ​

入出力スキーマの記述に含まれる再帰的スキーマ定義の最大深度を定義します。

Document content ​

OpenAPI ドキュメントの内容です。フォーマットは JSON または YAML です。OpenAPI v2 および v3 をサポートします。

Documentation Links ​

アプリケーションドキュメント、ユーザーガイド、または企業 Web サイトへのリンクです。このドキュメントリンクは、コネクターのトリガーまたはアクションのヘルプテキストで提供されます。

OpenAPI Document Source ​

OpenAPI ドキュメントが、コネクターにどのように提供されるかを定義します。推奨されるのは、URL からロードする方法です。それ以外に、ファイル内容をコピーして貼り付ける方法もあります。

この項目の値により、ユーザーが指定する必要があるその他の値が決まります。以下のいずれかである必要があります。

• url (Document URL を参照)
• content (Document content を参照)

Document URL ​

この URL は、常にパブリックにアクセス可能である必要があります。将来的にドキュメント自体が変更された場合は、それが Workato レシピエディターに自動的に表示されます。このドキュメントは JSON 形式または YAML 形式である必要があります。OpenAPI v2 および v3 をサポートします。

External Documentation Links ​

これが定義されていると、オブジェクト項目の説明を、API リファレンスやドキュメントなどの外部 Web サイトにリンクさせることが可能になります。

詳細と例については、「OpenAPI ユーザーインターフェイスのカスタマイズ」ガイドを参照してください。

Filter API Endpoints ​

エンドポイントをフィルタリングするための規則を定義します。

サンプル ​

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

Header Authorization ​

API リクエストに追加するヘッダーのリストです。 通常のユーザー名とパスワード/API キーに加えてヘッダーを必要とするアプリケーションの場合、またはリクエスト内で送信されるヘッダーをカスタマイズしたい場合に使用します。ヘッダー認証は、生成済みのトークンの利用準備が整っている場合に使用できます。

例:
API-Key: 1234567890
X-API-Token: abc123

Ignore Request Fields ​

コネクターで無視すべき特定の要求項目を定義します。

詳細と例については、「OpenAPI ユーザーインターフェイスのカスタマイズ」ガイドを参照してください。

OAuth2 Authorization URL ​

[Connect] ボタンをクリックしたときに Workato がユーザーをリダイレクトする URL。これにより、多くの場合は接続先アプリのログイン画面が表示されます。

この情報は、接続先アプリの API ドキュメントの「認証」セクションなどで公開されているものです。

OAuth2 Token URL ​

Workato が認証トークンを取得する URL。この認証トークンは、アプリとそのデータへのアクセス権限を証明するために使用されます。

この情報は、接続先アプリの API ドキュメントの「認証」セクションなどで公開されているものです。

OAuth2 Token Request Mode ​

クライアント ID とシークレットをトークンリクエストの本文で送信するか、それとも base64 エンコードした文字列としてヘッダー内で送信するかを指定します。

OAuth2 Client ID ​

Workato に関連付けられている、OAuth アプリの公開 ID です。

これはたいてい、接続先アプリのアカウントの [設定] や [統合] (またはそれと同等の) ページにあり、秘密にしておくべきものです。

OAuth2 Client Secret ​

接続先アプリケーションがクライアント ID と併せて検証する、対応する秘密鍵です。

これはたいてい、接続先アプリのアカウントの [設定] や [統合] (またはそれと同等の) ページにあり、秘密にしておくべきものです。

OAuth2 User ​

アプリケーションのユーザー名またはアカウント名。

OAuth2 Password ​

ユーザーのパスワード。ユーザーパスワードの代わりに、アカウント設定から取得した API キーまたは API トークンを使用することもできます。

OAuth2 Scopes ​

スコープとは接続先アプリにリクエストできる権限です。

これはたいてい、接続先アプリのアカウントの [設定] や [統合] (またはそれと同等の) ページで見つかります。

Object Hint ​

コネクターでオブジェクトヒントの表示に使用すべき、OpenAPI ドキュメント内のフィールドを定義します。

デフォルトの実装では、ユーザーは summary フィールドと description フィールドのいずれかを選択できます。

サンプル OpenAPI ドキュメントに含まれる、以下のオブジェクトを例に取ります。

• summary の場合は、オブジェクトヒントとして Update an existing pet が使用されます。
• description の場合は、オブジェクトヒントとして Update an existing pet by Id が使用されます。

{
   "paths":{
      "/pet":{
         "put":{
            "tags":[
               "pet"
            ],
            "summary":"Update an existing pet",
            "description":"Update an existing pet by Id",
            "operationId":"updatePet",
            "requestBody":{
               "description":"Update an existent pet in the store",
               "content":{ ... },
               "required":true
            }
         }
      }
   }
}

詳細と例については、「OpenAPI ユーザーインターフェイスのカスタマイズ」ガイドを参照してください。

Object Hint Substitutions ​

オブジェクトヒントに対する置換リストを定義します。オブジェクトヒントフィールドの値を変更し、オブジェクトピッカーのユーザーエクスペリエンスを向上させるために有用です。

置換オブジェクトには以下のプロパティが含まれます。

• pattern: 正規表現文字列。オプションとして、キャプチャーグループが含まれることもあります。
• replacement: pattern の出現箇所すべてを置き換える文字列値。この値には、pattern の以下のキャプチャーグループに対する後方参照が含まれる場合もあります。
  • \d 形式。ここで、d はグループ番号を表します。例 : \1
  • \k。ここで、n はグループ名を表します。例 : \object
  二重引用符で囲まれた文字列の場合は、どちらの後方参照の前にも追加のバックスラッシュ (\) を挿入する必要があります。注 : $& などの特別なマッチング変数は、置き換えにおける現在のマッチを参照しません。

Object Name ​

コネクターでオブジェクト名の表示に使用すべき、OpenAPI ドキュメント内のフィールドを定義します。

デフォルトの実装では、ユーザーは summary フィールドと operation_id フィールドのいずれかを選択できます。

サンプル OpenAPI ドキュメントに含まれる、以下のオブジェクトを例に取ります。

• summary の場合は、オブジェクト名として Update an existing pet が使用されます。
• operation_id の場合は、オブジェクト名として updatePet が使用されます。

{
   "paths":{
      "/pet":{
         "put":{
            "tags":[
               "pet"
            ],
            "summary":"Update an existing pet",
            "description":"Update an existing pet by Id",
            "operationId":"updatePet",
            "requestBody":{
               "description":"Update an existent pet in the store",
               "content":{ ... },
               "required":true
            }
         }
      }
   }
}

詳細と例については、「OpenAPI ユーザーインターフェイスのカスタマイズ」ガイドを参照してください。

Object Name Substitutions ​

オブジェクト名に対する置換リストを定義します。オブジェクト名の値を変更し、オブジェクトピッカーのユーザーエクスペリエンスを向上させるために有用です。

置換オブジェクトには以下のプロパティが含まれます。

• pattern: 正規表現文字列。オプションとして、キャプチャーグループが含まれることもあります。
• replacement: pattern の出現箇所すべてを置き換える文字列値。この値には、pattern の以下のキャプチャーグループに対する後方参照が含まれる場合もあります。
  • \d 形式。ここで、d はグループ番号を表します。例 : \1
  • \k。ここで、n はグループ名を表します。例 : \object
  二重引用符で囲まれた文字列の場合は、どちらの後方参照の前にも追加のバックスラッシュ (\) を挿入する必要があります。注 : $& などの特別なマッチング変数は、置き換えにおける現在のマッチを参照しません。

Operation ID Substitutions For Grouping ​

エンドポイント操作を分類するためのルールを定義します。

詳細と例については、「OpenAPI ユーザーインターフェイスのカスタマイズ」ガイドを参照してください。

Operation Name Field ​

Execute API operation アクションのピックリスト内の操作名に使用するフィールドを定義します。デフォルトは object name field です。

Query Param Authorization ​

API リクエストに追加するクエリーパラメータのリストです。

例:
api_key: 1234567890
token: abc123

Record ID Field Name ​

オブジェクトの一意の ID 値を格納するフィールドの名前を定義します。

Static Object Names ​

オブジェクトと操作のわかりやすい名前のリストを定義します。

詳細と例については、「OpenAPI ユーザーインターフェイスのカスタマイズ」ガイドを参照してください。

サンプル ​

{
  ...
  "advanced" => {
    "object_label_map" => [
      { 
        "operation_id" => "createPet", 
        "label" => "Create a new Pet"
      },
      ...
    ]
  }
  ...
}

Server URL ​

ターゲットホストまたはサービスの URL です。OpenAPI ドキュメントからの相対エンドポイントパスがこの URL に追加され、完全なエンドポイント URL が作成されます。

注 : この項目の値をハードコードする場合、つまりエンドユーザーがコネクターの設定時にこの値を指定せずに済むようにする場合は、以下の2つのメソッドで項目を指定する必要があります。

• adjust_connection:

  ruby

  methods: {
       adjust_connection: lambda do |connection|
         connection.merge(
           {
             'definition_mode' => 'url',
             'definition_url' => 'http://calendly.github.io/redoc/openapi.yaml',
             'base_url' => 'https://petstore.swagger.io/v2/',
             'documentation_href' => 'http://redocly.github.io/redoc'
           }
         )
       end
     [ ... ]
  }

• base_uri:

  ruby

  base_uri: lambda do |connection|
     'https://petstore.swagger.io/v2/'
  end

Test Request URL ​

コネクターが接続をテストするために使用する、API エンドポイントの相対パスです。

Use HTTP Method Semantics For Grouping ​

HTTP メソッドを API 操作のグループ化に使用すべきかどうかを示します。

Swagger ファイル内のエンドポイントが RESTガイドラインに従っていない場合以外は、このフィールドは有効にすべきです。