経験豊富なデベロッパーであれば、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 API の利用規約への同意を求められることもあります。
スクリプト プロジェクトで標準の GCP プロジェクトまたは古いデフォルトの GCP プロジェクトを使用する場合は、GCP プロジェクトで対応する高度な API を 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 リファレンスの各高度なサービスガイドに記載されています。