サードパーティ API のデータやサービスと統合できるという点は、Google 広告スクリプトの優れた機能です。
このガイドでは、他のサービスに接続するスクリプトの作成に役立つ次のコンセプトについて説明します。
- HTTP リクエストの作成:
UrlFetchApp
を使用して外部 API にアクセスする方法。 - 認証: 一般的な認証シナリオについて説明します。
- レスポンスの解析: 返された JSON データと XML データの処理方法。
UrlFetchApp でデータを取得する
UrlFetchApp
は、サードパーティ API とのやり取りに必要なコア機能を提供します。
次の例では、OpenWeatherMap から気象データを取得しています。OpenWeatherMap を選択したのは、比較的シンプルな認証スキームと API であるためです。
リクエストを作成する
OpenWeatherMap のドキュメントでは、次のように現在の天気をリクエストする際の形式が規定されています。
http://api.openweathermap.org/data/2.5/weather?q=[location]&apikey=[apikey]
この URL は認可の最初の例です。パラメータ apikey
は必須で、値はユーザーごとに一意です。このキーは、登録によって取得できます。
登録後、次のようにキーを使用したリクエストを発行できます。
const location = 'London,uk';
const apikey = 'da.......................81'; // Replace with your API key
const currentWeatherUrl = `http://api.openweathermap.org/data/2.5/weather?q=${location}&apiKey=${apiKey}`;
const response = UrlFetchApp.fetch(currentWeatherUrl);
console.log(response.getContentText());
このコードを実行すると、Google 広告スクリプトのログ ウィンドウに長い JSON テキストが書き込まれます。
次のステップでは、これをスクリプト内で使用できる形式に変換します。
JSON データ
多くの API は JSON 形式でレスポンスを提供します。これは、JavaScript オブジェクトの単純なシリアル化を表します。たとえば、オブジェクト、配列、基本型を文字列として表したり、転送したりできます。
JSON 文字列(OpenWeatherMap から返される文字列など)を JavaScript オブジェクトに戻すには、組み込みの JSON.parse
メソッドを使用します。上記の例の続きを見てみましょう。
const json = response.getContentText();
const weatherData = JSON.parse(json);
console.log(weatherData.name);
// "London"
JSON.parse
メソッドは、文字列をプロパティ name
を持つオブジェクトに変換します。
さまざまな形式の API レスポンスを操作する方法について詳しくは、レスポンスを解析するセクションをご覧ください。
エラー処理
サードパーティの API は頻繁に変更され、予期しないレスポンス値が生成されることが多いため、スクリプトでサードパーティの API を使用する場合、エラー処理は重要な考慮事項です。次に例を示します。
- API の URL やパラメータは、知らないうちに変更される可能性があります。
- API キー(または他のユーザー認証情報)には有効期限があります。
- 回答の形式は予告なく変更される場合があります。
HTTP ステータス コード
予期しないレスポンスが発生する可能性があるため、HTTP ステータス コードを調べる必要があります。デフォルトでは、HTTP エラーコードが発生した場合、UrlFetchApp
は例外をスローします。この動作を変更するには、次の例のように省略可能なパラメータを渡す必要があります。
const options = {
muteHttpExceptions: true
}
const response = UrlFetchApp.fetch(url, options);
// Any status code greater or equal to 400 is either a client or server error.
if (response.getResponseCode() >= 400) {
// Error encountered, send an email alert to the developer
sendFailureEmail();
}
レスポンスの構造
サードパーティの API が変更された場合、多くの場合、デベロッパーはスクリプトに影響する可能性がある変更にすぐに気づかないことがあります。たとえば、OpenWeatherMap の例で返された name
プロパティが locationName
に変更された場合、このプロパティを使用するスクリプトは失敗します。
このため、返された構造が期待どおりかどうかをテストすることをおすすめします。次に例を示します。
const weatherData = JSON.parse(json);
if (weatherData && weatherData.name) {
console.log('Location is : ' + name);
} else {
console.log('Data not in expected format');
}
UrlFetchApp による POST データ
OpenWeatherMap の導入例では、データのみを取得しました。通常、リモート サーバーで状態を変更しない API 呼び出しでは、HTTP
GET
メソッドを使用します。
GET
メソッドは UrlFetchApp
のデフォルトです。ただし、SMS メッセージを送信するサービスの呼び出しなど、一部の API 呼び出しでは POST
や PUT
などの他のメソッドが必要になります。
UrlFetchApp
で POST
呼び出しを使用する例を次に示します。次の例では、コラボレーション メッセージ アプリケーションである Slack と統合して、Slack のユーザーとグループに Slack メッセージを送信する方法を示します。
Slack を設定
このガイドは、Slack アカウントにすでに登録していることを前提としています。
前の例の OpenWeatherMap と同様に、メッセージの送信を可能にするにはトークンを取得する必要があります。Slack では、着信 Webhook と呼ばれる、チームにメッセージを送信するための一意の URL が用意されています。
[着信 Webhook の追加] をクリックし、手順に沿って 着信 Webhook を設定します。このプロセスでは、メッセージに使用する URL を発行する必要があります。
POST リクエストを行う
受信 Webhook を設定したら、POST
リクエストを行うには、UrlFetchApp.fetch
に渡される options
パラメータでいくつかの追加プロパティを使用するだけで済みます。
method
: 前述のとおり、デフォルトはGET
ですが、ここではオーバーライドしてPOST
に設定します。payload
:POST
リクエストの一部としてサーバーに送信されるデータです。この例では、Slack のドキュメントで説明されているように、Slack は JSON 形式にシリアル化されたオブジェクトを想定しています。そのためには、JSON.stringify
メソッドを使用し、Content-Type
をapplication/json
に設定します。// Change the URL for the one issued to you from 'Setting up Slack'. const SLACK_URL = 'https://hooks.slack.com/services/AAAA/BBBB/CCCCCCCCCC'; const slackMessage = { text: 'Hello, slack!' }; const options = { method: 'POST', contentType: 'application/json', payload: JSON.stringify(slackMessage) }; UrlFetchApp.fetch(SLACK_URL, options);
拡張された Slack の例
上記の例は、Slack への受信メッセージを有効にする場合の最小要件を示しています。拡張サンプルは、キャンペーン パフォーマンス レポートを作成してグループに送信する方法、およびフォーマットや表示オプションを例示したものです。
Slack メッセージの詳細については、Slack のドキュメントのメッセージのフォーマットをご覧ください。
フォームデータ
上記の例では、POST
リクエストの payload
プロパティとして JSON 文字列を使用することが示されています。
UrlFetchApp
は、payload
の形式に応じて POST
リクエストの作成方法が異なります。
payload
が文字列の場合、文字列引数はリクエストの本文として送信されます。payload
がオブジェクト(値のマップなど)である場合:{to: 'mail@example.com', subject:'Test', body:'Hello, World!'}
Key-Value ペアは form-data に変換されます。
subject=Test&to=mail@example.com&body=Hello,+World!
また、リクエストの
Content-Type
ヘッダーがapplication/x-www-form-urlencoded
に設定されます。
一部の API では、POST リクエストの送信時にフォームデータを使用する必要があります。ここでは、JavaScript オブジェクトからフォームデータへの自動変換について説明します。
HTTP 基本認証
HTTP 基本認証は最もシンプルな認証形式の一つで、多くの API で使用されています。
認証は、エンコードされたユーザー名とパスワードを各リクエストの HTTP ヘッダーに添付して行います。
リクエストを作成する
認証されたリクエストを生成するには、次の手順が必要です。
- ユーザー名とパスワードをコロンで結合して、パスフレーズを形成します(例:
username:password
)。 - パスフレーズを Base64 でエンコードします。たとえば、
username:password
はdXNlcm5hbWU6cGFzc3dvcmQ=
になります。 Authorization
ヘッダーをAuthorization: Basic <encoded passphrase>
の形式でリクエストに追加します。
次のスニペットは、Google 広告スクリプトでこれを実現する方法を示しています。
const USERNAME = 'your_username';
const PASSWORD = 'your_password';
const API_URL = 'http://<place_api_url_here>';
const authHeader = 'Basic ' + Utilities.base64Encode(USERNAME + ':' + PASSWORD);
const options = {
headers: {Authorization: authHeader}
}
// Include 'options' object in every request
const response = UrlFetchApp.fetch(API_URL, options);
Plivo
Plivo は、API を介して SMS メッセージの送受信を容易にするサービスです。このサンプルは、メッセージの送信方法を示しています。
- Plivo に登録します。
- サンプル スクリプトを Google 広告の新しいスクリプトに貼り付けます。
PLIVO_ACCOUNT_AUTHID
とPLIVO_ACCOUNT_AUTHTOKEN
の値は、管理ダッシュボードの値に置き換えます。- エラー通知用のスクリプトで指定されているメールアドレスを挿入します。
- Plivo を使用するには、トライアル アカウントに番号を購入するか、番号を追加する必要があります。トライアル アカウントで使用できるサンドボックス番号を追加します。
- 送信者として表示される番号と受信者の番号の両方を追加します。
- スクリプトの
PLIVO_SRC_PHONE_NUMBER
を、登録したサンドボックス番号のいずれかに更新します。国際国コードを含める必要があります。たとえば、英国の電話番号の場合は447777123456
です。
Twilio
Twilio は、API を介した SMS メッセージの送受信を容易にするもう一つのサービスです。このサンプルは、メッセージの送信方法を示しています。
- Twillio に登録します。
- サンプル スクリプトを Google 広告の新しいスクリプトに貼り付けます。
TWILIO_ACCOUNT_SID
とTWILIO_ACCOUNT_AUTHTOKEN
の値は、アカウント コンソール ページに表示されている値に置き換えます。TWILIO_SRC_PHONE_NUMBER
は、ダッシュボードの番号に置き換えます。これは、Twilio にメッセージの送信が許可される番号です。
OAuth 1.0
一般的なサービスの多くは、認証に OAuth を使用します。OAuth にはさまざまなフレーバーとバージョンがあります。
HTTP 基本認証では、ユーザーが持つユーザー名とパスワードは 1 つのみです。一方、OAuth では、サードパーティ アプリケーションに固有の認証情報を使用して、サードパーティ アプリケーションにユーザーのアカウントとデータへのアクセスを許可できます。また、アクセスの範囲はそのアプリケーションに固有のものになります。
OAuth 1.0 の背景情報については、OAuth Core ガイドをご覧ください。特に、6. OAuth による認証」をご覧ください。完全な 3-legged OAuth 1.0 では、プロセスは次のようになります。
- アプリケーション(「コンシューマ」)がリクエスト トークンを取得します。
- ユーザーがリクエスト トークンを承認します。
- アプリケーションはリクエスト トークンをアクセス トークンと交換します。
- 後続のすべてのリソース リクエストでは、署名付きリクエストにアクセス トークンが使用されます。
サードパーティ サービスでユーザー操作なしで OAuth 1.0 を使用する場合(Google 広告スクリプトで行う場合など)は、手順 1、2、3 は行えません。したがって、一部のサービスは構成コンソールからアクセス トークンを発行します。これにより、アプリケーションはステップ 4 に直接移動できます。これは one-legged OAuth 1.0 です。
Google 広告スクリプトでの OAuth 1.0
Google 広告スクリプトの場合、通常、各スクリプトはアプリケーションとして解釈されます。 サービスのコンソールまたは管理設定ページで、通常、次のことを行う必要があります。
- スクリプトを表すアプリケーション構成を設定します。
- スクリプトに拡張する権限を指定します。
- one-legged OAuth で使用するコンシューマー キー、コンシューマー シークレット、アクセス トークン、アクセス シークレットを取得します。
OAuth 2.0
OAuth 2.0 は、一般的な API でユーザーデータへのアクセスを可能にするために使用されます。特定のサードパーティ サービスのアカウントの所有者は、特定のアプリにユーザーデータへのアクセスを許可する権限を付与します。オーナーには次のようなメリットがあります。
- アカウントの認証情報をアプリケーションと共有する必要がない。
- どのアプリケーションが、どの程度までデータにアクセスできるかを個別に制御できる。(たとえば、付与されるアクセス権が読み取り専用の場合や、データのサブセットのみの場合などがあります)。
OAuth 2.0 対応サービスを Google 広告スクリプトで使用する手順は次のとおりです。
- スクリプトの外部
Google 広告スクリプトに、第三者 API 経由でユーザーデータへのアクセスを許可します。ほとんどの場合、サードパーティ サービスのコンソールでアプリケーションを設定します。このアプリケーションは Google 広告スクリプトを表しています。
Google 広告スクリプト アプリケーションに付与するアクセス権を指定します。通常はクライアント ID が割り当てられます。これにより、OAuth 2 を介して、サードパーティ サービス内のデータにアクセスできるアプリケーションと、そのデータのどの部分が表示または変更できるかを制御できます。
- スクリプト
リモート サーバーで認証する。サーバーが許可した権限付与タイプに応じて、フローと呼ばれる異なる手順を実行する必要がありますが、いずれの場合も最終的にアクセス トークンが発行され、後続のリクエストでそのセッションが使用されます。
API リクエストを行う。リクエストごとにアクセス トークンを渡します。
認可フロー
権限付与タイプとそれぞれのフローは、さまざまな使用シナリオに対応しています。たとえば、ユーザーがインタラクティブ セッションに参加している場合は、ユーザーがいない状況でアプリをバックグラウンドで実行する必要があるケースとは対照的に、ユーザーがインタラクティブ セッションに参加している場合は、別のフローが使用されます。
API プロバイダは受け入れる権限付与タイプを決定します。これは、ユーザーが API の統合を進める際の指針となります。
実装
どの OAuth フローでも、残りのセッションでリクエストを認証するために使用できるアクセス トークンを取得することが目的です。
サンプル ライブラリは、異なるフロータイプごとの認証方法を示しています。これらの各メソッドは、アクセス トークンを取得して保存し、認証済みリクエストを容易にするオブジェクトを返します。
一般的な使用パターンは次のとおりです。
// Authenticate using chosen flow type
const urlFetchObj = OAuth2.<flow method>(args);
// Make request(s) using obtained object.
const response1 = urlFetchObj.fetch(url1);
const response2 = urlFetchObj.fetch(url2, options);
クライアント認証情報の付与
クライアント認証情報の付与は、より単純な形式の OAuth2 フローの一つです。このフローでは、時間制限付きのアクセス トークンの発行と引き換えに、アプリケーションに固有の ID とシークレットを交換します。
// Access token is obtained and cached.
const authUrlFetch = OAuth2.withClientCredentials(
tokenUrl, clientId, clientSecret, optionalScope));
// Use access token in each request
const response = authUrlFetch.fetch(url);
// ... use response
更新トークンの付与
更新トークンの付与は、クライアント認証情報の付与に似ています。サーバーへの単純なリクエストによって、セッションで使用できるアクセス トークンが返されるためです。
更新トークンを取得する
更新トークンの付与との違いは、クライアント認証情報の付与に必要とされる詳細情報がアプリケーションの構成(サービスのコントロール パネルなど)から取得されるのに対し、更新トークンはユーザーの操作を必要とする認可コード付与など、より複雑なフローの一部として付与されることです。
- OAuth Playground を使用して更新トークンを取得する
OAuth2 Playground には、ユーザーが認可コード付与をステップ実行して更新トークンを取得できる UI が用意されています。
右上の設定ボタンをクリックすると、OAuth フローで使用するすべてのパラメータを定義できます。これには、次のようなものがあります。
- 認可エンドポイント: 認可フローの開始に使用されます。
- トークン エンドポイント: アクセス トークンを取得するために更新トークンとともに使用されます。
- client ID and secret: アプリケーションの認証情報。
- スクリプトを使用して更新トークンを取得する
フローを完了するためのスクリプトベースの代替手段として、更新トークンの生成サンプルが用意されています。
更新トークンの使用状況
最初の承認が行われると、サービスは更新トークンを発行できます。このトークンは、クライアント認証情報フローと同様の方法で使用できます。以下に 2 つの例を示します。
const authUrlFetch = OAuth2.withRefreshToken(tokenUrl, clientId, clientSecret,
refreshToken, optionalScope);
const response = authUrlFetch.fetch(url);
// ... use response
検索広告 360 の例
検索広告 360 は、更新トークンとともに使用できる API の一例です。 このサンプルでは、スクリプトがレポートを生成して返します。実行できるその他のアクションについて詳しくは、Search Ads 360 API リファレンスをご覧ください。
スクリプトを作成する
- API Console で新しいプロジェクトを作成し、DoubleClick ガイドの手順に沿ってクライアント ID、クライアント シークレット、更新トークンを取得します。その際、必ず DoubleClick Search API を有効にします。
- サンプル スクリプトを Google 広告の新しいスクリプトに貼り付けます。
- コードリストの下にサンプル OAuth2 ライブラリを貼り付けます。
- クライアント ID、クライアント シークレット、更新トークンに正しい値が含まれるようにスクリプトを修正します。
Apps Script Execution API の例
この例では、Apps Script Execution API を使用して Apps Script で関数を実行する方法を説明します。これにより、Google 広告スクリプトから Apps Script を呼び出せるようになります。
Apps Script スクリプトを作成する
新しいスクリプトを作成します。次のサンプルでは、ドライブから 10 個のファイルを一覧表示します。
function listFiles() {
const limit = 10;
const files = [];
const fileIterator = DriveApp.getFiles();
while (fileIterator.hasNext() && limit) {
files.push(fileIterator.next().getName());
limit--;
}
return files;
}
Apps Script の実行を構成する
- スクリプトを保存します。
- [リソース] > [Cloud Platform プロジェクト] をクリックします。
- プロジェクト名をクリックして API Console に移動します。
- [API とサービス] に移動します。
- 適切な API(この場合は Drive API と Apps Script Execution API)を有効にします。
- メニューの [認証情報] 項目から OAuth 認証情報を作成します。
- スクリプトに戻り、[Publish] > [Deploy as API Executable] からスクリプトを公開します。
Google 広告スクリプトを作成する
- サンプル スクリプトを Google 広告の新しいスクリプトに貼り付けます。
- さらに、コードリストの下にサンプル OAuth2 ライブラリを貼り付けます。
- クライアント ID、クライアント シークレット、更新トークンに正しい値が含まれるようにスクリプトを修正します。
サービス アカウント
上記の権限付与タイプの代わりにサービス アカウントのコンセプトを使用できます。
サービス アカウントは、ユーザーデータへのアクセスに使用されないという点で上記と異なります。認証後、リクエストは、プロジェクトを所有するユーザーではなく、アプリケーションに代わってサービス アカウントによって行われます。たとえば、サービス アカウントが Drive API を使用してファイルを作成した場合、これはサービス アカウントに属し、デフォルトではプロジェクトのオーナーはアクセスできません。
Google Natural Language API の例
Natural Language API は、テキストの感情分析とエンティティ分析を行います。
この例は、広告見出しや説明文などの広告文の感情を計算する方法を示しています。これにより、メッセージがどの程度ポジティブか、メッセージの大きさが測量されます。「ケーキを販売している」と「ロンドンで一番おいしいケーキを販売しています。いますか?
スクリプトを設定する
- API Console で新しいプロジェクトを作成する
- Natural Language API を有効にします。
- プロジェクトの課金を有効にします。
- サービス アカウントを作成します。認証情報の JSON ファイルをダウンロードします。
- このサンプル スクリプトを Google 広告の新しいスクリプトに貼り付けます。
- さらに、コードリストの下にサンプル OAuth2 ライブラリを貼り付けます。
- 必要な値を置き換えます。
serviceAccount
: サービス アカウントのメールアドレス(例:xxxxx@yyyy.iam.gserviceaccount.com
)。key
: サービス アカウントの作成時にダウンロードされた JSON ファイルのキー。-----BEGIN PRIVATE KEY...
から...END PRIVATE KEY-----\n
まで。
API レスポンス
API はさまざまな形式でデータを返すことができます。特に注目すべきは XML と JSON です。
JSON
JSON は通常、レスポンス形式として扱うために XML よりもシンプルです。ただし、まだいくつか問題が発生することがあります。
レスポンスの検証
API 呼び出しから正常なレスポンスを取得したら、通常、JSON.parse
を使用して JSON 文字列を JavaScript オブジェクトに変換します。この時点で、解析に失敗したケースに対処することをおすすめします。
const json = response.getContentText();
try {
const data = JSON.parse(json);
return data;
} catch(e) {
// Parsing of JSON failed - handle error.
}
また、API がユーザーの制御下にない場合は、レスポンスの構造が変更され、プロパティがこれ以上存在しなくなる可能性があることを考慮してください。
// Less good approach
// Assumes JSON was in form {"queryResponse": ...} when parsed.
const answer = data.queryResponse;
// Better approach
if (data && data.queryResponse) {
const answer = data.queryResponse;
} else {
// Format of API response has changed - alert developer or handle accordingly
}
XML
検証
XML は、今でも API をビルドするための一般的な形式です。API 呼び出しからのレスポンスは、XmlService の parse
メソッドを使用して解析できます。
const responseText = response.getContentText();
try {
const document = XmlService.parse(responseText);
} catch(e) {
// Error in XML representation - handle accordingly.
}
XmlService.parse
は XML のエラーを検出し、それに応じて例外をスローしますが、スキーマに照らして XML を検証する機能は提供されません。
ルート要素
XML ドキュメントの解析が正常に完了したら、getRootElement()
メソッドを使用してルート要素を取得します。
const document = XmlService.parse(responseText);
const rootElement = document.getRootElement();
Namespace
次の例では、Sportradar API を使用して、選択した試合のサッカーの結果を取得しています。XML レスポンスの形式は次のとおりです。
<schedule xmlns="http://feed.elasticstats.com/schema/soccer/sr/v2/matches-schedule.xsd">
<matches>
...
</matches>
</schedule>
ルート要素で Namespace がどのように指定されているかに注目してください。このため、以下を行う必要があります。
- ドキュメントから名前空間属性を抽出します。
- この名前空間は、子要素を走査してアクセスするときに使用します。
次のサンプルは、上記のドキュメント スニペットの <matches>
要素にアクセスする方法を示しています。
const document = XmlService.parse(xmlText);
const scheduleElement = document.getRootElement();
// The namespace is required for accessing child elements in the schema.
const namespace = scheduleElement.getNamespace();
const matchesElement = scheduleElement.getChild('matches', namespace);
値を取得する
フットボールのスケジュールのサンプルの場合:
<match status="..." category="..." ... >
...
</match>
次のような属性を取得できます。
const status = matchElement.getAttribute('status').getValue();
要素内のテキストは getText()
を使用して読み取ることができますが、要素内に複数のテキストの子がある場合には連結されます。複数のテキストの子がある可能性が高い場合は、getChildren()
を使用して、各子に対して反復処理することを検討してください。
Sportradar の例
この Sportradar の例では、サッカーの試合、特にイングランド プレミアリーグの試合の詳細を取得しています。Soccer API は、Sportradar が提供している幅広いスポーツ フィードの 1 つです。
Sportradar アカウントの設定
- Sportradar のデベロッパー サイトに移動します。
- トライアル アカウントに登録します。
- 登録が済んだら、アカウントにログインします。
- ログインしたら、MyAccount に移動します。
Sportradar は、さまざまなスポーツを異なる API に分けます。たとえば、Socer API へのアクセス権を購入して、Tennis API へのアクセス権を購入しないようにできます。作成するアプリケーションごとに、さまざまなスポーツとさまざまなキーを関連付けることができます。
- [Applications] で [Create a new Application] をクリックします。アプリケーションに名前と説明を設定します。ウェブサイト フィールドは無視されます。
- [Issue a new key for Soccer Trial Europe v2] のみを選択します。
- [Register Application] をクリックします。
正常に完了すると、新しい API キーが設定されたページが表示されます。
- サンプル スクリプトを Google 広告の新しいスクリプトに貼り付けます。
- リスト内の API キーを上記で取得したキーに置き換え、メールアドレス フィールドを編集します。
トラブルシューティング
サードパーティの API を使用する場合、次のようなさまざまな理由でエラーが発生します。
- API で想定されない形式でサーバーにリクエストを発行するクライアント。
- クライアントが想定しているレスポンス形式とは異なる形式になっている。
- 無効なトークンまたはキーを使用している、またはプレースホルダとして残っている値を使用しているクライアント。
- クライアントが使用量上限に達した。
- クライアントが無効なパラメータを提供している。
上記いずれの場合も、問題の原因を特定するには、エラーの原因となるレスポンスの詳細を調べることが最初のステップとなります。
レスポンスを解析する
デフォルトでは、エラー(ステータス コード 400 以上)を返すレスポンスは、すべて Google 広告スクリプト エンジンによってスローされます。
この動作を回避し、エラーとエラー メッセージを検査できるようにするには、オプション パラメータの muteHttpExceptions
プロパティを UrlFetchApp.fetch
に設定します。例:
const params = {
muteHttpExceptions: true
};
const response = UrlFetchApp.fetch(url, params);
if (response.getResponseCode() >= 400) {
// ... inspect error details...
}
一般的なステータス コード
200 OK
は成功を示します。レスポンスに目的のデータが含まれていない場合は、次の点を考慮してください。- 一部の API では、使用するフィールドやレスポンス形式を指定できます。詳しくは、API ドキュメントをご覧ください。
- API には、呼び出すことができる複数のリソースがある場合があります。ドキュメントを参照して、別のリソースのほうが適しているかどうかを判断すると、必要なデータが返されます。
- コードの作成後に API が変更された可能性があります。詳しくは、ドキュメントまたはデベロッパーにお問い合わせください。
400 Bad Request
は通常、サーバーに送信されたリクエストの形式や構造に誤りがあります。リクエストを検査し、API 仕様と比較し、想定どおりであることを確認します。リクエストの調査方法について詳しくは、リクエストの検査をご覧ください。401 Unauthorized
は通常、認証の提供または正常に実行せずに API が呼び出されていることを意味します。- API で基本認証を使用する場合は、
Authorization
ヘッダーが作成され、リクエストで指定されていることを確認します。 - API が OAuth 2.0 を使用する場合は、アクセス トークンが取得され、署名なしトークンとして提供されていることを確認します。
- 承認に関する他のバリエーションでは、リクエストに必要な認証情報が指定されていることを確認してください。
- API で基本認証を使用する場合は、
403 Forbidden
は、リクエストされたリソースに対する権限がユーザーに付与されていないことを示します。- ファイルベースのリクエストでユーザーにファイルへのアクセスを許可するなど、必要な権限がユーザーに付与されていることを確認します。
404 Not Found
は、リクエストされたリソースが存在しないことを意味します。- API エンドポイントに使用されている URL が正しいことを確認します。
- リソースを取得する場合は、参照されているリソースが存在することを確認します(たとえば、ファイルベースの API 用のファイルが存在するかどうか)。
リクエストを検査する
リクエストの調査は、リクエストの形式が正しくないことが API レスポンスに示されている場合(400 ステータス コードなど)に役立ちます。リクエストを調べるために、UrlFetchApp
には fetch()
メソッドのコンパニオン メソッドである getRequest()
があります。
このメソッドは、サーバーにリクエストを送信するのではなく、送信されたリクエストを作成して返します。これにより、ユーザーはリクエストの要素を調べて、リクエストが正しく表示されているかどうかを確認できます。
たとえば、リクエストのフォームデータが連結された多数の文字列で構成されている場合、そのフォームデータを生成するために作成した関数にエラーがある可能性があります。簡単に言うと、次のようになります。
const request = UrlFetchApp.getRequest(url, params);
console.log(request);
// Now make the fetch:
const response = UrlFetchApp.fetch(url, params);
// ...
リクエストの要素を調べることができます。
リクエストとレスポンスをログに記録する
サードパーティ API へのリクエストとレスポンスを検査するプロセス全体をサポートするために、次のヘルパー関数を UrlFetchApp.fetch()
の代わりに使用できます。これにより、リクエストとレスポンスの両方をログに記録できます。
コード内の
UrlFetchApp.fetch()
のすべてのインスタンスをlogUrlFetch()
に置き換えます。スクリプトの末尾に次の関数を追加します。
function logUrlFetch(url, opt_params) { const params = opt_params || {}; params.muteHttpExceptions = true; const request = UrlFetchApp.getRequest(url, params); console.log('Request: >>> ' + JSON.stringify(request)); const response = UrlFetchApp.fetch(url, params); console.log('Response Code: <<< ' + response.getResponseCode()); console.log('Response text: <<< ' + response.getContentText()); if (response.getResponseCode() >= 400) { throw Error('Error in response: ' + response); } return response; }
スクリプトを実行すると、すべてのリクエストとレスポンスの詳細がコンソールに記録されるため、デバッグが容易になります。