# SDK Gem 入門ガイド

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

  • SDK gem のインストールと実行
  • 新しいコネクタープロジェクトの作成
  • コネクター用テストの設定
  • ローカルコネクターの Workato ワークスペースへのプッシュ

# 前提条件

このチュートリアルを完了するには、以下のものが必要になります。

  • Ruby バージョンマネージャー。 お使いのオペレーティングシステムに応じて、Ruby または Ruby バージョンマネージャーをインストールする必要があります。

Mac ユーザーは、Ruby バージョンマネージャー (opens new window)または任意のマネージャーを使用できます。

Windows ユーザーは、RubyInstaller (opens new window) を使用できます。

詳細については、こちら (opens new window)から Ruby 公式ドキュメントを参照してください。

  • サポートされているバージョンの Ruby。 2.7.X をお勧めしますが、2.4.10 または 2.5.X も使用できます。Ruby をインストールしていない場合は、公式ドキュメントの手順に従ってインストールしてください (opens new window)

    Ruby のバージョンは、次のコマンドを実行するか、Ruby バージョンマネージャーの適切なコマンド (例 : rvm current ) を実行することで確認できます。

    $ ruby -v
    ruby 2.7.X
    

    このコマンドは、現在コンピュータにインストールされている Ruby のバージョンを返します。この例では、2.7.X を使用しています。


# ステップ1 : SDK Gem のインストールと実行

SDK gem のインストールはコマンドラインで行います。次のコマンドを実行し、rubygems.org (opens new window) から gem をインストールします。

$ gem install workato-connector-sdk

ターミナルで workato コマンドを入力して、gem が正しくインストールされていることを確認します。

$ workato

Commands:
  workato edit <PATH>            # Edit encrypted file, e.g. settings.yaml.enc
  workato exec <PATH>            # Execute connector defined block
  workato generate <SUBCOMMAND>  # Generates code from template
  workato help [COMMAND]         # Describe available commands or one specific command
  workato new <CONNECTOR_PATH>   # Inits new connector folder
  workato push <FOLDER>          # Upload and release connector's code

Options:
  [--verbose], [--no-verbose]  

TIP

tzinfo-data gem をインストールする必要がある Windows ユーザーは、gem install tzinfo-data コマンドを実行してください。

gem の正確な場所を確認するには、gem which を使用します。

$ gem which workato-connector-sdk

さらに、workato コマンドを使用すると、開発中に利用可能なコマンドを表示できます。個々のキーの詳細については、workato help edit などを使用して確認してください。


# ステップ2 : 新しいコネクタープロジェクトの作成

これで設定はすべて終わりましたので、次はコネクターを作成します。

1

workato new コマンドを使用して新しいコネクタープロジェクトを作成します。<PATH> はプロジェクトで使用するパスに置き換えてください。

$ workato new <PATH>

これにより、現在のディレクトリにプロジェクトが作成されます。

2

次に、HTTP モック動作について入力を求められる場合があります。

Please select default HTTP mocking behavior suitable for your project?

1 - secure. Cause an error to be raised for any unknown requests, all request recordings are encrypted.
            To record a new cassette you need set VCR_RECORD_MODE environment variable

            Example: VCR_RECORD_MODE=once bundle exec rspec spec/actions/test_action_spec.rb

2 - simple. Record new interaction if it is a new request, requests are stored as plain text and expose secret tokens.

以下の 1 または 2 から選択して入力します。

  • 1 - secure - 推奨。 HTTP リクエストはすべて暗号化され、安定性を確保するために VCR で記録されます。また、資格情報がプレーンテキストで保存されないよう、記録を暗号化する簡単な方法も用意されています。
  • 2 - simple - HTTP リクエストはすべてプレーンテキストで保存されます。

workato new コマンドが作成するファイルの詳細については、プロジェクトディレクトリのリファレンスを参照してください。


# ステップ3 : コネクターの構築とテスト

このステップでは、コネクターの構築とテストを行います。何をどのように構築するかはユーザーごとに異なるため、このセクションではテストについてのみ取り上げます。

# ステップ3.1 : テスト用資格情報の指定

資格情報はプロジェクトの settings.yaml.enc または settings.yaml ファイルに保管されます。

1

ファイルの暗号化を選択した場合はworkato edit コマンドを実行し、<EDITOR> を任意のエディターに置き換えます。

例 - Mac ユーザー
$ EDITOR="<EDITOR>" workato edit settings.yaml.enc
例 - Windows ユーザー
$ set EDITOR=notepad
$ workato edit settings.yaml.enc

このコマンドを初めて実行すると、settings.yaml.enc および master.key ファイルが作成されます。

2

プロジェクトの settings.yaml.enc または settings.yaml ファイルに資格情報を追加します。

この例では、ルートレベルで定義できるよう1セットの資格情報を使用します。

## settings.yaml.enc

api_key: [api_key]
domain: [domain]

複数セットの資格情報の指定方法など詳細については、設定ファイルのリファレンスを参照してください。

3

プロジェクトをコミットする場合はmaster.key をプロジェクトの .gitignore または類似のファイルに追加します。これにより、誰でもアクセスできるリポジトリに資格情報がチェックインされるのを防ぎます。

# ステップ3.2 : コネクターのテスト

workato exec を使用して、コネクターの接続、トリガー、またはアクションをテストします。これは、指定した PATH でコネクターの lambda ブロックを実行します。

例 :

# Executes the execute block of the new_record action
$ workato exec actions.new_record.execute 

# Invokes a polling trigger for the updated_record trigger
$ workato exec triggers.updated_record.poll 

# Executes the get_record method with parameters from input.json 
$ workato exec methods.get_record --args=input.json 

CLI でのテストの詳細については、「How to ガイド - CLI における test lambda の実行」を参照してください。


# ステップ4 : Workato ワークスペースへのプッシュ

準備ができたら、コネクターのコードをローカル環境から Workato ワークスペースにプッシュします。Workato ワークスペースにプッシュすると、コネクターの機能やユーザーエクスペリエンスをテストして、すばやく改善できるようになります。

次のように workato push コマンドを実行します。

$ workato push

Workato ワークスペースでテストを行い、必要に応じてローカルで変更して Workato ワークスペースにプッシュします。その際は、ワークスペースのメールアドレスや API トークンを認証用に設定する必要があります。


# ステップ5 : RSpec を使ったコネクターのテスト

ユニットテストは、コネクターのイテレーションがそれぞれ期待どおりに実行されているかどうかを確認するための最適な方法です。コネクターのテストの作成方法の詳細については、こちらを参照してください。

RSpec を実行するには、プロジェクト構成を設定する必要があります。RSpec の実行は、CLI で Workato gem を実行するのと同じくらい簡単です。プロジェクトのホームディレクトリで bundle exec rspec を使用するだけです。

特定のテストのみを一度に実行することもできますが、指定しない場合、RSpec は デフォルトで spec フォルダーにあるすべての spec ファイルを実行します。

# Runs the test(s) at line 16 of your spec file. 
$ bundle exec rspec ./spec/connector_spec.rb:16 

注 : rspec コマンドも使用できますが、bundle exec rspec を使用すると、テストの実行に使用している RSpec の gem のバージョンが、Gemfile で指定されたバージョンであることが保証されます。

# 5.1 VCR の設定

Workato の SDK Gem は RSpec や VCR と連携することで、ユニットテストを作成し、HTTP のやり取り (リクエストとレスポンス) を保存する方法を提供します。これにより、API に常にリクエストを送信しなくても、ユニットテストを継続して実行することができます。同じレスポンスが再生されるという利点もあるため、アプリケーションでの実際のデータの変更を心配する必要はありません。

Workato を使用してプロジェクトを生成すると、これらの設定が spec_helper.rb ファイルに自動的に生成されます。いくつかのデフォルトの VCR 設定もこのファイルに含まれます。こうした VCR の記録は、プロジェクトの初回設定時に選択したセキュリティ設定にも依存します。secure を選択した場合、VCR の記録は master.key を使用して暗号化されます。

VCR の使用の詳細については、こちらを参照してください。


# 次のステップ


Last updated: 2024/7/10 18:18:20