サードパーティ API

Google 広告スクリプトの強力な機能の一つは、サードパーティ API のデータやサービスと統合できることです。

このガイドでは、他のサービスに接続するスクリプトを作成する際に役立つ次のコンセプトについて説明します。

  • HTTP リクエストの作成: UrlFetchApp を使用して外部 API にアクセスする方法。
  • 認証: 一般的な認証シナリオについて説明します。
  • レスポンスの解析: 返された JSON データと XML データを処理する方法。

また、これらのコンセプトを説明する、一般的な API のサンプルも含まれています。

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 オブジェクトのシリアル化を表します。これにより、オブジェクト、配列、基本型を文字列として表現して転送できます。

OpenWeatherMap から返された JSON 文字列を 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 には、チームにメッセージを送信できる一意の URL が用意されています。これは受信 Webhook と呼ばれます。

[Add Incoming WebHooks Integration] をクリックし、手順に沿って受信 Webhook を設定します。このプロセスでは、メッセージに使用する URL を発行する必要があります。

POST リクエストを行う

受信 Webhook を設定したら、POST リクエストを行うには、UrlFetchApp.fetch に渡される options パラメータで追加のプロパティを使用する必要があります。

  • method: 前述のように、デフォルトは GET ですが、ここではオーバーライドして POST に設定します。
  • payload: POST リクエストの一部としてサーバーに送信されるデータです。この例では、Slack は Slack のドキュメントに記載されているように、JSON 形式にシリアル化されたオブジェクトを想定しています。このために、[JSON.stringify][json-stringify-url] メソッドが使用され、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 文字列を使用する方法を示しました。

payload の形式に応じて、UrlFetchApp は 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 基本認証は、最もシンプルな認証形式の 1 つであり、多くの API で使用されています。

認証は、エンコードされたユーザー名とパスワードを各リクエストの HTTP ヘッダーに添付することで行われます。

HTTP 基本認証

リクエストを作成する

認証済みリクエストを生成するには、次の手順が必要です。

  1. ユーザー名とパスワードをコロンで結合してパスフレーズを作成します(例: username:password)。
  2. パスフレーズを Base64 でエンコードします。たとえば、username:password は dXNlcm5hbWU6cGFzc3dvcmQ= になります。
  3. Authorization: Basic <encoded passphrase> 形式で Authorization ヘッダーをリクエストに添付します。

次のスニペットは、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);

基本認証のサンプル

コードサンプル セクションには、HTTP Basic Authentication の使用方法を示す 2 つのサンプルが含まれています。

Plivo

Plivo は、API を使用して SMS メッセージの送受信を容易にするサービスです。このサンプルは、メッセージの送信を示しています。

  1. Plivo に登録します。
  2. サンプル スクリプトを Google 広告の新しいスクリプトに貼り付けます。
  3. PLIVO_ACCOUNT_AUTHID と PLIVO_ACCOUNT_AUTHTOKEN の値は、管理ダッシュボードの値に置き換えます。
  4. エラーの通知用に、スクリプトで指定されているメールアドレスを挿入します。
  5. Plivo を使用するには、番号を購入するか、トライアル アカウントに番号を追加する必要があります。トライアル アカウントで使用できるサンドボックス番号を追加します。
  6. 送信者として表示される番号と受信者の番号の両方を追加します。
  7. スクリプトの PLIVO_SRC_PHONE_NUMBER を、登録したサンドボックス番号のいずれかに更新します。これには、国際国コード(英国の番号の場合は 447777123456 など)を含める必要があります。

Twilio

Twilio は、API を使用して SMS メッセージの送受信を容易にするもう 1 つのサービスです。このサンプルは、メッセージの送信を示しています。

  1. Twillio に登録します。
  2. サンプル スクリプトを Google 広告の新しいスクリプトに貼り付けます。
  3. TWILIO_ACCOUNT_SID と TWILIO_ACCOUNT_AUTHTOKEN の値は、アカウント コンソール ページに表示される値に置き換えます。
  4. 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 のプロセスは次のとおりです。

  1. アプリケーション(「コンシューマ」)がリクエスト トークンを取得します。
  2. ユーザーがリクエスト トークンを承認します。
  3. アプリケーションがリクエスト トークンをアクセス トークンと交換します。
  4. 後続のすべてのリソース リクエストでは、アクセス トークンが署名付きリクエストで使用されます。

サードパーティ サービスがユーザー操作なしで OAuth 1.0 を使用する場合(Google 広告スクリプトで必要となる場合など)、ステップ 1、2、3 は実行できません。そのため、一部のサービスでは、構成コンソールからアクセス トークンを発行し、アプリケーションが直接ステップ 4 に進むことができるようにしています。これは、1-legged OAuth 1.0 と呼ばれます。

OAuth1

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

Google 広告スクリプトの場合、通常、各スクリプトはアプリケーションとして解釈されます。サービスのコンソールまたは管理設定ページで、通常は次の操作を行う必要があります。

  • スクリプトを表すアプリケーション構成を設定します。
  • スクリプトに拡張する権限を指定します。
  • 1 レッグ OAuth で使用するコンシューマ キー、コンシューマ シークレット、アクセス トークン、アクセス シークレットを取得します。

OAuth 2.0

OAuth 2.0 は、一般的な API でユーザーデータへのアクセスを提供するために使用されます。特定のサードパーティ サービスのアカウントの所有者が、特定のアプリケーションにユーザーデータへのアクセスを許可します。オーナーにとってのメリットは次のとおりです。

  • アカウントの認証情報をアプリケーションと共有する必要がない。
  • データにアクセスできるアプリケーションを個別に制御し、アクセスの範囲を制御できます。(たとえば、付与されるアクセス権が読み取り専用の場合や、データの一部のみにアクセスできる場合があります)。

Google 広告スクリプトで OAuth 2.0 対応サービスを使用する手順は次のとおりです。

スクリプトの外部

サードパーティ API を介して Google 広告スクリプトがユーザーデータにアクセスすることを承認します。ほとんどの場合、これにはサードパーティ サービスのコンソールでアプリケーションを設定する必要があります。このアプリケーションはスクリプトを表します。

Google 広告スクリプトアプリケーションに付与するアクセス権を指定すると、通常はクライアント ID が割り当てられます。これにより、OAuth 2.0 を介して、サードパーティ サービス内のデータにアクセスできるアプリケーションと、それらのアプリケーションが表示または変更できるデータの側面を制御できます。

スクリプト内

リモート サーバーで承認する。サーバーで許可されている権限付与タイプに応じて、フローと呼ばれる一連の手順を実行する必要がありますが、最終的には、そのセッションの以降のすべてのリクエストで使用されるアクセス トークンが発行されます。

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);

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

[クライアント認証情報の権限付与][client-credentials-rfc] は、OAuth2 フローのよりシンプルな形式の 1 つです。このフローでは、アプリケーションがアプリケーションに固有の 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

更新トークン付与

更新トークン権限付与は、サーバーへのリクエストがセッションで使用できるアクセス トークンを返すという点で、クライアント認証情報権限付与に似ています。

更新トークン

更新トークンを取得する

更新トークン権限付与との違いは、クライアント認証情報権限付与に必要な詳細情報はアプリケーション構成(サービスのコントロール パネルなど)から取得されるのに対し、更新トークンは、[認証コード権限付与][authorization-code-rfc] などのより複雑なフローの一部として付与される点です。このフローでは、ユーザー操作が必要になります。

認証コード

OAuth Playground を使用して更新トークンを取得する

OAuth2 Playground には、ユーザーが認証コードの付与をステップ実行して更新トークンを取得できる UI が用意されています。

右上の設定ボタンを使用すると、OAuth フローで使用するすべてのパラメータを定義できます。

  • 認可エンドポイント: 認可フローの開始点として使用されます。
  • トークン エンドポイント: 更新トークンとともに使用して、アクセス トークンを取得します。
  • クライアント ID とシークレット: アプリケーションの認証情報。

    OAuth2 Playground

更新トークンの使用

最初の認可が実行されると、サービスは更新トークンを発行できます。このトークンは、クライアント認証情報フローと同様の方法で使用できます。

const authUrlFetch = OAuth2.withRefreshToken(tokenUrl, clientId, clientSecret,
    refreshToken, optionalScope);
const response = authUrlFetch.fetch(url);
// ... use response

検索広告 360 の例

検索広告 360 は、更新トークンで使用できる API の一例です。このサンプルでは、スクリプトがレポートを生成して返します。実行可能なその他のアクションの詳細については、Search Ads 360 API リファレンスをご覧ください。

スクリプトを作成する
  1. Google Cloud コンソールで新しいプロジェクトを作成し、検索広告 360 ガイドの手順に沿ってクライアント ID、クライアント シークレット、更新トークンを取得します。その際、Search Ads 360 API を有効にしてください。
  2. [サンプル スクリプト][search-ads-360-example] を Google 広告の新しいスクリプトに貼り付けます。
  3. コードリストの下に [OAuth2 ライブラリのサンプル][oauth20-library-example] を貼り付けます。
  4. クライアント 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 を構成する
  1. スクリプトを保存します。
  2. [リソース] > [Cloud Platform プロジェクト] をクリックします。
  3. プロジェクト名をクリックして、Google Cloud コンソールに移動します。
  4. [API とサービス] に移動します。
  5. 適切な API(この場合は Drive API と Apps Script Execution API)を有効にします。
  6. メニューの [認証情報] 項目から OAuth 認証情報を作成します。
  7. スクリプトに戻り、[公開] > [API 実行可能ファイルとしてデプロイ] を選択して、スクリプトを公開します。
Google 広告スクリプトを作成する
  1. サンプル スクリプトを Google 広告の新しいスクリプトに貼り付けます。
  2. また、コードリストの下に [OAuth2 ライブラリのサンプル][oauth20-library-example] を貼り付けます。
  3. クライアント ID、クライアント シークレット、更新トークンの正しい値が含まれるようにスクリプトを修正します。

サービス アカウント

権限付与タイプの代わりに、サービス アカウントのコンセプトを使用することもできます。

サービス アカウントは、ユーザーデータへのアクセスに使用されないという点で権限付与タイプとは異なります。認証後、リクエストは、プロジェクトを所有するユーザーとしてではなく、アプリケーションに代わってサービス アカウントによって行われます。たとえば、サービス アカウントが Drive API を使用してファイルを作成する場合、このファイルはサービス アカウントに属し、デフォルトではプロジェクトのオーナーはアクセスできません。

Google Natural Language API の例

[Natural Language API][natural-language-api-docs] は、テキストの [感情分析][sentiment-analysis-api-docs] と [エンティティ分析][entity-analysis-api-docs] を提供します。

この例では、広告テキスト(広告見出しや説明文など)の [感情][sentiment-api-docs]を計算する方法を示します。これにより、メッセージのポジティブさとメッセージの大きさを測定できます。We sell cakes と We sell the best cakes in London. ご注文はこちらから!

スクリプトを設定する
  1. Google Cloud コンソールで新しいプロジェクトを作成します。
  2. [Natural Language API][natural-language-api] を有効にします。
  3. プロジェクトの課金を有効にします。
  4. [サービス アカウントを作成する][create-service-account]。認証情報 JSON ファイルをダウンロードします。
  5. [サンプル スクリプト][natural-language-example] を Google 広告の新しいスクリプトに貼り付けます。
  6. また、コードリストの下に [OAuth2 ライブラリのサンプル][oauth20-library-example] を貼り付けます。
  7. 必要な値を置き換えます。
    • 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

XmlService を使用すると、スクリプトで 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();

名前空間

次の例では、Sportradar API を使用して、選択した試合のサッカーの結果を取得します。XML レスポンスの形式は次のとおりです。

<schedule_schedules xmlns="http://schemas.sportradar.com/sportsapi/soccer/v4">
  <schedule>
     ...
  </schedule>
</schedule_schedules>

ルート要素で名前空間がどのように指定されているかに注目してください。そのため、次のことを行う必要があります。

  • ドキュメントから名前空間属性を抽出します。
  • 子要素を走査してアクセスする場合は、この名前空間を使用します。

次のサンプルは、<schedule> 要素にアクセスし、前述のドキュメント スニペットでその <sport_event> 子要素を検索する方法を示しています。

const document = XmlService.parse(xmlText);
const rootElement = document.getRootElement();
// The namespace is required for accessing child elements in the schema.
const namespace = rootElement.getNamespace();
const scheduleElement = rootElement.getChild('schedule', namespace);
const sportEvents = scheduleElement.getChildren('sport_event', namespace);

値を取得する

サッカーのスケジュールのサンプルを例に取ります。

<sport_event_status status="..." ... />

属性は、たとえば次のように取得できます。

const statusElement = sportEventElement.getChild('sport_event_status', namespace);
const status = statusElement.getAttribute('status').getValue();

要素に含まれるテキストは getText() を使用して読み取ることができますが、要素に複数の子テキストがある場合は、それらが連結されます。複数のテキスト子要素が存在する可能性がある場合は、getChildren() を使用して各子要素を反復処理することを検討してください。

Sportradar の例

この完全な Sportradar の例では、サッカーの試合(具体的にはイングランド プレミア リーグの試合)の詳細を取得する方法を示しています。Soccer API は、Sportradar が提供する幅広いスポーツ フィードの 1 つです。

Sportradar アカウントを設定する
  1. Sportradar デベロッパー サイトに移動します。
  2. トライアル アカウントに登録します。
  3. 登録が完了したら、アカウントにログインします。
  4. ログインしたら、[My Account] に移動します。

Sportradar は、スポーツごとに異なる API に分割しています。たとえば、Soccer API へのアクセス権を購入しても、Tennis API へのアクセス権は購入しない場合があります。作成する各 Application には、異なるスポーツと異なるキーを関連付けることができます。

  1. [Applications] で [Create a new Application] をクリックします。アプリケーションに名前と説明を付け、ウェブサイト フィールドは無視します。
  2. [Issue a new key for Soccer Trial Europe v2] のみを選択します。
  3. [Register Application] をクリックします。

成功すると、新しい API キーが記載されたページが表示されます。

  1. サンプル スクリプトを Google 広告の新しいスクリプトに貼り付けます。
  2. リスティングの 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(url, params) が用意されています。

このメソッドは、サーバーにリクエストを送信する代わりに、送信されるはずだったリクエストを作成して返します。これにより、ユーザーはリクエストの要素を検査して、リクエストが正しいことを確認できます。

たとえば、リクエストのフォームデータが多数の文字列を連結したものである場合、そのフォームデータを生成するために作成した関数にエラーがある可能性があります。簡単に言うと、

const request = UrlFetchApp.getRequest(url, params);
console.log(request);
// Now make the fetch:
const response = UrlFetchApp.fetch(url, params);
// ...

を使用すると、リクエストの要素を検査できます。

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

サードパーティ API へのリクエストとレスポンスを検査するプロセス全体を支援するために、次のヘルパー関数を UrlFetchApp.fetch() のドロップイン置換として使用して、リクエストとレスポンスの両方をロギングできます。

  1. コード内の UrlFetchApp.fetch() のすべてのインスタンスを logUrlFetch() に置き換えます。

  2. スクリプトの末尾に次の関数を追加します。

    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;
    }
    

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

[json-stringify-url]: //developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify [client-credentials-rfc]: //datatracker.ietf.org/doc/html/rfc6749#section-4.4 [authorization-code-rfc]: //datatracker.ietf.org/doc/html/rfc6749#section-1.3.1 [oauth20-library-example]: /google-ads/scripts/docs/examples/oauth20-library [search-ads-360-example]: /google-ads/scripts/docs/examples/search-ads-360 [natural-language-api]: //console.developers.google.com/apis/api/language.googleapis.com/overview [create-service-account]: //console.developers.google.com/apis/credentials/serviceaccountkey [natural-language-example]: /google-ads/scripts/docs/examples/natural-language [natural-language-api-docs]: //cloud.google.com/natural-language/docs/ [sentiment-api-docs]: //cloud.google.com/natural-language/docs/reference/rest/v1beta2/Sentiment [sentiment-analysis-api-docs]: //cloud.google.com/natural-language/docs/analyzing-sentiment [entity-analysis-api-docs]: //cloud.google.com/natural-language/docs/analyzing-entities