Apps Script タスク

お知らせ: Google Cloud プロジェクトで Application Integration を使用できるようになりました。これで、同じ Google Cloud プロジェクト内で Apigee Integration と Application Integration の両方を使用できるようになりました。詳細

Apps Script タスクを使用すると、統合から Google Apps Script を実行できます。Google Apps Script は、高速かつ容易なビジネス アプリケーションの作成を可能にする迅速性に優れたアプリケーション開発プラットフォームです。詳細については、Google Apps Script をご覧ください。このタスクは、カスタム スクリプトを実行する場合、または既存のスクリプトを統合で再利用する場合に有用です。

注: Apps Script タスクは、リージョン化されていないグローバル サービスです。

始める前に

Apps Script タスクを使用する前に、次の手順を完了しておいてください。

• AppsScript API を有効にする
• OAuth 2.0 クライアント ID を作成する
• 認証プロファイルを設定する
• Google Cloud プロジェクトの Apigee Integration で VPC Service Controls が設定されていないことを確認します。
  警告: Google Cloud プロジェクトで Application Integration 用に VPC Service Controls が設定されている場合、Cloud Functions は機能しないか、機能を停止します。

AppsScript API を有効にする

このタスクを使用するには、Google Cloud プロジェクトの AppsScript API と AppsScript ユーザー アカウントを有効にする必要があります。Google Cloud プロジェクトで AppsScript API を有効にする方法については、標準 Google Cloud プロジェクトで API を有効にするをご覧ください。ユーザー アカウントで API を有効にするには、[設定] をクリックし、Google Apps Script API を On に設定します。

OAuth 2.0 クライアント ID を作成する

利用可能な OAuth 2.0 クライアント ID をお持ちの場合は、この手順をスキップして認証プロファイルの設定に進むことができます。

新しい OAuth クライアント ID の作成については、OAuth クライアント ID の作成をご覧ください。

認証プロファイルを設定する

Apigee Integration では、認証プロファイルを使用して Google Cloud に接続し、Apps Script プロジェクトをデプロイして実行します。認証プロファイルを設定する手順は、次のとおりです。

Apps Script タスクを追加する

1. Apigee UI で、Apigee 組織を選択します。
2. [Develop] > [Integrations] の順にクリックします。
3. 既存のインテグレーションを選択するか、[Create Integration] をクリックして新しいインテグレーションを作成します。

   新しいインテグレーションを作成する場合:

   1. [Create Integration] ダイアログで名前と説明を入力します。
   2. サポートされているリージョンのリストから、インテグレーションのリージョンを選択します。
   3. [Create] をクリックします。

   インテグレーション デザイナーでインテグレーションが開きます。

4. インテグレーション デザイナーのナビゲーション バーで、[+ Add a task/trigger] > [Tasks] の順にクリックして、使用可能なタスクのリストを表示します。
5. [Apps Script] 要素をクリックして統合エディタに配置します。

認証プロファイルを作成する

1. デザイナーの [Apps Script] 要素をクリックして、[Apps Script] タスク構成ペインを表示します。
2. Apps Script タスクのタスク構成ペインで、[+ New authentication profile] をクリックします。
3. [Authentication profile] ダイアログで、プロファイルの名前と説明を入力して、次のプロパティを設定します。
   • Authentication type: OAuth 2.0 認証コードを選択します。
   • Authentication endpoint: 「https://accounts.google.com/o/oauth2/auth」と入力します。
   • Token endpoint: 「https://oauth2.googleapis.com/token」と入力します。
   • Client ID: クライアント ID を入力します。

     クライアント ID は、Google Cloud プロジェクト ダッシュボードの [認証情報] > [OAuth 2.0 クライアント ID] で確認できます。

   • Secret: クライアント シークレットを入力します。

     クライアント シークレットは、Google Cloud プロジェクト ダッシュボードの [認証情報] > [OAuth 2.0 クライアント ID] で確認できます。

   • Scope(s): 次のように入力します。

     https://www.googleapis.com/auth/script.projects https://www.googleapis.com/auth/script.deployments https://www.googleapis.com/auth/script.deployments.readonly https://www.googleapis.com/auth/drive.scripts https://www.googleapis.com/auth/drive https://www.googleapis.com/auth/script.external_request https://www.googleapis.com/auth/userinfo.email

     注: 複数のスコープは、スペース 1 文字（「 」）で区切ることができます。

4. [Generate Access Token and Save] をクリックします。

   認可画面にリダイレクトされます。ログインして、表示された許可画面に同意し、アクセス トークンを生成します。アクセス トークンの生成が正常に終了すると、認証プロファイルが保存され、統合の編集を続行できます。

注: 認証プロファイルの作成と、Apps Script のデプロイは、同じユーザーが行う必要があります。ユーザーが異なると、Apps Script は実行されません。

Apps Script タスクを構成する

Apps Script タスクで Apps Script プロジェクトを構成するには、次の手順を行います。

1. タスク構成ペインで、[Configure Apps Script Project] をクリックします。

   [Apps Script Configuration] ダイアログが表示されます。

2. 既存の Apps Script プロジェクトにリンクするか、新しい Apps Script プロジェクトを作成できます。

   Apps Script プロジェクトを構成すると、Apps Script プロジェクトが Apigee Integration の統合に関連付けられます。

3. [Save] をクリックする。
4. [Open Apps Script Project] をクリックします。

   Apps Script エディタでは、次のファイルを表示できます。

   • Run.gs: 実行可能コードが含まれます。run 関数内でスクリプトを記述します。この関数は、Apps Script タスクの実行時に呼び出されます。スクリプトでは、統合レベルで定義された変数を使用できます。統合変数の使用ついての情報は、統合変数の使用をご覧ください。
   • Main.gs: 統合から Apps Script を実行するための初期化コードが含まれています。このファイルは、編集 / 変更しないでください。
   • Test.gs: テスト実行の実行コードが含まれます。testRun 関数内にスクリプトを記述して、スクリプトをテストできます。

   プロジェクトは、ウェブアプリ形式でデプロイしてください。さまざまなデプロイモードの詳細については、デプロイの作成と管理をご覧ください。

統合変数にアクセスする

Apps Script タスクでは、AppsScriptTask ライブラリを使用します。このライブラリにより、スクリプトで統合変数を使用できます。AppsScriptTask ライブラリが自動的にインポートされ、run 関数で使用できます。

Apps Script の統合変数にアクセスするには、変数をタスク パラメータの形式で Apps Script タスクに渡す必要があります。タスク パラメータは Key-Value ペアです。ここで、Key は AppsScript タスクの変数の名前、Value は対応する統合変数名です。タスク構成ペインの [Task Parameters] セクションで、1 つ以上のタスク パラメータを追加できます。

たとえば、Apps Script で使用する Product という名前の統合変数がある場合は、Key を ProductKey、その値を Product として定義できます。このように処理すると、Apps Script で AppsScriptTask.getTaskParameter('ProductKey') を使用してプロダクト変数を読み取ることができます。

注: AppsScript で統合変数を使用するには、変数を Apps Script タスクのタスク パラメータとして追加する必要があります。

AppsScriptTask ライブラリには、統合変数にアクセスするための次のメソッドが用意されています。

• setIntegrationVariable
• getTaskParameter

関数名	説明	使用状況
setIntegrationVariable	指定された値を変数に設定します。	構文: setIntegrationVariable(value,value) 例: // Write to an Integer variable AppsScriptTask.setIntegrationVariable('EmployeeIDKey','456');
getTaskParameter	変数の値を取得します。	構文: getTaskParameter(value) 例: // Read an integration variable AppsScriptTask.getTaskParameter('EmployeeIDKey');

AppsScriptTask ライブラリで使用可能なすべての関数を表示するには、Apps Script エディタの [AppsScriptTask] メニュー項目にカーソルを合わせて、Apps Script エディタのメニュー項目で、[その他] > [新しいタブで開く] の順にクリックします。

Apps Script をテストする

統合を公開する前に、Test.gs ファイルで利用可能な testRun 関数を使用してスクリプトをテストできます。テストコードは、AppsScriptTaskTest ライブラリを使用して、testRun 関数に記述します。このライブラリを使用すると、アサーション ベースのテストケースを実行でき、testRun 関数で使用するために自動的にインポートされます。

AppsScriptTaskTest ライブラリの利用可能なすべての関数を表示するには、Apps Script エディタで AppsScriptTaskTest メニュー項目にカーソルを合わせ、その他アイコン > [新しいタブで開く] をクリックします。

次のサンプルでは、AppsScriptTaskTest ライブラリ関数の使用方法を示します。

function testRun(){

  // Create a new request
  let req = AppsScriptTaskTest.createNewTestRequest('myCustomTest');

  // Add a task parameter that references an integration variable with the value 5
  AppsScriptTaskTest.setIntegrationVariableAndCreateReference(req, 'input', '$input$', 5);

  // Add a task parameter that references an integration variable
  AppsScriptTaskTest.createReference(req, 'output', '$output$');

  // Run the task(assuming the task increments the input by 1) and get the response
  let res = AppsScriptTaskTest.runTest(req, executeScript);

  // Check the response for the expected integration variable and its corresponding values
  AppsScriptTaskTest.containsIntegrationVariable(res, 'output', true);
  AppsScriptTaskTest.containsIntegrationVariable(res, 'someOtherIntegrtionVariable', false);
  AppsScriptTaskTest.containsIntegrationVariableWithValue(res, 'output', 6);
}

次のサンプルは、testRun メソッドで JSON と配列変数にアクセスする方法を示しています。

function testRun(){

  // Create a new request
  let req = AppsScriptTaskTest.createNewTestRequest('json-test');

  // Add a task parameter that references a JSON integration variable
  AppsScriptTaskTest.setIntegrationVariableAndCreateReference(req, "emp", "employee", {name:"snape", age:35});

  // Add a task parameter that references an array integration variable
  AppsScriptTaskTest.setIntegrationVariableAndCreateReference(req, "arr", "array", ["A", "B", "C"]);


  // Run the task and get the response
  // Assume that the run method increases the age of the employee by 5 and appends a new element in the array
  let res = AppsScriptTaskTest.runTest(req, executeScript);

  // Check the response for the expected integration variable and its corresponding values
  AppsScriptTaskTest.containsIntegrationVariableWithValue(res, "employee", {name:"snape", age:40});
  AppsScriptTaskTest.containsIntegrationVariable(res, "array", true);
  AppsScriptTaskTest.containsIntegrationVariableWithValue(res, "array", ["A", "B", "C", "D"]);
}

テストケースを実行すると、実行ログでアサーションを表示できます。ログを表示するには、メニューの [実行ログ] をクリックします。

ベスト プラクティス

統合でタスクのレイテンシを 1～2 秒未満にする必要がある場合、Apps Script タスクの使用はおすすめしません。

また、パフォーマンスのボトルネックを最小限に抑えるため、複数の Apps Script タスクをチェーン化するのではなく、すべてのロジックを単一の Apps Script タスクにコーディングすることをおすすめします。

Apps Script タスクに適用される使用量上限については、使用量上限をご覧ください。

考慮事項

Apps Script タスクを統合設計に含める場合は、次のシステム制限を考慮してください。

• AppsScript のアクティブなデプロイの最大数: 50
• API 実行可能ファイルの秒間クエリ数（QPS）: 5,000 / 分
• ウェブアプリ デプロイメントの秒間クエリ数（QPS）: 5,000 / 分
• API 実行可能ファイルのレイテンシ: 1.5 秒
• Webapp のレイテンシ: 2.5 秒
• AppsScript 内のすべての統合変数の最大累積サイズ: 15 MB

エラー処理方法

タスクのエラー処理方法では、一時的なエラーによってタスクが失敗した場合のアクションを指定します。エラー処理方式と、さまざまな種類のエラー処理方式の詳細については、エラー処理方法をご覧ください。