このページは Cloud Translation API によって翻訳されました。

サードパーティ API

サードパーティ 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 ヘッダーに添付して行います。

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 です。

OAuth1

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: アプリケーションの認証情報。

OAuth2 Playground

スクリプトを使用して更新トークンを取得する

フローを完了するためのスクリプトベースの代替手段として、更新トークンの生成サンプルが用意されています。

更新トークンの使用状況

最初の承認が行われると、サービスは更新トークンを発行できます。このトークンは、クライアント認証情報フローと同様の方法で使用できます。以下に 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 を使用する場合は、アクセストークンが取得され、署名なしトークンとして提供されていることを確認します。
- 承認に関する他のバリエーションでは、リクエストに必要な認証情報が指定されていることを確認してください。
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;
}

スクリプトを実行すると、すべてのリクエストとレスポンスの詳細がコンソールに記録されるため、デバッグが容易になります。

サードパーティ API

UrlFetchApp でデータを取得する

リクエストを作成する

JSON データ

エラー処理

HTTP ステータス コード

レスポンスの構造

UrlFetchApp による POST データ

Slack を設定

POST リクエストを行う

拡張された Slack の例

フォームデータ

HTTP 基本認証

リクエストを作成する

Plivo

Twilio

OAuth 1.0

Google 広告スクリプトでの OAuth 1.0

OAuth 2.0

認可フロー

実装

クライアント認証情報の付与

更新トークンの付与

更新トークンを取得する

更新トークンの使用状況

検索広告 360 の例

スクリプトを作成する

Apps Script Execution API の例

Apps Script スクリプトを作成する

Apps Script の実行を構成する

Google 広告スクリプトを作成する

サービス アカウント

Google Natural Language API の例

スクリプトを設定する

API レスポンス

JSON

レスポンスの検証

XML

検証

ルート要素

Namespace

値を取得する

Sportradar の例

Sportradar アカウントの設定

トラブルシューティング

レスポンスを解析する

一般的なステータス コード

リクエストを検査する

リクエストとレスポンスをログに記録する

HTTP ステータスコード

サービスアカウント

一般的なステータスコード