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 リクエスト ヘッダー（Calendar Advanced Service など）を受け入れることもできます。
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 のリファレンス セクションにある各拡張サービスガイドに記載されています。