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 メソッドを使用するのが最も簡単です。
要件
高度なサービスを使用するには、次の要件を満たす必要があります。
- スクリプト プロジェクトで高度なサービスを有効にする必要があります。
スクリプトが使用する Cloud Platform（GCP）プロジェクトで、高度なサービスに対応する API が有効になっていることを確認する必要があります。
2019 年 4 月 8 日以降に作成されたデフォルトの GCP プロジェクトをスクリプト プロジェクトで使用する場合、高度なサービスを有効にしてスクリプト プロジェクトを保存すると、API が自動的に有効になります。まだ同意していない場合は、Google Cloud と Google API の利用規約への同意も求められることがあります。
スクリプト プロジェクトで標準 GCP プロジェクトまたは古いデフォルトの GCP プロジェクトを使用している場合は、GCP プロジェクトで高度なサービスの対応する API を手動で有効にする必要があります。この変更を行うには、GCP プロジェクトに対する編集権限が必要です。
詳しくは、Cloud Platform プロジェクトをご覧ください。
高度なサービスを有効にする
Google の高度なサービスを使用する手順は次のとおりです。
- Apps Script プロジェクトを開きます。
- 左側のエディタ アイコン をクリックします。
- 左側の [サービス] の横にある [サービスを追加] をクリックします。
- 高度な Google サービスを選択し、[追加] をクリックします。
高度なサービスを有効にすると、オートコンプリートでそのサービスを利用できるようになります。
メソッド シグネチャの決定方法
高度なサービスは通常、対応する公開 API と同じオブジェクト、メソッド名、パラメータを使用しますが、メソッド シグネチャは Apps Script で使用するために変換されます。通常、スクリプト エディタのオートコンプリート機能で十分な情報が得られます。ただし、以下のルールでは、Apps Script が公開の Google API からメソッド シグネチャを生成する方法について説明します。
Google API へのリクエストでは、パスパラメータ、クエリ パラメータ、リクエスト本文、メディア アップロードの添付ファイルなど、さまざまな種類のデータを受け取ることができます。一部の高度なサービスでは、特定の HTTP リクエスト ヘッダーを受け入れることもできます（カレンダーの高度なサービスなど）。
Google Apps Script の対応するメソッド シグネチャには次の引数があります。
- リクエストの本文（通常はリソース）。JavaScript オブジェクト。
- パスまたは必須パラメータ（個別の引数）。
- メディア アップロードの添付ファイル。
Blob引数で指定します。 - オプションのパラメータ。パラメータ名を値にマッピングする JavaScript オブジェクトです。
- HTTP リクエスト ヘッダー。ヘッダー名をヘッダー値にマッピングする JavaScript オブジェクトです。
メソッドで指定したカテゴリのアイテムがない場合、シグネチャのその部分は省略されます。
ただし、次のような特別な例外があります。
- メディア アップロードを受け入れるメソッドの場合、パラメータ
uploadTypeが自動的に設定されます。 deleteは JavaScript の予約語であるため、Google API のdeleteという名前のメソッドは、Apps Script ではremoveという名前になります。- 高度なサービスが HTTP リクエスト ヘッダーを受け入れるように構成されていて、リクエスト ヘッダー JavaScript オブジェクトを設定する場合は、オプション パラメータ JavaScript オブジェクトも設定する必要があります（オプション パラメータを使用しない場合は空のオブジェクト）。
高度なサービスのサポート
拡張サービスは、Apps Script 内で Google API を使用できるようにするシンラッパーです。そのため、これらのスクリプトの使用時に発生する問題は通常、Apps Script 自体ではなく、基盤となる API にあります。
高度なサービスの使用中に問題が発生した場合は、基盤となる API のサポート手順を使用して報告してください。これらのサポート手順へのリンクは、Apps Script のリファレンス セクションにあるそれぞれの高度なサービスガイドに記載されています。