OpenAPIコネクターを使用したカスタムコネクターの作成 ​

アプリケーション固有のコネクターにより、完全な柔軟性と最高のユーザーエクスペリエンスが得られます。 ただし、コネクターをゼロから構築するには長い時間がかかる場合があります。 コネクター構築にかかる時間を短縮するには、OpenAPIコネクターをアプリケーションコネクター作成の基盤またはテンプレートとして使用します。

変換後、新しいアプリケーション固有のコネクターは、汎用OpenAPIコネクターの代わりにWorkatoレシピで使用できます。

この方法が適しているかどうかわからない場合 ほとんどの場合、OpenAPIコネクターはそのまま使用できます。 ただし、カスタムコネクターの作成が必要になる状況もあります。 例:

• コネクター名またはアイコンのカスタマイズ
• カスタム認証フローの実装
• アプリ固有のコネクション項目の追加
• コネクション設定の簡略化

上記のいずれかに該当する場合は、カスタムコネクターの作成が最適な方法である可能性があります。

前提条件 ​

OpenAPIコネクションを設定するには、次が必要です。

• Workato Connector SDKに精通していること。詳細については、SDKドキュメントを参照してください。

• 次の操作を許可するWorkatoの権限:

  • コネクションの作成
  • SDKコネクターの作成と変更

• 次の条件を満たすSwaggerファイル:

  • OpenAPI v2またはv3の仕様に準拠している
  • 有効なJSONまたはYAMLである

ステップ1: コネクターのインストール ​

最初のステップは、Workatoアカウントにコネクターをインストールすることです。 すでに完了している場合は、ステップ2に進みます。

ステップ2: Workatoで新しいSDKコネクターを作成する ​

• ステップ2.1: OpenAPIコネクターのソースコードをコピーする
• ステップ2.2: SDKコネクターを作成する

ステップ2.1: OpenAPIコネクターのソースコードをコピーする ​

ステップ2.2: SDKコネクターを作成する ​

ステップ3: コネクターの設定のカスタマイズ ​

このステップでは、コネクターのコネクション設定を変更する方法について説明します。 これを行う方法は2つあります。

• カスタム項目を追加する、またはデフォルトのコネクション項目を変更する。
• コネクション値をハードコードする。この方法は、ユーザーのコネクション設定を簡略化する場合に便利です。 例: ユーザーにOpenAPIドキュメントへのリンクを指定してもらう代わりに、ハードコードできます。

コネクション項目の詳細については、OpenAPIのデフォルトコネクション項目リファレンスを参照してください。

コネクション項目の追加と変更 ​

コネクション項目を追加または変更するには、connection.fieldsリストを見つけます。 Workatoはこのリストを使用して、コネクションのユーザーインターフェースを生成します。

デフォルトでは、WorkatoはこのリストにOpenAPI document source、Document URLなどの項目を入力します。 項目を表示したくない場合は、リストから削除するか、ユーザーが指定する必要がないようにその値をハードコードできます。

例: アプリケーションで認証にAPIキーのみが必要な場合。 すべてのデフォルト項目を削除し、ユーザーにAPIキーの入力を求める単一のapi_key項目を追加できます。

connection: {
  fields: [
    {
      name: 'api_key',
      label: 'API key',
      hint: 'Refer to <a href="<YOUR_DOC_URL>"><APP> docs</a> ' \
            'for help retrieving your API key.',
      optional: false,
      control_type: 'password'
    }
  ]
}

コネクション値のハードコード ​

ユーザーのコネクション設定を簡略化するために、コネクション値をハードコードできます。 これにより、ユーザーに代わって必要なコネクション値を指定することで、設定手順を1つ省略できます。

認証関連の項目を除き、コネクション値はadjust_connectionメソッドでハードコードできます。 このメソッドはソースコード全体の他のメソッドから呼び出され、コネクターの動作に影響します。 このメソッドに変更を加えると、そのメソッドが呼び出されるすべての場所に適用されます。

次の規則を使用して、adjust_connectionに項目を追加します。 <FIELD_NAME>を項目のnameに、valueをそのハードコードされた値に置き換えます。

methods: {
  adjust_connection: lambda do |connection|
    connection.merge (
      {
        '<FIELD_NAME>' => '<VALUE>',
        '<FIELD_NAME>' => '<VALUE>'
      }
    )
  end,
  [...]
}

例: 前のセクションでは、すべてのデフォルトのコネクション項目をconnection.fieldsから削除しました。 コネクターを正常に設定するには、これらの項目値をadjust_connectionでハードコードする必要があります。

上記の例では、既存のコネクション項目をconnection.fieldsから削除しました。 コネクターを正常に設定するには、adjust_connectionで項目をハードコードする必要があります。

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/',
        'advanced' => {
          'test_endpoint' => '/pet/findByStatus?status=%3D%5B%22available%22%5D',
          'documentation_href' => 'https://redocly.github.io/redoc/?url=https://petstore3.swagger.io/api/v3/openapi.yaml'
        }
      }
    )
  end,
  [...]
}

名前や説明など、項目の詳細については、OpenAPIコネクション項目リファレンスを参照してください。

注: 必須項目はconnection.fieldsに存在するか、adjust_connectionでハードコードされている必要があります。

ステップ4: 認証の実装 ​

認証項目がカスタマイズされている場合、またはカスタム認証フローが必要な場合は、ソースコードのauthorizationセクションを変更する必要があります。

変更が必要な具体的なメソッドは、要件と使用する認証方法によって異なります。 詳細については、SDK Authorizationリファレンスを参照してください。

例: ステップ3では、デフォルトのコネクション項目を単一のapi_key項目に置き換えました。 この場合、カスタム認証フローを正しく設定するには、authorization.applyメソッドを更新する必要があります。

実装を処理する方法は2つあり、それぞれに利点があります。

• コードをほぼそのまま維持し、コネクション変数のみを更新します。****注: 元のコードを維持すると、ソースコードのアップグレードを適用しやすくなります。

  例を表示

  ruby

  authorization: {
    type: 'custom_auth',
    apply: lambda do |connection|
      connection = connection.merge(
        {
          'auth_method' => 'header',
          'auth_headers' => "api_key: Bearer #{connection['api_key']}",
        }
      )
      auth_method = connection['auth_method']
      # don't apply any credentials when requesting the API definition
      if connection['definition_mode'] == 'url' &&
         current_url == connection['definition_url']
        auth_method = nil
      end
      case auth_method
      when 'none'
        # nothing to do
      when 'basic'
        username = connection['basic_auth_user']
        password = connection['basic_auth_password']
        encoded = "#{username}:#{password}".encode_base64
        headers(Authorization: "Basic #{encoded}")
      when 'header'
        auth_headers_input = connection['auth_headers']
        lines = auth_headers_input.split(/\n+|\r+/)
        headers_hash = {}
        lines.each do |header|
          next if header.blank?
  
          header = header.split(':', 2)
          header_name = header[0]
          header_value = header[1].strip
          headers_hash[header_name] = header_value
        end
        headers(headers_hash)
      end
    end
  },
  [...]

• 既存のコードを新しいカスタムコードに置き換えます。この方法では、コードが具体的で読みやすくなります。 ただし、カスタマイズにより、ソースコードのアップグレードの適用がより複雑になる可能性があるという欠点があります。

  例を表示

  ruby

  authorization: {
    type: 'custom_auth',
    apply: lambda do |connection|
      headers(api_key: => "api_key: Bearer #{connection['api_key']}")
    end
  },
  [...]

ステップ5: オンプレミス接続の設定 ​

オンプレミス接続が必要な場合は、オンプレミスエージェント（OPA）を介して通信するようにコネクターを設定できます。

新しいOPAを設定した後、SDKコネクターのソースコードの冒頭にあるsecure_tunnelキーを見つけます。

trueに設定すると、このアプリはプライベートネットワーク内にありますか? コネクターの設定で項目を使用できるようになります。 その後、ユーザーは接続先のOPAを選択できます。

次の予定 ​

これで完了です - カスタムコネクターを作成しました。 ここから、次の操作を実行できます。

• コネクターのユーザーインターフェースのカスタマイズ
• コネクション項目の詳細
• ソースコードバージョンのアップグレードについて学ぶ