SDK - プロジェクトのディレクトリとファイルのリファレンス

SDK gem を使用して作成されたコネクタープロジェクトは通常、以下のような構成となります。

. # root
├── connector.rb
├── fixtures
├── Gemfile 
├── Gemfile.lock
├── logo.png 
├── master.key 
├── README.md
├── settings.yaml.enc
├── spec 
|   ├── connector_spec.rb
|   └── spec_helper.rb
├── tape_library
├── .github
├── .gitignore 
└── .rspec

それぞれのファイルやディレクトリの役割について、以下に概要を示します。

ファイル/ディレクトリ	作成者/作成手段	説明
connector.rb	workato new	実際のコネクターコードを格納します。これは Workato 内にあるコネクターコードの複製となっているはずです。
fixtures	workato new	RSpec や CLI のための入力/出力 JSON ファイルを格納します。サンプルファイルと詳細情報についてはこちらから確認できます。
Gemfile	workato new	プロジェクトに必要な gem (依存関係) を宣言します。これは RSpec の実行に必要となります。サンプルファイルと詳細情報についてはこちらから確認できます。
Gemfile.lock	workato new	バージョンや依存関係の依存関係といった、gem の依存関係データを格納します。このファイルは、プロジェクト作成時に自動で作成されます。
logo.png	ユーザー	コネクターのロゴ。workato push を通して Workato ワークスペースと同期されると、これがコネクターのデフォルトのロゴ画像として使用されます。
master.key	workato new	ファイルの暗号化に使用される暗号化キーを格納します。暗号化されるファイルの例には、資格情報をはじめとする機密データ (アカウントのプロパティなど) があります。 注: プロジェクトの設定時に secure が選択された場合にのみ作成されます。
README.md	ユーザー	コネクターの機能や使用方法を書き記すために用いられます。workato push を通して Workato ワークスペースと同期されると、これがコネクターの説明のデフォルトファイルとして使用されます。
settings.yaml.enc または settings.yaml		コネクターのテストに用いられる資格情報を格納します。サンプルファイルと詳細情報についてはこちらから確認できます。 注: プロジェクトのセットアップ時に secure が選択された場合、これは .yaml.enc ファイルになります。それ以外の場合は .yaml ファイルになります。
spec	workato new	RSpec テストファイルを格納します。rSpec は、SDK gem と組み合わせて使用することでコネクターの単体テストを定義、記述、実行できる Ruby テストツールです。
spec/connector_spec.rb	workato new	コネクターの単体テストすべてを格納します。このファイルが、メインの RSpec ファイルです。サンプルファイルと詳細情報についてはこちらから確認できます。 このファイルは、テストを整理するために複数のファイルやフォルダーに分けることもできます。すべての仕様テストは bundle exec rspec コマンドを使って実行できます。
spec/spec_helper.rb	workato new	RSpec の実行前に毎回設定する必要があるコマンドすべてを格納します。サンプルファイルと詳細情報についてはこちらから確認できます。
tape_library	RSpec	VCR カセットを格納します。VCR カセットは、記録された API リクエストと後続のレスポンスに関するすべての情報を格納したファイルです。これらのリクエストは、単体テストの安定のために欠かせません。詳細については VCR のドキュメントを参照してください。
.github	ユーザー	GitHub を利用している場合に使われます。ユーザーの GitHub アクションワークフローに関する情報を格納します。
.gitignore	workato new	Git にプッシュすべきではないファイルやディレクトリの名前を格納します。サンプルファイルと詳細情報についてはこちらから確認できます。 注: プロジェクトに master.key がある場合は、Workato のセキュリティベストプラクティスに従い、それをこのファイルに追加することが推奨されます。
.rspec	workato new	実行時に RSpec に渡す標準オプションを格納します。フラグには以下のようなものがあります。 --format documentation - テストのグループ化を有効化 --color - RSpec 出力の色分けを有効化 --require spec_helper - 毎回の RSpec の実行前に spec_helper.rb を要求するよう指示

---

connector_spec.rb

connector_spec.rb ファイルは workato new の実行時に作成され、コネクターの単体テストを格納します。

以下にファイル内容の例を挙げます。

# frozen_string_literal: true

RSpec.describe 'connector', :vcr do
  let(:connector) { Workato::Connector::Sdk::Connector.from_file('connector.rb', settings) }
  let(:settings) { Workato::Connector::Sdk::Settings.from_default_file }

  it { expect(connector).to be_present }

  describe 'test' do
    subject(:output) { connector.test(settings) }

    context 'given valid credentials' do
      it 'establishes valid connection' do
        expect(output).to be_truthy
      end

      it 'returns response that is not excessively large' do
        # large Test responses might also cause connections to be evaluated wrongly
        expect(output.to_s.length).to be < 5000
      end
    end

    context 'given invalid credentials' do
      let(:settings) { Workato::Connector::Sdk::Settings.from_encrypted_file('invalid_settings.yaml.enc'}

      it 'establishes invalid connection' do
        expect { output }
          .to raise_error('500 Internal Server Error')
      end
    end
  end
end

また、workato generate test を使用して RSpec テストスタブを生成することもできます。これにより、コネクターのインスタンス化や設定といった手間のかかる作業の大部分を処理することができます。

単体テストをどのように書くかは、最終的にはユーザー次第です。作業を開始するための参考情報については、こちらのチュートリアルを参照してください (opens new window)。

---

fixtures

/fixtures フォルダーの用途は、コネクターの各部分をテストするために使用される入力/出力 JSON ファイルを格納することです。その各部分としては、たとえばアクション、トリガー、メソッドなどが挙げられます。

入力 JSON ファイルは、手動で作成する必要があります。これはユーザー自身で設計することも、Cloud SDK のデバッガーコンソールを利用して作成することもできます。

出力 JSON ファイルは、--output オプションを追加することで CLI コマンドから作成できます。以下に例を示します。

workato exec <PATH> --output

/fixtures フォルダーの内容の例を以下に示します。

├── fixtures
│   ├── actions
│   │   └── search_customers
│   │       ├── input.json
│   │       └── output.json
│   ├── methods
│   │   └── sample_method
│   │       ├── input.json
│   │       └── output.json
│   ├── pick_lists
│   │   └── dependent
│   │       └── input.json
│   └── triggers
│       └── new_updated_object
│           ├── customer_config.json
│           ├── customer_input_poll.json
│           ├── customer_input_poll_page.json
│           ├── customer_output_fields.json
│           ├── customer_output_poll.json
│           └── customer_output_poll_page.json

---

GEMFILE

# frozen_string_literal: true

source 'https://rubygems.org'

gem 'rspec'
gem 'vcr'
gem 'workato-connector-sdk'
gem 'webmock'
gem 'timecop'
gem 'byebug'
gem 'rubocop' # Only if you want to use rubocop. Not added by default.

---

settings.yaml.enc、settings.yaml

settings.yaml.enc/settings.yaml ファイルは、テストに使用する資格情報を格納します。このファイルのデータは有効な YAML である必要があります。

資格情報のセットが1つの場合

資格情報のセットが1つだけの場合、それはルートレベルで定義できます。

api_key: valid_key
domain: valid_domain

資格情報のセットが複数の場合

資格情報のセットが複数ある場合、設定ファイルは以下のような構造にする必要があります。

[one_connection_name]:
  api_key: valid_key
  domain: valid_domain
[second_connection_name]:
  api_key: invalid_key
  domain: invalid_domain

---

spec_helper.rb

spec_helper.rb ファイルは workato new の実行時に作成され、RSpec の実行で使用される一般的な属性を格納します。

このファイルでは少なくとも以下を require する必要があります。

• 'bundler/setup'
• 'workato-connector-sdk'
• 'json'

追加的な RSpec 設定の詳細については、RSpec リポジトリ (opens new window)を参照してください。

以下は、プロジェクトの HTTP モック動作として secure が選択されたときに作成される spec_helper.rb ファイルの例です。

このファイルは、プロジェクトの master.key を利用してすべての VCR 記録を暗号化します。

ただし、secure の記録モードはデフォルトでは none になっています。つまり、新しい VCR カセットは記録されないということです。この動作を変更するには、環境変数 VCR_RECORD_MODE を once に設定してください。

# frozen_string_literal: true

require 'bundler/setup'
require 'json'
require "webmock/rspec"
require "timecop"
require "vcr"
require "workato-connector-sdk"
require "workato/testing/vcr_encrypted_cassette_serializer"
require "workato/testing/vcr_multipart_body_matcher"

RSpec.configure do |config|
  # Enable flags like --only-failures and --next-failure
  config.example_status_persistence_file_path = ".rspec_status"

  # Disable RSpec exposing methods globally on `Module` and `main`
  config.disable_monkey_patching!

  config.expect_with :rspec do |c|
    c.syntax = :expect
  end
end

VCR.configure do |config|
  config.cassette_library_dir = "tape_library"
  config.hook_into :webmock
  config.cassette_serializers[:encrypted] = Workato::Testing::VCREncryptedCassetteSerializer.new
  config.register_request_matcher :headers_without_user_agent do |request1, request2|
    request1.headers.except("User-Agent") == request2.headers.except("User-Agent")
  end
  config.register_request_matcher :multipart_body do |request1, request2|
    Workato::Testing::VCRMultipartBodyMatcher.call(request1, request2)
  end
  config.default_cassette_options = {
    record: ENV.fetch('VCR_RECORD_MODE', :none).to_sym,
    serialize_with: :encrypted,
    match_requests_on: %i[uri headers_without_user_agent body]
  }
  config.configure_rspec_metadata!
end

---

.gitignore

.gitignore ファイルには、Git でプッシュすべきではないファイルやディレクトリのリストが格納されます。

注 : プロジェクトに master.key ファイルがある場合は、リポジトリに誤ってコミットされないよう、それをこのファイルに追加してください。

/.bundle/
/.yardoc
/_yardoc/
/coverage/
/doc/
/pkg/
/spec/reports/
/tmp/
master.key

# rspec failure tracking
.rspec_status