高度な Google サービス

Apps Script の高度なサービスを使用すると、経験豊富なデベロッパーは、HTTP インターフェースを使用するよりも簡単な設定で、特定の公開 Google API に接続できます。高度なサービスは、基本的にこれらの Google API のシンラッパーです。これらは Apps Script の組み込みサービスと同様に機能します。たとえば、オートコンプリートを提供し、Apps Script が認可フローを自動的に処理します。ただし、スクリプトで高度なサービスを使用するには、高度なサービスを有効にする必要があります。

高度なサービスとして利用できる Google API を確認するには、リファレンス高度な Google サービスのセクションをご覧ください。高度なサービスとして利用できない Google API を使用する場合は、他の外部 API と同様に接続するだけです。

高度なサービスと HTTP のどちらを使用するか

高度な Google サービスはいずれも、公開 Google API に関連付けられています。Apps Script では、高度なサービスを使用するか、UrlFetch を使用して直接 API リクエストを行うことで、これらの API にアクセスできます。

高度なサービス方式を使用する場合、Apps Script は認可フローを処理し、オートコンプリートをサポートします。ただし、使用する前に高度なサービスを有効にする必要があります。また、一部の高度なサービスでは、API で使用できる機能のサブセットのみが提供されます。

UrlFetch メソッドを使用して API に直接アクセスする場合は、基本的に Google API を外部 API として扱います。この方法では、API のすべての要素を使用できます。ただし、API 承認はデベロッパー自身で処理する必要があります。また、必要なヘッダーを作成し、API レスポンスを解析する必要があります。

一般に、可能な限り高度なサービスを使用し、その高度なサービスで必要な機能が提供されない場合にのみ、UrlFetch メソッドを使用するのが最も簡単です。

要件

高度なサービスを使用するには、次の要件を満たす必要があります。

  1. スクリプト プロジェクトで高度なサービスを有効にする必要があります。
  2. スクリプトが使用する Cloud Platform(GCP)プロジェクトで、高度なサービスに対応する API が有効になっていることを確認する必要があります。

    2019 年 4 月 8 日以降に作成されたデフォルトの GCP プロジェクトをスクリプト プロジェクトで使用する場合、高度なサービスを有効にしてスクリプト プロジェクトを保存すると、API が自動的に有効になります。まだ同意していない場合は、Google CloudGoogle API の利用規約への同意も求められることがあります。

    スクリプト プロジェクトで標準 GCP プロジェクトまたは古いデフォルトの GCP プロジェクトを使用している場合は、GCP プロジェクトで高度なサービスの対応する API を手動で有効にする必要があります。この変更を行うには、GCP プロジェクトに対する編集権限が必要です。

詳しくは、Cloud Platform プロジェクトをご覧ください。

高度なサービスを有効にする

Google の高度なサービスを使用する手順は次のとおりです。

  1. Apps Script プロジェクトを開きます。
  2. 左側のエディタ アイコン をクリックします。
  3. 左側の [サービス] の横にある [サービスを追加] をクリックします。
  4. 高度な Google サービスを選択し、[追加] をクリックします。

高度なサービスを有効にすると、オートコンプリートでそのサービスを利用できるようになります。

メソッド シグネチャの決定方法

高度なサービスは通常、対応する公開 API と同じオブジェクト、メソッド名、パラメータを使用しますが、メソッド シグネチャは Apps Script で使用するために変換されます。通常、スクリプト エディタのオートコンプリート機能で十分な情報が得られます。ただし、以下のルールでは、Apps Script が公開の Google API からメソッド シグネチャを生成する方法について説明します。

Google API へのリクエストでは、パスパラメータ、クエリ パラメータ、リクエスト本文、メディア アップロードの添付ファイルなど、さまざまな種類のデータを受け取ることができます。一部の高度なサービスでは、特定の HTTP リクエスト ヘッダーを受け入れることもできます(カレンダーの高度なサービスなど)。

Google Apps Script の対応するメソッド シグネチャには次の引数があります。

  1. リクエストの本文(通常はリソース)。JavaScript オブジェクト。
  2. パスまたは必須パラメータ(個別の引数)。
  3. メディア アップロードの添付ファイル。Blob 引数で指定します。
  4. オプションのパラメータ。パラメータ名を値にマッピングする JavaScript オブジェクトです。
  5. HTTP リクエスト ヘッダー。ヘッダー名をヘッダー値にマッピングする JavaScript オブジェクトです。

メソッドで指定したカテゴリのアイテムがない場合、シグネチャのその部分は省略されます。

ただし、次のような特別な例外があります。

  • メディア アップロードを受け入れるメソッドの場合、パラメータ uploadType が自動的に設定されます。
  • delete は JavaScript の予約語であるため、Google API の delete という名前のメソッドは、Apps Script では remove という名前になります。
  • 高度なサービスが HTTP リクエスト ヘッダーを受け入れるように構成されていて、リクエスト ヘッダー JavaScript オブジェクトを設定する場合は、オプション パラメータ JavaScript オブジェクトも設定する必要があります(オプション パラメータを使用しない場合は空のオブジェクト)。

高度なサービスのサポート

拡張サービスは、Apps Script 内で Google API を使用できるようにするシンラッパーです。そのため、これらのスクリプトの使用時に発生する問題は通常、Apps Script 自体ではなく、基盤となる API にあります。

高度なサービスの使用中に問題が発生した場合は、基盤となる API のサポート手順を使用して報告してください。これらのサポート手順へのリンクは、Apps Script のリファレンス セクションにあるそれぞれの高度なサービスガイドに記載されています。