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が自動的に設定されます。 - Google API の
deleteという名前のメソッドは、Apps Script ではremoveという名前になります。deleteは JavaScript の予約語であるためです。 - 高度なサービスが HTTP リクエスト ヘッダーを受け入れるように構成されていて、リクエスト ヘッダー JavaScript オブジェクトを設定している場合は、オプション パラメータの JavaScript オブジェクトも設定する必要があります（オプションのパラメータを使用しない場合は空のオブジェクトに設定します）。
高度なサービスのサポート
拡張サービスは、Apps Script 内で Google API を使用できるようにするシンラッパーです。そのため、通常は、Apps Script 自体ではなく、基盤となる API に関する問題です。
高度なサービスの使用中に問題が発生した場合は、基盤となる API のサポート手順を使用して報告してください。これらのサポート手順へのリンクは、Apps Script リファレンス セクションの高度なサービスガイドに記載されています。