Thanks for previewing Google's new tag platform documentation! This site is in public beta. (Feedback)

サーバーサイド タグ設定 API

このドキュメントでは、サーバーサイド タグ設定 API について説明します。


addEventCallback

イベントの終了時に呼び出されるコールバック関数を登録します。このコールバックは、イベントのすべてのタグが実行された時点で呼び出されます。コールバックには 2 つの値が渡されます。1 つは、この関数を呼び出すコンテナの ID で、もう 1 つは、イベントに関する情報が含まれたオブジェクトです。

この API をタグで使用すると、現在のイベントに関連付けられます。この API をクライアントで使用する場合は、runContainer API の bindToEvent 関数を使用して、特定のイベントにバインドする必要があります。詳しくは、以下のをご覧ください。

構文

const addEventCallback = require('addEventCallback');

addEventCallback((containerId, eventData) => {
  // Take some action based on the event data.
});

パラメータ

パラメータ 説明
callback 関数 イベントの終了時に呼び出す関数。

eventData オブジェクトには、以下のデータが格納されます。

キー名 説明
tags 配列 タグデータ オブジェクトの配列。イベント中に呼び出されたすべてのタグのオブジェクトが、この配列に含まれます。タグデータ オブジェクトには、タグの ID(id)、実行ステータス(status)、実行時間(executionTime)が含まれます。タグデータには、そのタグで設定されている追加のタグメタデータも含まれます。

サンプル

クライアント:

const addEventCallback = require('addEventCallback');
const claimRequest = require('claimRequest');
const extractEventsFromMpv1 = require('extractEventsFromMpv1');
const logToConsole = require('logToConsole');
const returnResponse = require('returnResponse');
const runContainer = require('runContainer');

claimRequest();

const events = extractEventsFromMpv1();
let eventsCompleted = 0;
events.forEach((evt, i) => {
  runContainer(evt, /* onComplete= */ (bindToEvent) => {
    bindToEvent(addEventCallback)((containerId, eventData) => {
      logToConsole('Event Number: ' + i);
      eventData.tags.forEach((tag) => {
        logToConsole('Tag ID: ' + tag.id);
        logToConsole('Tag Status: ' + tag.status);
        logToConsole('Tag Execution Time: ' + tag.executionTime);
      });
    });
    if (events.length === ++eventsCompleted) {
      returnResponse();
    }
  });
});

タグ:

const addEventCallback = require('addEventCallback');

addEventCallback((containerId, eventData) => {
  // This will be called at the end of the current event.
});

関連付けられているアクセス権

read_event_metadata


callLater

関数の呼び出しが非同期的に行われるように、呼び出しのスケジュールを調整します。この関数は、現在のコードが返ると呼び出されます。setTimeout(<function>, 0) と同じです。

サンプル

const callLater = require('callLater');
const logToConsole = require('logToConsole');

callLater(() => {
  logToConsole('Logged asynchronously');
});

構文

callLater(function)

パラメータ

パラメータ 説明
function 関数 呼び出す関数。

関連付けられているアクセス権

なし


claimRequest

クライアントでこの API を使用してリクエストを受理します。リクエストが受理されると、コンテナは追加のクライアントを実行しません。

この API は、タグまたは変数で呼び出された場合に例外をスローします。この API は、クライアントが返された後に呼び出されると例外をスローします(callLaterrunContainer onComplete 関数などで非同期コールバックで呼び出される場合)。

クライアントは runContainer API を呼び出す前に、この API を使用してリクエストを受理する必要があります。

サンプル

const claimRequest = require('claimRequest');

claimRequest();

構文

claimRequest();

関連付けられているアクセス権

なし


computeEffectiveTldPlusOne

指定されたドメインまたは URL の有効なトップレベル ドメイン + 1(eTLD+1)を返します。 eTLD+1 は、公開サフィックス リストのルールに照らしてドメインを評価することによって計算されます。eTLD+1 は通常、Cookie を設定可能な最上位レベルのドメインです。

引数が null または未定義の場合、引数値は変更されることなく返されます。それ以外の場合、引数は文字列に強制変換されます。引数が有効なドメインまたは URL でない場合は、空の文字列が返されます。サーバーが公開サフィックス リストを取得できない場合、引数の値は変更されることなく返されます。

サンプル

const computeEffectiveTldPlusOne = require('computeEffectiveTldPlusOne');

// Returns 'example.co.uk'
computeEffectiveTldPlusOne('analytics.example.co.uk');

// Returns 'example.co.uk'
computeEffectiveTldPlusOne('https://analytics.example.co.uk/path');

構文

computeEffectiveTldPlusOne(domainOrUrl);

パラメータ

パラメータ 説明
domainOrUrl 文字列 eTLD+1 を計算するためのドメインまたは URL。

関連付けられているアクセス権

なし


decodeUri

指定された URI でエンコードされた文字をデコードします。デコードされた URI コンポーネントを表す文字列を返します。無効な入力がある場合、undefined を返します。

サンプル

const decodeUri = require('decodeUri');

const decodedUrl = decodeUri(data.encodedUrl);
if (decodedUrl) {
  // ...
}

構文

decodeUri(encoded_uri);

パラメータ

パラメータ 説明
encoded_uri 文字列 encodeUri() またはその他の方法でエンコードされた URI。

関連付けられているアクセス権

なし


decodeUriComponent

指定された URI コンポーネントでエンコードされた文字をデコードします。デコードされた URI コンポーネントを表す文字列を返します。入力内容が無効な場合は undefined を返します。

サンプル

const decodeUriComponent = require('decodeUriComponent');

const decodedQuery = decodeUriComponent(data.query);
if (decodedQuery) {
  // ...
}

構文

decodeUriComponent(encoded_uri_component);

パラメータ

パラメータ 説明
encoded_uri_component 文字列 encodeUriComponent() またはその他の方法でエンコードされた URI コンポーネント。

関連付けられているアクセス権

なし


encodeUri

特殊文字をエスケープして、エンコードされた Uniform Resource Identifier(URI)を返します。提供された文字列を URI としてエンコードしたものを表す文字列を返します。

サンプル

const encodeUri = require('encodeUri');
const sendHttpGet = require('sendHttpGet');

sendHttpGet('https://www.example.com/' + encodeUri(pathInput));

構文

encodeUri(uri);

パラメータ

パラメータ 説明
uri 文字列 完全な URI。

関連付けられているアクセス権

なし


encodeUriComponent

特殊文字をエスケープして、エンコードされた Uniform Resource Identifier(URI)を返します。提供された文字列を URI としてエンコードしたものを表す文字列を返します。

サンプル

const encodeUriComponent = require('encodeUriComponent');
const sendHttpGet = require('sendHttpGet');

sendHttpGet('https://www.example.com/?' + encodeUriComponent(queryInput));

構文

encodeUriComponent(str);

パラメータ

パラメータ 説明
str 文字列 URI のコンポーネント。

関連付けられているアクセス権

なし


extractEventsFromMpv1

受信した Measurement Protocol V1 リクエストを、統合スキーマ形式のイベントのリストに変換します。抽出されたイベントのリストを返します。リクエストが正しい形式でない場合、エラーをスローします。

サンプル

const extractEventsFromMpv1 = require('extractEventsFromMpv1');
const isRequestMpv1 = require('isRequestMpv1');

if (isRequestMpv1()) {
  const events = extractEventsFromMpv1();
  for (let i = 0; i < events.length; ++i) {
    const event = events[i];
    // Process event.
  }
}

構文

extractEventsFromMpv1();

関連付けられているアクセス権

read_request アクセス権が必要です。少なくとも下記へのアクセスを許可するように、このアクセス権を設定する必要があります。

  • body
  • query parameters

extractEventsFromMpv2

受信した Measurement Protocol V2 リクエストを、統合スキーマ形式のイベントのリストに変換します。抽出されたイベントのリストを返します。リクエストが正しい形式でない場合、エラーをスローします。

サンプル

const extractEventsFromMpv2 = require('extractEventsFromMpv2');
const isRequestMpv2 = require('isRequestMpv2');

if (isRequestMpv2()) {
  const events = extractEventsFromMpv2();
  for (let i = 0; i < events.length; ++i) {
    const event = events[i];
    // Process event.
  }
}

構文

extractEventsFromMpv2();

関連付けられているアクセス権

read_request アクセス権が必要です。少なくとも下記へのアクセスを許可するように、このアクセス権を設定する必要があります。

  • body
  • query parameters

fromBase64

base64 でエンコードされた文字列をデコードします。入力が無効な場合は undefined を返します。

構文

fromBase64(base64EncodedString);

パラメータ

パラメータ 説明
base64EncodedString 文字列 Base64 でエンコードされた文字列。

サンプル

const fromBase64 = require('fromBase64');

const greeting = fromBase64('aGVsbG8=');
if (greeting === 'hello') {
  // ...
}

関連付けられているアクセス権

なし


generateRandom

指定範囲内の乱数(整数)を返します。

サンプル

const generateRandom = require('generateRandom');

const randomValue = generateRandom(0, 10000000);

構文

generateRandom(min, max);

パラメータ

パラメータ 説明
min 数値 返される整数の潜在的な最小値(その値も含む)。
max 数値 返される整数の潜在的な最大値(その値も含む)。

関連付けられているアクセス権

なし


getAllEventData

イベントデータのコピーを返します。

構文

getAllEventData();

関連付けられているアクセス権

read_event_data


getClientName

現在のクライアントの名前を含む文字列を返します。

構文

getClientName();

関連付けられているアクセス権

read_container_data


getContainerVersion

現在のコンテナに関するデータを含むオブジェクトを返します。返されるオブジェクトには次のフィールドがあります。

{
  containerId: string,
  debugMode: boolean,
  environmentName: string,
  environmentMode: boolean,
  previewMode: boolean,
  version: string,
}

サンプル

const getContainerVersion = require('getContainerVersion');

const containerVersion = getContainerVersion();
const containerId = containerVersion['containerId'];
const isDebug = containerVersion['debugMode'];

構文

getContainerVersion();

関連付けられているアクセス権

read_container_data


getCookieValues

指定した名前のすべての Cookie の値を含む配列を返します。

サンプル

const getCookieValues = require('getCookieValues');

const lastVisit = getCookieValues('lastVisit')[0];
if (lastVisit) {
  // ...
}

構文

getCookieValues(name[, noDecode]);

パラメータ

パラメータ 説明
name 文字列 Cookie の名前。
noDecode ブール値 true の場合、Cookie 値はデコードされてから返されます。デフォルトは false です。

関連付けられているアクセス権

get_cookies


getEventData

イベントデータ内の指定されたパスにある値のコピーを返します。イベントデータがない場合、または指定されたパスに値がない場合は、undefined を返します。

サンプル

const getEventData = require('getEventData');

const campaignId = getEventData('campaign.id');
const itemId = getEventData('items.0.id');
const referrer = getEventData('page_referrer');

パラメータ

パラメータ 説明
keyPath 任意 キーのパス。パス コンポーネントはドットで区切ります。パス コンポーネントは、オブジェクト内のキーまたは配列内のインデックスです。keyPath が文字列でない場合、文字列に変換されます。

構文

getEventData(keyPath);

関連付けられているアクセス権

read_event_data


getGoogleScript

事前に作成された Google スクリプトのセットからリソースを取得し、スクリプトおよび関連付けられたキャッシュ メタデータとともに Promise を返します。

Promise は scriptmetadata の 2 つのキーを含むオブジェクトに解決されます。リクエストが失敗した場合、Promise は拒否され、reason キーが返されます。

metadata オブジェクトには、リソース レスポンス ヘッダーに基づく次のキャッシュ メタデータが含まれます。対応するヘッダーがリソース レスポンスに存在する場合にのみ各フィールドが存在します。

{
  'cache-control': string,
  'expires': string,
  'last-modified': string,
}

サンプル

const getGoogleScript = require('getGoogleScript');

getGoogleScript('ANALYTICS').then((result) => {
  // Operate on result.script and result.metadata here.
});

構文

getGoogleScript(script[, options]);

パラメータ

パラメータ 説明
script 文字列 スクリプトの名前。サポートされているスクリプトは、'ANALYTICS''GTAG''GTM'です。

'ANALYTICS' オプションは、https://www.google-analytics.com/analytics.js から Google アナリティクス スクリプトを取得します。

'GTAG' オプションは、https://www.googletagmanager.com/gtag/js からグローバル サイトタグ(gtag.js)スクリプトを取得します。

'GTM' オプションは、https://www.googletagmanager.com/gtm.js から Google タグ マネージャー スクリプトを取得します。
options オブジェクト リクエスト オプション(省略可)。サポートされているオプションについては、下記をご覧ください。

オプション

オプション 説明
id 文字列 gtag 測定 ID を含む 'GTAG' とウェブコンテナ ID を含む 'GTM' に適用されます(例: GTM-XXXX など)。
debug 任意 truthy の場合、測定スクリプトのデバッグ バージョンをリクエストし、返します。
timeout 数値 リクエスト タイムアウト(ミリ秒単位)。正の数以外は無視されます。リクエストがタイムアウトになると、スクリプト値(undefined)とメタデータ オブジェクト({})とともにコールバックが呼び出されます。

認識されないオプションキーは無視されます。

関連付けられているアクセス権

send_http アクセス権が必要です。少なくとも下記へのアクセスを許可するように、このアクセス権を設定する必要があります。

  • Google Domains を許可

getRemoteAddress

Forwarded や X-Forwarded-For などのリクエスト ヘッダーを読み取ることで、リクエストが発生した IP アドレスの文字列表現(例: IPv4 には 12.345.67.890、IPv6 には 2001:0db8:85a3:0:0:8a2e:0370:7334)を返します。 注: この API では送信元の IP を検出するためにできる限りのことが行われますが、結果が正確であるとは限りません。

構文

getRemoteAddress();

関連付けられているアクセス権

read_request アクセス権が必要です。少なくとも下記へのアクセスを許可するように、このアクセス権を設定する必要があります。

  • ヘッダー ForwardedX-Forwarded-For
  • リモート IP アドレス

getRequestBody

リクエストの本文がある場合は、それを文字列として返します。それ以外の場合は undefined を返します。

構文

getRequestBody();

関連付けられているアクセス権

read_request


getRequestHeader

名前付きのリクエスト ヘッダーの値がある場合はそれを文字列として、それ以外の場合は undefined を返します。ヘッダーが繰り返される場合、戻り値は ', ' で結合されます。

サンプル

const getRequestHeader = require('getRequestHeader');

const host = getRequestHeader('host');

構文

getRequestHeader(headerName);

パラメータ

パラメータ 説明
headerName 文字列 ヘッダー名。この値では、大文字と小文字が区別されません。

関連付けられているアクセス権

read_request


getRequestMethod

リクエスト メソッド('GET''POST' など)を文字列として返します。

サンプル

const getRequestMethod = require('getRequestMethod');

if (getRequestMethod() === 'POST') {
  // Handle the POST request here.
}

構文

getRequestMethod();

関連付けられているアクセス権

なし


getRequestPath

リクエストパスをクエリ文字列なしで返します。たとえば、URL が '/foo?id=123' の場合は '/foo' を返します。サーバー コンテナの URL プレフィックスはパスから自動的に削除されます。たとえば、サーバー コンテナの URL が https://example.com/analytics で、リクエストパスが '/analytics/foo' の場合は '/foo' を返します。

サンプル

const getRequestPath = require('getRequestPath');

const requestPath = getRequestPath();
if (requestPath === '/') {
  // Handle a request for the root path.
}

構文

getRequestPath();

関連付けられているアクセス権

read_request


getRequestQueryParameter

名前付きクエリ文字列パラメータのデコードされた値を文字列として、またはパラメータが存在しない場合は undefined を返します。パラメータがクエリ文字列で繰り返される場合、クエリ文字列に最初に現れる値が返されます。

サンプル

const getRequestQueryParameter = require('getRequestQueryParameter');

const query = getRequestQueryParameter('query');
if (query) {
  // Process query here.
}

構文

getRequestQueryParameter(name);

パラメータ

パラメータ 説明
name 文字列 クエリ パラメータ名。

関連付けられているアクセス権

read_request


getRequestQueryParameters

受信 HTTP リクエストのクエリ パラメータをオブジェクトとして返し、クエリ パラメータ名を対応する 1 つ以上の値にマッピングします。パラメータ名と値はデコードされます。

サンプル

const getRequestQueryParameters = require('getRequestQueryParameters');

const queryParameters = getRequestQueryParameters();
if (queryParameters['search']) {
  // Handle the search query here.
  const maxResults = queryParameters['max_results'];
}

構文

getRequestQueryParameters();

関連付けられているアクセス権

read_request


getRequestQueryString

リクエスト クエリを先頭の疑問符なしで文字列として返します。リクエスト URL にクエリ文字列が含まれていない場合は空の文字列を返します。

サンプル

const getRequestQueryString = require('getRequestQueryString');

const queryString = getRequestQueryString();
if (queryString !== '') {
  // Handle the query string.
}

構文

getRequestQueryString();

関連付けられているアクセス権

read_request


getTimestamp

非推奨。getTimestampMillis を優先します。

現在の時刻を示す数値(ミリ秒単位、Unix エポック以降)を返します。Date.now() によって返されます。

構文

getTimestamp();

関連付けられているアクセス権

なし


getTimestampMillis

現在の時刻を示す数値(ミリ秒単位、Unix エポック以降)を返します。Date.now() によって返されます。

構文

getTimestampMillis();

関連付けられているアクセス権

なし


getType

指定された値のタイプを表す文字列を返します。

入力タイプ 戻り値
文字列 'string'
数値 'number'
ブール値 'boolean'
null 'null'
未定義 'undefined'
配列 'array'
オブジェクト 'object'
関数 'function'

サンプル

const getType = require('getType');

const type = getType(value);
if (type === 'string') {
  // Handle string input.
} else if (type === 'number') {
  // Handle numeric input.
} else {
  logToConsole('Unsupported input type: ', type);
}

構文

getType(value);

パラメータ

パラメータ 説明
value 任意 入力値。

関連付けられているアクセス権

なし


isRequestMpv1

受信リクエストが Measurement Protocol V1 リクエストの場合は true を、そうでない場合は false を返します。

サンプル

const isRequestMpv1 = require('isRequestMpv1');

if (isRequestMpv1()) {
  // Handle Measurement Protocol V1 request.
  const events = extractEventsFromMpv1();
}

構文

isRequestMpv1();

関連付けられているアクセス権

なし


isRequestMpv2

受信リクエストが Measurement Protocol V2 リクエストの場合は true を、そうでない場合は false を返します。

サンプル

const isRequestMpv2 = require('isRequestMpv2');

if (isRequestMpv2()) {
  // Handle Measurement Protocol V2 request.
  const events = extractEventsFromMpv2();
}

構文

isRequestMpv2();

関連付けられているアクセス権

なし


logToConsole

引数をコンソールにログ記録します。

これらのログは、Google Cloud Console のログ エクスプローラ内に表示されます。ログ エクスプローラから logName =~ "stdout" クエリを実行すると、この API で作成されたログエントリが表示されます。

サンプル

const logToConsole = require('logToConsole');

const that = 123;
const those = { ... };
logToConsole('that is: ', that, ' and those is: ', those);

構文

logToConsole(argument1[, argument2, ...]);

パラメータ

API により 1 つ以上の引数が取得され、必要に応じて文字列に変換してから、コンソールにログ記録されます。

関連付けられているアクセス権

logging


makeInteger

与えられた値を数値(整数)に変換します。

構文

makeInteger(value);

パラメータ

パラメータ 説明
value 任意の型 変換する値。

関連付けられているアクセス権

なし


makeNumber

指定された値を数値に変換します。

構文

makeNumber(value);

パラメータ

パラメータ 説明
value 任意の型 変換する値。

関連付けられているアクセス権

なし


makeString

指定された値を文字列として返します。

構文

makeString(value);

パラメータ

パラメータ 説明
value 任意の型 変換する値。

関連付けられているアクセス権

なし


makeTableMap

2 つの列で構成された単純なテーブル オブジェクトを Map に変換します。これを使って、2 つの列を持つ SIMPLE_TABLE テンプレート フィールドを、より管理しやすい形式に変更します。

たとえば、以下の関数はテーブル オブジェクトを変換できます。

[
  {'key': 'k1', 'value': 'v1'},
  {'key': 'k2', 'value': 'v2'}
]

以下のマップに変換されます。

{
  'k1': 'v1',
  'k2': 'v2'
}

オブジェクトを返します。Key-Value ペアが追加されている場合は変換された Map を、それ以外の場合は null を返します。

構文

makeTableMap(tableObj, keyColumnName, valueColumnName);

パラメータ

パラメータ 説明
tableObj リスト 変換するテーブル オブジェクト。各 Map がテーブル内の行を表すマップのリストです。行オブジェクトの各プロパティ名は列名で、プロパティ値は行の列値です。
keyColumnName 文字列 値が変換された Map 内のキーになる列の名前。
valueColumnName 文字列 値が変換された Map 内の値になる列の名前。

関連付けられているアクセス権

なし


parseUrl

URL オブジェクトと同様に、指定された URL の全構成要素を含むオブジェクトを返します。

この API は、不正な形式の URL に対して undefined を返します。URL が適切にフォーマットされている場合、URL 文字列に存在しないフィールドの文字列、または searchParams のオブジェクトは空になります。

返されるオブジェクトには次のフィールドがあります。

{
  href: string,
  origin: string,
  protocol: string,
  username: string,
  password: string,
  host: string,
  hostname: string,
  port: string,
  pathname: string,
  search: string,
  searchParams: Object<string, (string|Array)>,
  hash: string,
}

サンプル

const parseUrl = require('parseUrl');

const urlObject = parseUrl('https://abc:xyz@example.com:8080/foo?param=val%2Cue#bar');

構文

parseUrl(url);

パラメータ

パラメータ 説明
url 文字列 チェック用の完全な URL。

関連付けられているアクセス権

なし


returnResponse

レスポンスを変更する API(setCookiesetPixelResponsesetResponseBodysetResponseHeadersetResponseStatus)を使用し、他のテンプレートによって前に設定されたレスポンスをフラッシュします。デフォルトは、HTTP ステータス コード 200、空の本文、ヘッダーなしです。

この API は、クライアント テンプレートから使用することをおすすめします。

構文

returnResponse();

サンプル

runContainer の例をご覧ください。

関連付けられているアクセス権

return_response


runContainer

イベントの範囲内でコンテナ ロジック(変数、トリガー、タグ)を実行します。 コンテナ実行中にこの API が呼び出されると、コンテナは再び実行されます。

onComplete コールバックと onStart コールバックは、bindToEvent という関数を受け取ります。bindToEvent を使用して、イベントのコンテキストで API を実行します。 詳しくは、addEventCallback の例をご覧ください。

この API は、クライアント テンプレートから使用することをおすすめします。

サンプル

const returnResponse = require('returnResponse');
const runContainer = require('runContainer');

// Runs the container with a simple pageview event and then returns a response.
runContainer({'event_name': 'pageview'}, () => returnResponse());

構文

runContainer(event, onComplete, onStart);

パラメータ

パラメータ 説明
event オブジェクト イベント パラメータ。
onComplete 関数 すべてのタグが配信された後に呼び出されるコールバック。
onStart 関数 タグが配信される直前に呼び出されるコールバック。

関連付けられているアクセス権

run_container


sendEventToGoogleAnalytics

一般的なイベントデータを使って単一のイベントを Google アナリティクスに送信し、Promise を返します。この Promise の解決時には location キーを持つオブジェクトが、拒否時には reason キーを持つオブジェクトが返されます。

location フィールドは location ヘッダーに設定されます(存在する場合)。

サンプル

const sendEventToGoogleAnalytics = require('sendEventToGoogleAnalytics');
const setResponseHeader = require('setResponseHeader');
const setResponseStatus = require('setResponseStatus');

// Sends an event to Google Analytics and returns failure if the request did not
// succeed. Additionally, if the request resulted in a redirect request, the
// code nominates a redirect response to be returned.
sendEventToGoogleAnalytics(event).then((response) => {
  if (response.location) {
    setResponseHeader('location', response.location);
    setResponseStatus(302);
  } else {
    setResponseStatus(200);
  }
  data.gtmOnSuccess();
}, (err) => {
  setResponseStatus(500);
  data.gtmOnFailure();
});

構文

sendEventToGoogleAnalytics(event);

パラメータ

パラメータ 説明
event オブジェクト 統合スキーマ形式のイベント。

関連付けられているアクセス権

send_http アクセス権が必要です。少なくとも下記へのアクセスを許可するように、このアクセス権を設定する必要があります。

  • Google Domains を許可

sendHttpGet

指定された URL に HTTP GET リクエストを送信し、リクエストが完了またはタイムアウトになったときに結果で解決される Promise を返します。

解決時の結果は、statusCodeheadersbody の 3 つのキーを含むオブジェクトになります。リクエストが失敗した場合(URL が無効である、ホストへのルートがない、SSL ネゴシエーションが失敗したなど)、Promise は拒否され {reason: 'failed'} が返されます。timeout オプションが設定されている場合、リクエストがタイムアウトすると、Promise は拒否され {reason: 'timed_out'} が返されます。

サンプル

const sendHttpGet = require('sendHttpGet');

// Returns the response body as the value for a variable.
return sendHttpGet('https://example.com/item/' + data.itemId, {
  headers: {key: 'value'},
  timeout: 500,
}).then((result) => result.body, () => undefined);

構文

sendHttpGet(url[, options]);

パラメータ

パラメータ 説明
url 文字列 リクエスト URL。
options オブジェクト リクエスト オプション(省略可)。サポートされるオプションは headerstimeout です。不明なオプションキーは無視されます(下記のオプションを参照)。

オプション

  • headers: オブジェクトとして表される追加のリクエスト ヘッダー。
  • timeout: リクエストが中止されるまでの時間(ミリ秒単位)。 デフォルトは 15000 です。

関連付けられているアクセス権

send_http


sendHttpRequest

指定された URL に HTTP リクエストを送信し、リクエストが完了するかタイムアウトになると、レスポンスで解決される Promise を返します。

解決時の結果は、statusCodeheadersbody の 3 つのキーを含むオブジェクトになります。リクエストが失敗した場合(URL が無効である、ホストへのルートがない、SSL ネゴシエーションが失敗したなど)、Promise は拒否され {reason: 'failed'} が返されます。timeout オプションが設定されている場合、リクエストがタイムアウトすると、Promise は拒否され {reason: 'timed_out'} が返されます。

サンプル

const sendHttpRequest = require('sendHttpRequest');
const setResponseBody = require('setResponseBody');
const setResponseHeader = require('setResponseHeader');
const setResponseStatus = require('setResponseStatus');

const postBody = 'interaction=click&campaign=promotion&medium=email';
// Sends a POST request and nominates response based on the response to the POST
// request.
sendHttpRequest('https://example.com/collect', {
  headers: {key: 'value'},
  method: 'POST',
  timeout: 500,
}, postBody).then((result) => {
  setResponseStatus(result.statusCode);
  setResponseBody(result.body);
  setResponseHeader('cache-control', result.headers['cache-control']);
});

構文

sendHttpRequest(url[, options[, body]]);

パラメータ

パラメータ 説明
url 文字列 リクエスト URL。
options オブジェクト リクエスト オプション(省略可)。サポートされているオプションは、headersmethodtimeout です。不明なオプションキーは無視されます(下記のオプションを参照)。
body 文字列 オプションのリクエスト本文。

オプション

  • headers: 追加のリクエスト ヘッダー。
  • method: リクエスト メソッド。デフォルトは「GET」です。
  • timeout: リクエストが中止されるまでの時間(ミリ秒単位)。 デフォルトは 15000 です。

関連付けられているアクセス権

send_http


sendPixelFromBrowser

ブラウザにコマンドを送信して、提供された URL を <img> タグとして読み込みます。このコマンド プロトコルは、Google アナリティクス: GA4 設定Google アナリティクス: GA4 イベントのウェブタグに対応しています。設定タグで [サーバー コンテナに送信する] オプションを有効にする必要があります。詳しくは、こちらの手順をご確認ください。

受信リクエストがコマンド プロトコルに対応していない場合、またはレスポンスがすでにフラッシュされている場合、この API は false を返します。 それ以外の場合は、true を返します。

例:

const sendPixelFromBrowser = require('sendPixelFromBrowser');

sendPixelFromBrowser('https://example.com/?id=123');

構文

sendPixelFromBrowser(url)

パラメータ

パラメータ 説明
url 文字列 ブラウザに送信する URLです。

関連付けられているアクセス権

send_pixel_from_browser


setCookie

指定されたオプションで Cookie を設定または削除します。

Cookie を削除するには、その Cookie の作成時と同じパスおよびドメインで Cookie を設定し、過去の有効期限値("Thu, 01 Jan 1970 00:00:00 GMT" など)を割り当てる必要があります。

レスポンスをクライアントに返すには、returnResponse を呼び出す必要があります。

サンプル

const setCookie = require('setCookie');

// Sets an httpOnly cookie with a max-age of 3600.
setCookie('cookieName', 'cookieValue', {'max-age': 3600, httpOnly: true});

構文

setCookie(name, value[, options[, noEncode]]);

パラメータ

パラメータ 説明
name 文字列 Cookie 名。大文字と小文字は区別されません。
value 文字列 Cookie の値。
options オブジェクト オプションの Cookie 属性: domainexpiresfallbackDomainhttpOnlymax-agepathsecuresameSite(下記のオプションを参照)。
noEncode ブール値 true の場合、Cookie 値はエンコードされません。デフォルト値は false です。

オプション

  • domain: Cookie の送信先ホスト。特殊な値「auto」に設定すると、次の戦略を使用して、ホストが自動的に計算されます。

    • Forwarded ヘッダーの eTLD+1(存在する場合)
    • X-Forwarded-Host ヘッダーの eTLD+1(存在する場合)
    • Host ヘッダーの eTLD+1
  • expires: Cookie の最大有効期間。UTC 形式の日付文字列でなければなりません(例: 「Sat, 26 Oct 1985 08:21:00 GMT」)。expiresmax-age を両方とも設定した場合は、max-age が優先されます。

  • httpOnly: true の場合、JavaScript は Cookie にアクセスできません。

  • max-age: Cookie の有効期限が切れるまでの秒数。ゼロまたは負の数値を設定すると Cookie の有効期限が即座に切れます。expiresmax-age の両方を設定した場合は、max-age が優先されます。

  • path: リクエストされた URL に存在する必要があるパス。存在しないと、ブラウザは Cookie ヘッダーを送信しません。

  • secure: true に設定した場合、リクエストが https: エンドポイントから送信された場合のみ、Cookie がサーバーに送信されます。

  • sameSite: クロスオリジン リクエストで Cookie を送信しないようにアサーションを行います。'strict''lax'、または 'none' を指定してください。

関連付けられているアクセス権

set_cookie


setPixelResponse

レスポンスの本文を 1×1 GIF に設定したり、Content-Type ヘッダーを「image/gif」に設定したり、ユーザー エージェントがレスポンスをキャッシュしないようキャッシュ ヘッダーを設定したり、レスポンスのステータスを 200 に設定したりします。

レスポンスをクライアントに返すには、returnResponse を呼び出す必要があります。

構文

setPixelResponse();

関連付けられているアクセス権

access_response アクセス権が必要です。少なくとも下記へのアクセスを許可するように、このアクセス権を設定する必要があります。

  • headers - 次のキーを許可する必要があります。
    • content-type
    • cache-control
    • expires
    • pragma
  • body
  • status

setResponseBody

レスポンスの本文を引数に設定します。

レスポンスをクライアントに返すには、returnResponse を呼び出す必要があります。

構文

setResponseBody(body[, encoding]);

パラメータ

パラメータ 説明
body 文字列 レスポンスの本文として設定する値。
encoding 文字列 レスポンス本文の文字エンコード(デフォルトは 'utf8')。サポートされている値は、'ascii''utf8''utf16le''ucs2''base64''latin1''binary''hex' です。

関連付けられているアクセス権

access_response アクセス権が必要です。少なくとも下記へのアクセスを許可するように、このアクセス権を設定する必要があります。

  • body

setResponseHeader

返されるレスポンスのヘッダーを設定します。この名前(大文字と小文字を区別しない)のヘッダーが以前に API で設定されていた場合、後の呼び出しは前の呼び出し元によって設定された値を上書きまたはクリアします。

レスポンスをクライアントに返すには、returnResponse を呼び出す必要があります。

構文

setResponseHeader(name, value);

パラメータ

パラメータ 説明
name 文字列 ヘッダー名。HTTP ヘッダー名は大文字と小文字を区別しないため、ヘッダー名は小文字になります。
value 文字列 | 未定義 ヘッダー値。null または未定義の場合、返されるレスポンスから名前の付いたヘッダーがクリアされます。

関連付けられているアクセス権

access_response アクセス権が必要です。少なくとも下記へのアクセスを許可するように、このアクセス権を設定する必要があります。

  • headers

setResponseStatus

返されるレスポンスの HTTP ステータス コードを設定します。

レスポンスをクライアントに返すには、returnResponse を呼び出す必要があります。

構文

setResponseStatus(statusCode);

パラメータ

パラメータ 説明
statusCode 数値 返される HTTP ステータス コード。

関連付けられているアクセス権

access_response アクセス権が必要です。少なくとも下記へのアクセスを許可するように、このアクセス権を設定する必要があります。

  • status

sha256

入力値の SHA-256 ダイジェストを計算し、ダイジェストが base64 でエンコードされたコールバックを呼び出します(options オブジェクトが別の出力エンコードを指定していない場合)。

この API の署名と動作は、ウェブコンテナの sha256 API に一致します。ただし、サーバー コンテナのカスタム テンプレートでは、コードを簡素化するために sha256Sync API を使用する必要があります。

サンプル

const encodeUriComponent = require('encodeUriComponent');
const sendHttpGet = require('sendHttpGet');
const sha256 = require('sha256');

sha256('inputString', (digest) => {
  sendHttpGet('https://example.com/collect?id=' + encodeUriComponent(digest));
});

sha256('inputString', (digest) => {
  sendHttpGet('https://example.com/collect?id=' + encodeUriComponent(digest));
}, {outputEncoding: 'hex'});

構文

sha256(input, onSuccess, options = undefined);

パラメータ

パラメータ 説明
input 文字列 ハッシュ化する文字列。
onSuccess 関数 生成されたダイジェスト(base64 でエンコード済み)で呼び出されます(options オブジェクトが別の出力エンコードを指定していない場合)。
options オブジェクト オプション オブジェクト(省略可)が出力エンコードを指定します。指定する場合、オブジェクトには base64 または hex の値を持つキー outputEncoding が含まれている必要があります。

関連付けられているアクセス権

なし


sha256Sync

入力値の SHA-256 ダイジェストを計算して base64 でエンコードされたものを返します(options オブジェクトが別の出力エンコードを指定していない場合)。

サンプル

const encodeUriComponent = require('encodeUriComponent');
const sendHttpGet = require('sendHttpGet');
const sha256Sync = require('sha256Sync');

const digestBase64 = sha256Sync('inputString');
const digestHex = sha256Sync('inputString', {outputEncoding: 'hex'});
sendHttpGet('https://example.com/collect?id=' + encodeUriComponent(digestBase64));
sendHttpGet('https://example.com/collect?id=' + encodeUriComponent(digestHex));

構文

sha256Sync(input, options = undefined);

パラメータ

パラメータ 説明
input 文字列 ハッシュ化する文字列。
options オブジェクト オプション オブジェクト(省略可)が出力エンコードを指定します。指定する場合、オブジェクトには base64 または hex の値を持つキー outputEncoding が含まれている必要があります。

関連付けられているアクセス権

なし


templateDataStorage

テンプレート データ ストレージにアクセスするためのメソッドを含むオブジェクトを返します。テンプレート データ ストレージを使うと、単一のテンプレートの実行全体でデータを共有できます。テンプレート データ ストレージに保存されているデータは、コンテナを実行しているサーバーで維持されます。多くの場合、コンテナを実行しているサーバーは複数存在するため、テンプレート データ ストレージにデータを保存しても、後続のリクエストでデータにアクセスできない場合があります。

「templateDataStorage」という名前の「data」は、この API を使用して保存できるのが関数以外のプレーンなデータ型のみであることを示しています。API に渡される関数または関数へのリファレンスは、代わりに null として保存することが推奨されます。

構文

const templateDataStorage = require('templateDataStorage');

// Returns a copy of the value stored for the given key, or null if nothing
// is stored with that key.
templateDataStorage.getItemCopy(key);

// Stores a copy of the value for the given key (or removes the data stored
// for the given key if the input value is null).
templateDataStorage.setItemCopy(key, value);

// Removes the value stored for the given key, if present.
templateDataStorage.removeItem(key);

// Deletes all values stored for the current template.
templateDataStorage.clear();

サンプル

const sendHttpGet = require('sendHttpGet');
const setResponseBody = require('setResponseBody');
const templateDataStorage = require('templateDataStorage');

// Check to see if the item is in the cache.
const cachedBody = templateDataStorage.getItemCopy(data.key);
if (cachedBody) {
  setResponseBody(cachedBody);
  data.gtmOnSuccess();
  return;
}

sendHttpGet(data.url, (statusCode, headers, body) => {
  if (status >= 200 && status < 300) {
    setResponseBody(body);
    templateDataStorage.setItemCopy(data.key, body);
    data.gtmOnSuccess();
  } else {
    data.gtmOnFailure();
  }
  setResponseStatus(statusCode);
});

関連付けられているアクセス権

access_template_storage


toBase64

文字列を base64 としてエンコードします。

構文

toBase64(input);

パラメータ

パラメータ 説明
input 文字列 エンコードする文字列。

サンプル

const toBase64 = require('toBase64');

const base64Hello = toBase64('hello');

関連付けられているアクセス権

なし


BigQuery

BigQuery 関数を提供するオブジェクトを返します。

BigQuery.insert 関数を使用すると、BigQuery テーブルにデータを書き込むことができます。挿入が成功すると解決し、エラーが発生すると拒否される Promise を返します。

挿入が成功すると、Promise は引数なしで解決されます。

挿入が失敗すると、Promise はエラーの理由を含むオブジェクトのリスト(およびエラーが発生した場合の行オブジェクト)とともに拒否されます。リクエストの一部が正常に完了し、他の部分が正常に完了しない可能性があります。この場合は、Promise が、どの行が挿入されたかを特定できる行オブジェクトと、各行のエラーのリストとともに拒否されます(下記のエラーの例を参照)。詳しくは、BigQuery のエラー メッセージに関するドキュメントをご覧ください。

構文

BigQuery.insert(connectionInfo, rows[, options]);

パラメータ

パラメータ 説明
connectionInfo オブジェクト BigQuery テーブルに接続するために必要な情報を定義します。任意のパラメータが 1 つ、必須のパラメータが 2 つあります。
  • projectId - 省略可。Google Cloud Platform のプロジェクト ID。省略した場合、projectId は、プロジェクト ID の access_bigquery 権限の設定が * または GOOGLE_CLOUD_PROJECT である限り、環境変数 GOOGLE_CLOUD_PROJECT から取得されます。サーバー コンテナが Google Cloud で実行されている場合、GOOGLE_CLOUD_PROJECT はすでに Google Cloud プロジェクトの ID に設定されています。
  • datasetId - BigQuery データセット ID。
  • tableId - BigQuery テーブル ID。
rows 配列 テーブルに挿入する行。
options オブジェクト リクエスト オプション(省略可)。サポートされているオプションは ignoreUnknownValuesskipInvalidRows です。不明なオプションキーは無視されます(下記のオプションを参照)。

オプション

パラメータ 説明
ignoreUnknownValues ブール値 true に設定した場合、スキーマに一致しない値を含む行を受け入れます。不明な値は無視されます。デフォルトは false です。
skipInvalidRows ブール値 true に設定した場合、無効な行が存在する場合でも、リクエストの有効な行がすべて挿入されます。デフォルトは false です。

エラーの例

モジュールが見つからないというエラーが表示された場合は、サーバー コンテナが、BigQuery モジュールが追加されていない古いバージョンの画像を実行している可能性があります。Google のデプロイ スクリプトを使用して、同じ設定でサーバー コンテナを再デプロイしてください。再デプロイが終了すると、モジュールは自動的に追加されます。

通常、挿入以外のエラーには、reason キーを持つ 1 つのエラー オブジェクトが含まれます。

[{reason: 'invalid'}]

挿入エラーには、errors 配列と row オブジェクトを含む複数のエラー オブジェクトが含まれる場合があります。次の例は、1 つの行にのみエラーがある場合に 2 つの行を挿入した場合のエラー レスポンスです。

[
  {
    "errors": [
      {
        "reason":"invalid"
      }
    ],
    "row": {
      "string_col":"otherString",
      "number_col":-3,
      "bool_col":3
    }
  },
  {
    "errors": [
      {
        "reason":"stopped"
      }
    ],
    "row": {
      "string_col":"stringValue",
      "number_col":5,
      "bool_col:false
    }
  }
]

サンプル

const BigQuery = require('BigQuery');

const connectionInfo = {
  'projectId': 'gcp-cloud-project-id',
  'datasetId': 'destination-dataset',
  'tableId': 'destination-table',
};

const rows = [{
  'column1': 'String1',
  'column2': 1234,
}];

const options = {
  'ignoreUnknownValues': true,
  'skipInvalidRows': false,
};

BigQuery.insert(connectionInfo, rows, options)
  .then(data.gtmOnSuccess, data.gtmOnFailure);

関連付けられているアクセス権

access_bigquery


Firestore

Firestore 関数を提供するオブジェクトを返します。

この API は、ネイティブ モードの Firestore のみをサポートし、Datastore モードの Firestore はサポートしません。

Firestore.read

Firestore.read 関数は Firestore ドキュメントからデータを読み取り、iddata の 2 つのキーを含むオブジェクトに解決される Promise を返します。ドキュメントが存在しない場合、Promise は not_found と等しい reason キーを含むオブジェクトでリジェクトされます。

構文

Firestore.read(path[, options]);

パラメータ

パラメータ 説明
path 文字列 ドキュメントまたはコレクションへのパス。先頭または末尾を「/」にすることはできません。
options オブジェクト リクエスト オプション(省略可)。サポートされているオプションは、projectIddisableCachetransaction です。不明なオプションキーは無視されます(下記のオプションを参照)。

オプション

パラメータ 説明
projectId 文字列 省略可。Google Cloud Platform のプロジェクト ID。省略した場合、projectId は、プロジェクト ID の access_firestore 権限の設定が * または GOOGLE_CLOUD_PROJECT である限り、環境変数 GOOGLE_CLOUD_PROJECT から取得されます。サーバー コンテナが Google Cloud で実行されている場合、GOOGLE_CLOUD_PROJECT はすでに Google Cloud プロジェクトの ID に設定されています。
disableCache ブール値 省略可。キャッシュ保存を無効にするかどうかを決定します。 キャッシュ保存はデフォルトで有効です。つまり、リクエストの期間中、結果がキャッシュに保存されます。
transaction 文字列 省略可。Firestore.runTransaction() から取得した値。トランザクションで使用するオペレーションをマークします。

サンプル

const Firestore = require('Firestore');

return Firestore.read('collection/document', {
  projectId: 'gcp-cloud-project-id',
}).then((result) => result.data.key, () => undefined);

Firestore.write

Firestore.write 関数は、Firestore ドキュメントまたはコレクションにデータを書き込みます。コレクションへのパスの場合は、ランダムに生成された ID でドキュメントが作成されます。存在しないドキュメントへのパスの場合は、ドキュメントが作成されます。この API は、追加または変更されたドキュメントの ID に解決される Promise を返します。transaction オプションを使用している場合も API は Promise を返しますが、書き込みはバッチ処理されるため、ID は含まれません。

構文

Firestore.write(path, input[, options]);

パラメータ

パラメータ 説明
path 文字列 ドキュメントまたはコレクションへのパス。先頭または末尾を「/」にすることはできません。
input オブジェクト ドキュメントに書き込む値。merge オプションが設定されている場合、API は入力に含まれるキーをドキュメントにマージします。
options オブジェクト リクエスト オプション(省略可)。サポートされているオプションは、projectIdmergetransaction です。不明なオプションキーは無視されます(下記のオプションを参照)。

オプション

パラメータ 説明
projectId 文字列 省略可。Google Cloud Platform のプロジェクト ID。省略した場合、projectId は、プロジェクト ID の access_firestore 権限の設定が * または GOOGLE_CLOUD_PROJECT である限り、環境変数 GOOGLE_CLOUD_PROJECT から取得されます。サーバー コンテナが Google Cloud で実行されている場合、GOOGLE_CLOUD_PROJECT はすでに Google Cloud プロジェクトの ID に設定されています。
merge ブール値 省略可。true に設定した場合、入力に含まれるキーをドキュメントにマージします。それ以外の場合は、メソッドがドキュメント全体をオーバーライドします。デフォルトは false です。
transaction 文字列 省略可。Firestore.runTransaction() から取得した値。トランザクションで使用するオペレーションをマークします。

サンプル

const Firestore = require('Firestore');

const input = {key1: 'value1', key2: 12345};

Firestore.write('collection/document', input, {
  projectId: 'gcp-cloud-project-id',
  merge: true,
}).then((id) => {
  data.gtmOnSuccess();
}, data.gtmOnFailure);

Firestore.query

Firestore.query 関数は、指定されたコレクションに対してクエリを実行し、クエリ条件に一致する Firestore ドキュメントの配列に解決される Promise を返します。Firestore ドキュメント オブジェクトは、上記の Firestore.read でリストされているオブジェクトと同じです。クエリ条件に一致するドキュメントがない場合、Promise は空の配列に解決されて返されます。

構文

Firestore.query(collection, queryConditions[, options]);

パラメータ

パラメータ 説明
collection 文字列 コレクションへのパス。先頭または末尾を「/」にすることはできません。
queryConditions 配列 クエリ条件の配列。各クエリは、キー演算子expectedValue という 3 つの値を含む配列の形式を取ります。例: [['id', '<', '5'], ['state', '==', 'CA']]。

条件は AND で結合され、クエリ結果を作成します。互換性のあるクエリ演算子のリストについては、Firestore のクエリ演算子をご覧ください。
options オブジェクト リクエスト オプション(省略可)。サポートされているオプションは、projectIddisableCachelimittransaction です。不明なオプションキーは無視されます(下記のオプションを参照)。

オプション

パラメータ 説明
projectId 文字列 省略可。Google Cloud Platform のプロジェクト ID。省略した場合、projectId は、プロジェクト ID の access_firestore 権限の設定が * または GOOGLE_CLOUD_PROJECT である限り、環境変数 GOOGLE_CLOUD_PROJECT から取得されます。サーバー コンテナが Google Cloud で実行されている場合、GOOGLE_CLOUD_PROJECT はすでに Google Cloud プロジェクトの ID に設定されています。
disableCache ブール値 省略可。キャッシュ保存を無効にするかどうかを決定します。 キャッシュ保存はデフォルトで有効です。つまり、リクエストの期間中、結果がキャッシュに保存されます。
limit 数値 省略可。クエリによって返される結果の最大数を変更します。デフォルトは 5 です。
transaction 文字列 省略可。Firestore.runTransaction() から取得した値。トランザクションで使用するオペレーションをマークします。

サンプル

const Firestore = require('Firestore');

const queries = const queries = [['id', '==', '5']];

return Firestore.query('collection', queries, {
  projectId: 'gcp-cloud-project-id',
  limit: 1,
}).then((documents) => documents[0].data.key, () => undefined);

Firestore.runTransaction

Firestore.runTransaction 関数を使用すると、ユーザーは Firestore からアトミックに読み取りと書き込みを行うことができます。同時書き込み、または他のトランザクションの競合が発生した場合、トランザクションは最大 2 回再試行されます。3 回失敗するとエラーとなり、API によって拒否されます。トランザクションが成功した場合、この API は書き込みオペレーションごとに、ドキュメント ID の配列に解決される Promise を返します。トランザクションが失敗した場合はエラーとなり、API によって拒否されます。

構文

Firestore.runTransaction(callback[, options]);

パラメータ

パラメータ 説明
callback 関数 文字列のトランザクション ID で呼び出されるコールバック。トランザクション ID は読み取り、書き込み、クエリ API 呼び出しに渡すことができます。このコールバック関数は Promise を返す必要があります。コールバックは、最大 3 回の試行後にエラーとなります。
options オブジェクト リクエスト オプション(省略可)。サポートされているオプションは projectId のみです。不明なオプションキーは無視されます(下記のオプションを参照)。

オプション

パラメータ 説明
projectId 文字列 省略可。Google Cloud Platform のプロジェクト ID。省略した場合、projectId は、プロジェクト ID の access_firestore 権限の設定が * または GOOGLE_CLOUD_PROJECT である限り、環境変数 GOOGLE_CLOUD_PROJECT から取得されます。サーバー コンテナが Google Cloud で実行されている場合、GOOGLE_CLOUD_PROJECT はすでに Google Cloud プロジェクトの ID に設定されています。

サンプル

const Firestore = require('Firestore');

const path = 'collection/document';
const projectId = 'gcp-cloud-project-id';

Firestore.runTransaction((transaction) => {
  const transactionOptions = {
    projectId: projectId,
    transaction: transaction,
  };
  // Must return a promise.
  return Firestore.read(path, transactionOptions).then((result) => {
    const newInputCount = result.data.inputCount + 1;
    const input = {key1: 'value1', inputCount: newInputCount};
    return Firestore.write(path, input, transactionOptions);
  });
}, {
  projectId: projectId
}).then((ids) => {
  data.gtmOnSuccess();
}, data.gtmOnFailure);

エラーの例

各 Firestore 関数で発生したエラーは、reason キーを含むオブジェクトで拒否されます。

Firestore.read(...).then(onSuccess, (error) => {
  if (error.reason === 'unknown') {
    // Handle the unknown error here.
  }
});

エラーの理由には、Firestore REST API エラーコードが含まれる場合がありますが、これらに限定されません。

関連付けられているアクセス権

access_firestore


JSON

JSON 関数を提供するオブジェクトを返します。

parse() 関数は JSON 文字列を解析し、この文字によって表される値またはオブジェクトを生成します。値を解析できない場合(不正な形式の JSON など)は undefined を返します。入力値が文字列でない場合は、入力が文字列に強制変換されます。

stringify() 関数は、入力を JSON 文字列に変換します。(オブジェクトにサイクルがあるなど)値を解析できない場合は undefined を返します。

サンプル

const JSON = require('JSON');

// The JSON input string is converted to an object.
const object = JSON.parse('{"foo":"bar"}');

// The input object is converted to a JSON string.
const str = JSON.stringify({foo: 'bar'});

構文

JSON.parse(stringInput);
JSON.stringify(value);

関連付けられているアクセス権

なし


Math

Math 関数を提供するオブジェクト。

構文

const Math = require('Math');

// Retrieve the absolute value.
const absolute = Math.abs(-3);

// Round the input down to the nearest integer.
const roundedDown = Math.floor(3.6);

// Round the input up to the nearest integer.
const roundedUp = Math.ceil(2.2);

// Round the input to the nearest integer.
const rounded = Math.round(3.1);

// Return the largest argument.
const biggest = Math.max(1, 3);

// Return the smallest argument.
const smallest = Math.min(3, 5);

// Return the first argument raised to the power of the second argument.
const powerful = Math.pow(3, 1);

// Return the square root of the argument.
const unsquared = Math.sqrt(9);

パラメータ

数学関数のパラメータは数値に変換されます。

関連付けられているアクセス権

なし


Messages

次の API を組み合わせることで、コンテナの異なる要素間でメッセージを送受信できます。


addMessageListener

特定のタイプのメッセージをリッスンする関数を追加します。該当するタイプのメッセージが sendMessage API を使用して(通常はタグによって)送信されると、コールバックが同期的に実行されます。このコールバックは、次の 2 つのパラメータで実行されます。

  1. messageType:string
  2. message:Object

クライアントに追加されたコールバックは、そのクライアントが作成するすべてのイベントからメッセージを受け取ります。コールバックが特定のイベントからのみメッセージを受信する必要がある場合は、runContainer API の onStart 関数で、bindToEvent を使用してこの API を目的のイベントにバインドします。下記の例をご覧ください。

構文

const addMessageListener = require('addMessageListener');

addMessageListener('send_pixel', (messageType, message) => {
  // This will be run whenever something sends a 'send_pixel' message.
});

パラメータ

パラメータ 説明
messageType 文字列 リッスンするメッセージのタイプ。値が文字列でない場合は、文字列に強制変換されます。
callback 関数 指定したタイプのメッセージが送信されたときに実行するコールバック。コールバックが関数でない場合、この API は何も実行しません。

サンプル

const addMessageListener = require('addMessageListener');
const claimRequest = require('claimRequest');
const extractEventsFromMpv1 = require('extractEventsFromMpv1');
const returnResponse = require('returnResponse');
const runContainer = require('runContainer');

claimRequest();
addMessageListener('send_pixel', (messageType, message) => {
  // This will be run whenever a tag sends a 'send_pixel' message.
});

const events = extractEventsFromMpv1();
let eventsCompleted = 0;
events.forEach((event, i) => {
  runContainer(events[i], /* onComplete= */ () => {
    if (events.length === ++eventsCompleted) {
      returnResponse();
    }
  }, /* onStart= */ (bindToEvent) => {
    if (i === 0) {
      bindToEvent(addMessageListener)('send_pixel', (messageType, message) => {
        // This will be called whenever a tag for the first event sends a
        // 'send_pixel' message.
      });
    }
  });
});

関連付けられているアクセス権

use_message アクセス権が必要です。少なくとも、以下を許可するようにアクセス権を設定する必要があります。

  • Usagelisten または listen_and_send のメッセージ タイプ。

hasMessageListener

指定したメッセージ タイプにメッセージ リスナーが追加されている場合、true を返します。 それ以外の場合は false を返します。

構文

const hasMessageListener = require('hasMessageListener');

hasMessageListener('send_pixel');

関連付けられているアクセス権

なし


sendMessage

指定されたタイプのメッセージを登録済みリスナーに送信します。コンテナを実行したクライアントに、タグからメッセージを返送できます。

構文

const sendMessage = require('sendMessage');

sendMessage('send_pixel', {url: 'https://analytics.example.com/collect'});

パラメータ

パラメータ 説明
messageType 文字列 送信するメッセージ タイプ。値が文字列でない場合は、文字列に強制変換されます。
message オブジェクト 送信するメッセージ。メッセージがオブジェクトでない場合、この API は何も実行しません。

関連付けられているアクセス権

use_message アクセス権が必要です。少なくとも、以下を許可するようにアクセス権を設定する必要があります。

  • Usagelisten_and_send または send のメッセージ タイプ。

Object

Object メソッドを提供するオブジェクトを返します。

keys() メソッドは、標準ライブラリの Object.keys() の動作を実行します。for...in... ループと同じ順序で、指定したオブジェクトに固有の列挙プロパティ名の配列を返します。入力値がオブジェクトでない場合、オブジェクトに強制変換されます。

values() メソッドは、標準ライブラリの Object.values() の動作を実行します。for...in... ループと同じ順序で、指定したオブジェクトに固有の列挙プロパティの配列を返します。入力値がオブジェクトでない場合、オブジェクトに強制変換されます。

entries() メソッドは、標準ライブラリの Object.entries() の動作を実行します。for...in... ループと同じ順序で、指定したオブジェクトに固有の列挙プロパティ [key, value] の配列を返します。入力値がオブジェクトでない場合、オブジェクトに強制変換されます。

freeze() メソッドは、標準ライブラリの Object.freeze() の動作を実行します。固定されたオブジェクトを変更することはできません。つまり、新しいプロパティを追加したり、既存のプロパティを削除したり、既存のプロパティ値を変更したりすることは不可能です。freeze() は、渡されたのと同じオブジェクトを返します。プリミティブ引数または null 引数は、固定されたオブジェクトと同様に扱われ、返されます。

delete() メソッドは、標準ライブラリの削除演算子の動作を実行します。オブジェクトが固定されていないことを条件に、指定されたキーをオブジェクトから削除します。標準ライブラリの削除演算子と同様に、最初の入力値(objectInput)が固定されていないオブジェクトであれば、2 番目の入力値(keyToDelete)で存在しないキーが指定されていても true を返します。それ以外の場合は false を返します。ただし、標準ライブラリの削除演算子とは次の点で異なります。

  • keyToDelete には、ネストされたキーを指定するドット区切り文字列は使用できません。
  • delete() を使用して配列から要素を削除することはできません。
  • delete() を使用して、グローバル スコープからプロパティを削除することはできません。

構文

Object.keys(objectInput)
Object.values(objectInput)
Object.entries(objectInput)
Object.freeze(objectInput)
Object.delete(objectInput, keyToDelete)

パラメータ

Object.keys

パラメータ 説明
objectInput 任意 列挙するキーを持つオブジェクト。入力がオブジェクトでない場合、オブジェクトに強制変換されます。

Object.values

パラメータ 説明
objectInput 任意 列挙する値のオブジェクト。入力がオブジェクトでない場合、オブジェクトに強制変換されます。

Object.entries

パラメータ 説明
objectInput 任意 Key-Value ペアで列挙するオブジェクト。入力がオブジェクトでない場合、オブジェクトに強制変換されます。

Object.freeze

パラメータ 説明
objectInput 任意 固定するオブジェクト。入力がオブジェクトでない場合、固定されたオブジェクトとして扱われます。

Object.delete

パラメータ 説明
objectInput 任意 削除するキーを持つオブジェクト。
keyToDelete 文字列 削除するトップレベルのキー。

サンプル

const Object = require('Object');

// The keys of an object are enumerated in an array.
const keys = Object.keys({foo: 'bar'});

// The values of an object are enumerated in an array.
const values = Object.values({foo: 'bar'});

// The key/value pairs of an object are enumerated in an array.
const entries = Object.entries({foo: 'bar'});

// The input object is frozen.
const frozen = Object.freeze({foo: 'bar'});

// The key is removed from the input object.
const obj1 = {deleteme: 'value'};
Object.delete(obj1, 'deleteme');
// Only a top-level key can be specified as the key to delete.
const obj2 = {nested: {key: 'value'}};
Object.delete(obj2, 'nested.key'); // This has no effect.
Object.delete(obj2.nested, 'key'); // This deletes the nested key.

Promise

Promise とやり取りするためのメソッドを提供するオブジェクトを返します。

Promise は機能的に JavaScript の Promise と同等です。インスタンスごとに Promise を返すメソッドが 3 つあり、Promise がひとつ解決するごとに、新たなアクションを実行できます。

  • .then() - 解決済みのケースと拒否されたケースの両方を処理します。パラメータとしてコールバックを 2 つ(成功ケースと失敗ケース)受け取ります。
  • .catch() - 拒否されたケースのみを処理します。1 つのコールバックをパラメータとして受け取ります。
  • .finally() - Promise が解決されたか拒否されたかに関係なく、コードを実行する方法を提供します。1 つのコールバックを、引数なしで呼び出されるパラメータとして受け取ります。

Promise を返す変数は、Promise の解決値と同じ値か、Promise が拒否された場合は false になります。

サンプル

promise.then((resolvedValue) => {
    // Handles when promise resolves.
  }, (rejectedValue) => {
    // Handles when promise rejects.
  });
promise.catch((rejectedValue) => {
    // Handles when promise rejects.
  });
promise.finally(() => {
    // Runs regardless of whether or not the previous promise resolves or
    // rejects.
  });

Promise.all

次のいずれかの Promise を返します。

  • すべての入力が解決されると解決
  • いずれかの入力が拒否されると拒否

構文

Promise.all(inputs);

パラメータ

パラメータ 説明
inputs 配列 値または Promise の配列。入力が Promise でない場合、入力は Promise の解決値のような扱いで渡されます。入力が配列でない場合、エラーをスローします。

サンプル

const Promise = require('Promise');
const sendHttpGet = require('sendHttpGet');

return Promise.all(['a', sendHttpGet('https://example.com')])
  .then((results) => {
    // results will equal: ['a', {statusCode: 200, headers: {}, body: ''}]
  });

関連付けられているアクセス権

なし

Promise.create

JavaScript Promise と機能的に同等の Promise を作成します。

構文

Promise.create(resolver);

パラメータ

パラメータ 説明
resolver 関数 resolve と reject の 2 つの関数で呼び出される関数。返された Promise は、対応するパラメータが呼び出されたときに解決または拒否されます。リゾルバが関数でない場合、エラーをスローします。

サンプル

const Promise = require('Promise');

return Promise.create((resolve, reject) => {
  // Do asynchronous work that eventually calls resolve() or reject()
});

関連付けられているアクセス権

なし

テスト API

以下の API はサンドボックス化された JavaScript テストと連携して Google タグ マネージャーでカスタム テンプレートのテストを作成します。これらのテスト API には、require() ステートメントは必要ありません。[詳しくは、カスタム テンプレート テストの詳細をご覧ください]。


assertApi

指定された API に関するアサーションをスムーズに行うために使用できるマッチャー オブジェクトを返します。

構文

assertApi(apiName)

パラメータ

パラメータ 説明
apiName 文字列 確認する API の名前。require() に渡された文字列と同じ文字列。

マッチャー

  • Subject.wasCalled()
  • Subject.wasNotCalled()
  • Subject.wasCalledWith(...expected)
  • Subject.wasNotCalledWith(...expected)

assertApi('sendPixel').wasCalled();
assertApi('getUrl').wasNotCalled();
assertApi('makeNumber').wasCalledWith('8');
assertApi('setInWindow').wasNotCalledWith('myVar', 'theWrongValue');

assertThat

assertThat API は Google の [Truth] ライブラリを参考に作成されています。これは、サブジェクトの値に関するアサーションをスムーズに行うために使用できるオブジェクトを返します。アサーションが失敗すると、テストは直ちに停止し、失敗としてマークが付けられます。ただし、1 つのテストが失敗しても、他のテストケースに影響することはありません。

構文

assertThat(actual, opt_message)

パラメータ

パラメータ 説明
actual 任意 アサーションで使用する値です。
opt_message 文字列 アサーションが失敗した場合に出力するメッセージ(省略可)。

マッチャー

マッチャー 説明
isUndefined() サブジェクトが undefined であることのアサーションを行います。
isDefined() サブジェクトが undefined ではないことのアサーションを行います。
isNull() サブジェクトが null であることのアサーションを行います。
isNotNull() サブジェクトが null ではないことのアサーションを行います。
isFalse() サブジェクトが false であることのアサーションを行います。
isTrue() サブジェクトが true であることのアサーションを行います。
isFalsy() サブジェクトが falsy であることのアサーションを行います。falsy 値は undefinednullfalseNaN、0、および ''(空の文字列)です。
isTruthy() サブジェクトが truthy であることのアサーションを行います。falsy 値は undefinednullfalseNaN、0、および ''(空の文字列)です。
isNaN() サブジェクトの値が NaN であることのアサーションを行います。
isNotNaN() サブジェクトが NaN 以外の任意の値であることのアサーションを行います。
isInfinity() サブジェクトが正または負の無限大であることのアサーションを行います。
isNotInfinity() サブジェクトが正または負の無限大以外の値であることのアサーションを行います。
isEqualTo(expected) サブジェクトが指定された値と等しいことのアサーションを行います。参照を比較するのではなく、値を比較します。オブジェクトと配列の内容は繰り返し比較されます。
isNotEqualTo(expected) サブジェクトが指定された値と等しくないことのアサーションを行います。参照を比較するのではなく、値を比較します。オブジェクトと配列の内容は繰り返し比較されます。
isAnyOf(...expected) サブジェクトが指定された値のいずれかと等しいことのアサーションを行います。参照を比較するのではなく、値を比較します。オブジェクトと配列の内容は繰り返し比較されます。
isNoneOf(...expected) サブジェクトが指定された値のどの値にも等しくないことのアサーションを行います。参照を比較するのではなく、値を比較します。オブジェクトと配列の内容は繰り返し比較されます。
isStrictlyEqualTo(expected) サブジェクトが指定された値と厳密に等しい(===)ことのアサーションを行います。
isNotStrictlyEqualTo(expected) サブジェクトが指定された値と厳密には等しくない(!==)ことのアサーションを行います。
isGreaterThan(expected) 順序比較で、指定された値よりサブジェクトが大きい(>)ことのアサーションを行います。
isGreaterThanOrEqualTo(expected) 順序比較で、サブジェクトが指定された値より大きい、または指定された値と等しい(>=)ことのアサーションを行います。
isLessThan(expected) 順序比較で、指定された値よりサブジェクトが小さい(<)ことのアサーションを行います。
isLessThanOrEqualTo(expected) 順序比較で、サブジェクトが指定された値より小さい、または指定された値と等しい(<=)ことのアサーションを行います。
contains(...expected) サブジェクトが、指定されたすべての値を任意の順序で含む配列または文字列であることのアサーションを行います。参照を比較するのではなく、値を比較します。オブジェクトと配列の内容は繰り返し比較されます。
doesNotContain(...expected) サブジェクトが、指定されたどの値も含まない配列または文字列であることのアサーションを行います。参照を比較するのではなく、値を比較します。 オブジェクトと配列の内容は繰り返し比較されます。
containsExactly(...expected) サブジェクトが、指定されたすべての値を任意の順序で含み、それ以外の値を含まない配列であることのアサーションを行います。参照を比較するのではなく、値を比較します。オブジェクトと配列の内容は繰り返し比較されます。
doesNotContainExactly(...expected) サブジェクトが、指定された値とは異なる一連の値を任意の順序で含む配列であることのアサーションを行います。参照を比較するのではなく、値を比較します。オブジェクトと配列の内容は繰り返し比較されます。
hasLength(expected) サブジェクトが、指定された長さの配列または文字列であることのアサーションを行います。 値が配列または文字列でない場合、アサーションは常に失敗します。
isEmpty() サブジェクトが空(長さ = 0)の配列または文字列であることのアサーションを行います。値が配列または文字列でない場合、アサーションは常に失敗します。
isNotEmpty() サブジェクトが空でない(長さ > 0)配列または文字列であることのアサーションを行います。値が配列または文字列でない場合、アサーションは常に失敗します。
isArray() サブジェクトの型が配列であることのアサーションを行います。
isBoolean() サブジェクトの型がブール値であることのアサーションを行います。
isFunction() サブジェクトの型が関数であることのアサーションを行います。
isNumber() サブジェクトの型が数値であることのアサーションを行います。
isObject() サブジェクトの型がオブジェクトであることのアサーションを行います。
isString() サブジェクトの型が文字列であることのアサーションを行います。

assertThat(undefined).isUndefined();
assertThat(id, 'ID must be defined').isDefined();
assertThat(null).isNull();
assertThat(undefined).isNotNull();
assertThat(true).isTrue();
assertThat(false).isFalse();
assertThat(1).isTruthy();
assertThat('').isFalsy();
assertThat(1/0).isInfinity();
assertThat(0).isNotInfinity();
assertThat(-'foo').isNaN();
assertThat(100).isNotNaN();
assertThat(sentUrl).isEqualTo('https://endpoint.example.com/?account=12345');
assertThat(category).isNotEqualTo('premium');
assertThat(5).isAnyOf(1, 2, 3, 4, 5);
assertThat(42).isNoneOf('the question', undefined, 41.9);
assertThat('value').isStrictlyEqualTo('value');
assertThat('4').isNotStrictlyEqualTo(4);
assertThat(['a', 'b', 'c']).contains('a', 'c');
assertThat(['x', 'y', 'z']).doesNotContain('f');
assertThat(['1', '2', '3']).containsExactly('3', '2', '1');
assertThat(['4', '5']).doesNotContainExactly('4');
assertThat('a string').hasLength(8);
assertThat([]).isEmpty();
assertThat('another string').isNotEmpty();

fail

現在のテストが直ちに失敗し、指定されたメッセージを出力します(指定されている場合)。

構文

fail(opt_message);

パラメータ

パラメータ 説明
opt_message 文字列 省略可能なエラー メッセージのテキスト。

サンプル

fail('This test has failed.');

mock

mock API を使用すると、サンドボックス化された API の動作をオーバーライドできます。モック API はテンプレート コードで安全に使用できますが、テストモード以外では使用できません。モックは、各テストの実行前にリセットされます。

構文

mock(apiName, returnValue);

パラメータ

パラメータ 説明
apiName 文字列 モックする API の名前。require() に渡された文字列と同じ文字列。
returnValue 任意 API または API の代わりに呼び出される関数に対して返される値。returnValue が 関数の場合、この関数はサンドボックス化 された API の代わりに呼び出されます。returnValue が 関数以外の場合、その値がサンドボックス化された API の代わりに返されます。

mock('encodeUri', "https://endpoint.example.com/?account=12345");
mock('sendPixel', function(url, onSuccess, onFailure) {
    onSuccess();
});

runCode

指定した入力データ オブジェクトを設定した現在のテスト環境で、テンプレートのコード([コード] タブの内容)を実行します。

構文

runCode(data)

パラメータ

パラメータ 説明
data オブジェクト テストで使用するデータ オブジェクト。

戻り値

変数テンプレートの変数の値を返します。他のすべてのテンプレート タイプに対して undefined を返します。

サンプル

runCode({field1: 123, field2: 'value'});