OpenAPIデフォルトコネクションフィールドリファレンス ​

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

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

フィールドリファレンスドキュメント ​

OpenAPIコネクターの各コネクションフィールドには、このガイド内に独自のセクションがあります。 各セクションでは、次の情報を確認できます:

必須フィールド ​

コネクションフィールドはカスタマイズできますが、カスタムOpenAPIコネクターを正常に設定するには、次のフィールドがconnection.fieldsまたはadjust_connectionに存在する必要があります:

• 認証方法 (auth_method)
• Basic認証ユーザー (basic_auth_user) *
• Document content (definition_content) *
• OpenAPIドキュメントソース (definition_mode)
• ドキュメントURL (definition_url) *
• ヘッダー認可 (auth_headers) *
• OAuth2認可URL (authorization_url) *
• OAuth2トークンURL (token_url) *
• Client ID (client_id) *
• Client Secret (client_secret) *
• ユーザー名 (username) *
• パスワード (username) *
• クエリパラメーター認可 (query_params) *
• サーバーURL (base_url)

長いフィールドヒントを許可 ​

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

認証方法 ​

コネクションで使用する認証方法。 このフィールドの値によって、ユーザーが認証のために指定する必要がある他の値が決まります:

• none（他の入力は不要）
• basic（Basic認証ユーザーおよびBasic認証パスワードを参照）
• header（ヘッダー認可を参照）
• query（クエリパラメーター認可を参照）
• oauth2_client_credentials（OAuth2トークンURL、APIではトークンをリクエストするために認証情報をどのように送信する必要がありますか、Client ID、Client Secret、およびスコープを参照）
• oauth2_authorization_code（OAuth2認可URL、OAuth2トークンURL、APIではトークンをリクエストするために認証情報をどのように送信する必要がありますか、Client ID、Client Secret、およびスコープを参照）
• oauth2_resource_owner_password（OAuth2トークンURL、Client ID、Client Secret、ユーザー名、パスワード、およびスコープを参照）

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

Basic認証ユーザー ​

アプリケーションユーザー/アカウントの名前。

Basic認証パスワード ​

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

スキーマ深度制限 ​

入力スキーマと出力スキーマの説明に含めるネストされたフィールドの最大深度を定義します。

スキーマ再帰制限 ​

入力スキーマと出力スキーマの説明に含める再帰スキーマ定義の最大深度を定義します。

ドキュメント内容 ​

ドキュメントリンク ​

アプリケーションドキュメント、ユーザーガイド、または会社のWebサイトへのリンク。 このドキュメントリンクは、コネクターのトリガーまたはアクションのヘルプテキストに表示されます。

OpenAPIドキュメントソース ​

このフィールドの値によって、ユーザーが指定する必要がある他の値が決まります。 次のいずれかである必要があります:

• url（ドキュメントURLを参照）
• content（Document contentを参照）

ドキュメントURL ​

外部ドキュメントリンク ​

定義すると、オブジェクトフィールドの説明からAPIリファレンスやドキュメントなどの外部Webサイトにリンクできます。

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

APIエンドポイントをフィルター ​

エンドポイントをフィルターするルールを定義します。

サンプル ​

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

ヘッダー認可 ​

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

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

リクエストフィールドを無視 ​

コネクターが無視する特定のリクエストフィールドを定義します。

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

OAuth2認可URL ​

これは通常、接続先アプリのAPIドキュメントのAuthenticationセクションで公開されています。

OAuth2トークンURL ​

これは通常、接続先アプリのAPIドキュメントのAuthenticationセクションで公開されています。

OAuth2トークンリクエストモード ​

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

OAuth2クライアントID ​

Workatoに関連付けるOAuthアプリの公開ID。

これは通常、接続先としてログインしているアプリアカウントのSettingsまたはIntegrationsページ（または同等のページ）にあり、秘密にしておく必要があります。

OAuth2クライアントシークレット ​

アプリケーションがClient IDとともに検証する、一致する秘密キー。

これは通常、接続先としてログインしているアプリアカウントのSettingsまたはIntegrationsページ（または同等のページ）にあり、秘密にしておく必要があります。

OAuth2ユーザー ​

アプリケーションユーザー/アカウントの名前。

OAuth2パスワード ​

OAuth2スコープ ​

スコープは、アプリからリクエストできる権限です。

これは通常、接続したいログイン済みアプリアカウントのSettingsまたはIntegrationsページ（または同等の場所）にあります。

オブジェクトヒント ​

コネクターがオブジェクトヒントの表示に使用する、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ユーザーインターフェースのカスタマイズガイドを参照してください。

オブジェクトヒントの置換 ​

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

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

• pattern: キャプチャグループを含めることができる正規表現文字列。
• replacement: patternのすべての出現箇所を置換する文字列値。 この値には、patternの次のキャプチャグループへの後方参照を含めることができます:
  • \d形式。ここでdはグループ番号です。 例: \1
  • または\k。ここでnはグループ名です。 例: \object
  二重引用符で囲まれた文字列の場合、両方の後方参照の前に追加のバックスラッシュ（\）を付ける必要があります。 注: $&などの特殊な一致変数は、置換内の現在の一致を参照しません。

オブジェクト名 ​

コネクターがオブジェクト名の表示に使用する、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ユーザーインターフェースのカスタマイズガイドを参照してください。

オブジェクト名の置換 ​

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

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

• pattern: キャプチャグループを含めることができる正規表現文字列。
• replacement: patternのすべての出現箇所を置換する文字列値。 この値には、patternの次のキャプチャグループへの後方参照を含めることができます:
  • \d形式。ここでdはグループ番号です。 例: \1
  • または\k。ここでnはグループ名です。 例: \object
  二重引用符で囲まれた文字列の場合、両方の後方参照の前に追加のバックスラッシュ（\）を付ける必要があります。 注: $&などの特殊な一致変数は、置換内の現在の一致を参照しません。

グループ化の置換 ​

エンドポイントのグループ化オペレーションのテキストベース置換ルールを定義します。 組み込みのグループ化ルールがAPI構造の特定のニーズを満たさない場合に役立ちます。

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

オペレーション名フィールド ​

Execute API operationアクションのピックリストでオペレーション名に使用するフィールドを定義します。 デフォルトはオブジェクト名フィールドです。

クエリパラメーター認可 ​

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

例:
api_key: 1234567890
token: abc123

レコードIDフィールド名 ​

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

静的オブジェクト名 ​

オブジェクトとオペレーションのユーザーフレンドリーな名前のリストを定義します。

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

サンプル ​

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

サーバーURL ​

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

注: このフィールドの値をハードコードする場合、つまりエンドユーザーがコネクターの設定時に値を指定する必要がないようにする場合は、次の2つのメソッドでフィールドを指定する必要があります:

• adjust_connection:

  ruby

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

• base_uri:

  ruby

  base_uri: lambda do |connection|
    'https://petstore3.swagger.io/api/v3/'
  end

テストリクエストURL ​

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

HTTPメソッドセマンティクスを使用してグループ化 ​

HTTPメソッドをAPIオペレーションのグループ化に使用するかどうかを示します。

Swaggerファイル内のエンドポイントがRESTガイドラインに従っていない場合を除き、これを有効にする必要があります。