Apps Script の高度なサービスを使用すると、経験豊富なデベロッパーは、HTTP インターフェースを使用する場合よりも少ない設定で、特定の一般公開されている Google API に接続できます。拡張サービスは、基本的にこれらの Google API のシンラッパーです。これらは Apps Script の組み込みサービスとよく似ています。たとえば、自動補完が提供され、Apps Script が認可フローを自動的に処理します。ただし、スクリプトで使用する前に、拡張サービスを有効にする必要があります。
どの Google API が拡張サービスとして利用できるかを確認するには、リファレンスの拡張 Google サービスのセクションをご覧ください。高度なサービスとして利用できない Google API を使用する場合は、他の外部 API と同様に接続します。
高度なサービスまたは HTTP？
各 Google 拡張サービスは、公開 Google API に関連付けられています。Apps Script では、これらの API には、高度なサービスを介してアクセスするか、UrlFetch を使用して 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 APIs の利用規約にも同意するよう求められることがあります。
スクリプト プロジェクトで標準の 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は自動的に設定されます。 - Google API で
deleteという名前のメソッドは、Apps Script ではremoveという名前になります。これは、deleteが JavaScript の予約語であるためです。 - HTTP リクエスト ヘッダーを受け入れるように高度なサービスが構成されていて、リクエスト ヘッダーの JavaScript オブジェクトを設定した場合は、オプション パラメータの JavaScript オブジェクトも設定する必要があります（オプション パラメータを使用しない場合は空のオブジェクトに設定します）。
高度なサービスのサポート
拡張サービスは、Apps Script 内で Google API を使用できるようにするシンラッパーです。そのため、これらの API の使用中に発生した問題は、通常、Apps Script 自体ではなく、基盤となる API の問題です。
高度なサービスの使用中に問題が発生した場合は、基盤となる API のサポート手順に沿って報告する必要があります。これらのサポート手順へのリンクは、Apps Script のリファレンス セクションにある各拡張サービス ガイドに記載されています。