伺服器端標記 API

本文件概述適用於伺服器端代碼的 API。

---

addEventCallback

註冊將在事件結束時叫用的回呼函式。 回呼功能會在執行事件的所有標記後叫用。 回呼會傳送兩個值：叫用函式的容器 ID 以及包含事件相關資訊的物件。

如果在代碼中使用這個 API，系統會將其與目前的事件建立關聯。當此情況 API 是在用戶端中使用，則必須使用 runContainer API 的 bindToEvent 函式。詳情請參閱 example。

語法

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 會擲回 在用戶端傳回後呼叫則為例外狀況 (例如在非同步作業中呼叫) 回呼，例如 callLater 或 runContainer onComplete 函式)。

用戶端應先使用這個 API 聲明要求的擁有權，再呼叫 runContainer API。

範例

const claimRequest = require('claimRequest');

claimRequest();

語法

claimRequest();

關聯權限

無。

---

computeEffectiveTldPlusOne

傳回指定網域或網址的有效頂層網域 + 1 (eTLD+1)。 系統會根據公開尾碼清單評估網域，以計算 eTLD+1 不過，編寫這類演算法並不容易 因為我們無法寫出所有可能的規則eTLD+1 通常是您可以用來設定 Cookie。

如果引數為空值或未定義，則會傳回引數值 。否則，引數會強制轉換為字串。如果引數並非 有效的網域或網址，會傳回空白字串。如果伺服器無法 擷取公開尾碼清單，則會傳回引數值，不會受到任何變更。

範例

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	string	計算 eTLD+1 的網域或網址。

關聯權限

無。

---

createRegex

建立新的規則運算式例項，並傳回該例項以物件包裝。你無法 直接存取規則運算式不過您可以將文字傳遞到 testRegex API。 String.replace()、String.match()和String.search()。

如果規則運算式無效，或伺服器無法使用 Re2，則會傳回 null。

這個 API 使用 Re2 。伺服器 Docker 映像檔必須為 2.0.0 以上版本。

範例

const createRegex = require('createRegex');

const domainRegex = createRegex('\\w+\\.com', 'i');

// Returns '/foobar'
'example.com/foobar'.replace(domainRegex, '');

語法

createRegex(pattern, flags);

參數

參數	類型	說明
pattern	string	規則運算式的文字。
flags	string	選用字串，內含所建立規則運算式的旗標。 支援 `g` (全域) 和 `i` (不區分大小寫)。所有其他字元 無聲忽略。

關聯權限

無。

最低映像檔版本

2.0.0

---

decodeUri

將指定 URI 中的任何編碼字元解碼。傳回該字串 代表已解碼的 URI如果提供的值無效，則傳回 undefined 。

範例

const decodeUri = require('decodeUri');

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

語法

decodeUri(encoded_uri);

參數

參數	類型	說明
encoded_uri	string	經過編碼的 URI encodeUri() 或其他方式。

關聯權限

無。

---

decodeUriComponent

將指定 URI 元件中的任何編碼字元解碼。傳回 字串，代表已解碼的 URI 元件。如果符合以下情況，則傳回 undefined 指定的輸入內容無效

範例

const decodeUriComponent = require('decodeUriComponent');

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

語法

decodeUriComponent(encoded_uri_component);

參數

參數	類型	說明
encoded_uri_component	string	經過編碼的 URI 元件 encodeUriComponent() 或其他方式

關聯權限

無。

---

encodeUri

透過逸出特殊形式傳回經過編碼的統一資源識別碼 (URI) 字元。傳回代表經過編碼的所提供字串的字串 做為 URI

範例

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

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

語法

encodeUri(uri);

參數

參數	類型	說明
uri	string	完整的 URI。

關聯權限

無。

---

encodeUriComponent

透過逸出特殊形式傳回經過編碼的統一資源識別碼 (URI) 字元。傳回字串，代表編碼成 URI。

範例

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

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

語法

encodeUriComponent(str);

參數

參數	類型	說明
str	string	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	string	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	string	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

---

getGoogleAuth

傳回與 sendHttpGet或sendHttpRequest，將 包含 Google Cloud API 的授權標頭。這個 API 會使用 應用程式預設憑證可自動從 伺服器環境

範例

const getGoogleAuth = require('getGoogleAuth');
const logToConsole = require('logToConsole');
const sendHttpGet = require('sendHttpGet');

const auth = getGoogleAuth({
  scopes: ['https://www.googleapis.com/auth/datastore']
});

sendHttpGet(
  'https://firestore.googleapis.com/v1/projects/my-project/databases/(default)/documents/collection/document',
  {authorization: auth}
).then((result) => {
  if (result.statusCode >= 200 && result.statusCode < 300) {
    logToConsole('Result: ' + result.body);
    data.gtmOnSuccess();
  } else {
    data.gtmOnFailure();
  }
});

語法

getGoogleAuth(scopes);

參數

參數	類型	說明
scopes	陣列	OAuth 2.0 Google API 範圍的陣列， 要求存取權

關聯權限

必須具備use_google_credentials權限。授予這項權限 並設定一或多個允許的範圍。

---

getGoogleScript

從預先決定的一組 Google 指令碼擷取資源，並傳回 驗證指令碼和相關快取中繼資料。

承諾會解析為包含兩個鍵的物件：script 和 metadata。如果要求失敗，承諾會傳回 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	string	指令碼名稱。支援的指令碼為 'ANALYTICS'、'GTAG'和 'GTM'。 'ANALYTICS' 這個選項會擷取 Google Analytics 指令碼 https://www.google-analytics.com/analytics.js。 'GTAG' 選項會擷取全域網站代碼 (gtag.js) https://www.googletagmanager.com/gtag/js 的指令碼。 'GTM' 選項會擷取 Google 代碼管理工具 https://www.googletagmanager.com/gtm.js 的指令碼。
options	物體	選填的要求選項。如要瞭解支援的選項，請參閱下文。

選項

選項	類型	說明
id	string	適用於使用 gtag 評估 ID 的 'GTAG'，以及 'GTM' 為網站容器 ID (例如GTM-XXXX)。
debug	任何	如果偏誤，請請求並傳回測量結果的偵錯版本 指令碼
timeout	數字	要求逾時 (以毫秒為單位)；系統會忽略非正值。如果 要求逾時，系統就會以 undefined 用於指令碼值，{} 代表 中繼資料物件

系統會忽略無法辨識的選項鍵。

關聯權限

必須具備send_http權限。權限必須設為允許 至少擁有：

• 允許 Google 網域

---

getRemoteAddress

傳回要求中 IP 位址的 string 表示法 相關來源，例如12.345.67.890 適用於 IPv4 或 2001:0db8:85a3:0:0:8a2e:0370:7334 以讀取要求標頭，例如 Forwarded 和 X-Forwarded-For。 注意：這個 API 會盡可能嘗試找出來源 IP，但 無法保證結果是準確的

語法

getRemoteAddress();

關聯權限

必須具備read_request權限。權限必須設為 允許存取至少：

• 標題 Forwarded 和 X-Forwarded-For
• 遠端 IP 位址

---

getRequestBody

如有字串，則傳回要求主體，否則會傳回 undefined。

語法

getRequestBody();

關聯權限

read_request

---

getRequestHeader

傳回已命名要求標頭的值，用做字串 (如果有的話)；或 否則為 undefined。如果標頭重複，傳回的值會聯結 與 ', ' 整合。

範例

const getRequestHeader = require('getRequestHeader');

const host = getRequestHeader('host');

語法

getRequestHeader(headerName);

參數

參數	類型	說明
headerName	string	標頭名稱。這個值不區分大小寫。

關聯權限

read_request

---

getRequestMethod

會傳回要求方法，例如'GET' 或 'POST'，以字串的形式處理。

範例

const getRequestMethod = require('getRequestMethod');

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

語法

getRequestMethod();

關聯權限

無。

---

getRequestPath

傳回不含查詢字串的要求路徑。舉例來說，如果網址為 '/foo?id=123'，這會傳回 '/foo'。自動移除伺服器 容器網址前置字串舉例來說，如果伺服器容器網址為 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	string	查詢參數名稱。

關聯權限

read_request

---

getRequestQueryParameters

傳回傳入 HTTP 要求的查詢參數，做為對應物件 查詢參數名稱的對應值。參數名稱 而值會解碼

範例

const getRequestQueryParameters = require('getRequestQueryParameters');

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

語法

getRequestQueryParameters();

關聯權限

read_request

---

getRequestQueryString

傳回要求查詢 (字串中不含前置問號或) 空白字串。

範例

const getRequestQueryString = require('getRequestQueryString');

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

語法

getRequestQueryString();

關聯權限

read_request

---

getTimestamp

已淘汰。優先使用 getTimestampMillis。

傳回代表目前時間 (以毫秒為單位自 Unix 開始算起) 的數字 Date.now() 傳回的 Epoch 時間。

語法

getTimestamp();

關聯權限

無。

---

getTimestampMillis

傳回代表目前時間 (以毫秒為單位自 Unix 開始算起) 的數字 Date.now() 傳回的 Epoch 時間。

語法

getTimestampMillis();

關聯權限

無。

---

getType

傳回描述指定值類型的字串。

輸入類型	傳回的值
string	'string'
數字	'number'
布林值	'boolean'
空值	'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	任何	輸入值。

關聯權限

無。

---

hmacSha256

使用雜湊式訊息驗證計算編碼簽章 使用 SHA-256 的代碼 (HMAC)。預設值為 base64url 編碼。

如要使用這個 API，請在伺服器上設定 SGTM_CREDENTIALS 環境變數 連往 UTF-8 編碼 JSON 金鑰檔案的路徑，格式如下：

{
  "key1": "YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXowMTIzNDU2Nzg5",
  "key2": "OTg3NjU0MzIxMHp5eHd2dXRzcnFwb25tbGtqaWhnZmVkY2Jh",
  ...
}

這些值為採用 Base64 編碼的 HMAC 金鑰，

範例

const hmacSha256 = require('hmacSha256');
const toBase64 = require('toBase64');

const header = toBase64('{"alg":"HS256","typ":"JWT"}', {urlEncoding: true});
const claim = toBase64('{"sub":"1234567890","iat":1698164946}', {urlEncoding: true});
const signature = hmacSha256(header + '.' + claim, 'key1');

const jwt = header + "." + claim + '.' + signature;

語法

hmacSha256(data, keyId, options)

參數

參數	類型	說明
data	string	用於計算 HMAC 值的資料。
keyId	字串	來自 JSON 金鑰檔案的金鑰 ID，指的是 要使用的金鑰
options	物體	選用 API 設定。(詳情請參閱 選項)。

選項

選項	類型	說明
outputEncoding	字串	指定 Pod 的編碼格式 傳回值。支援的格式為 hex、 base64 或 base64url。預設為 base64url (如果未指定)。

關聯權限

use_custom_private_keys

最低映像檔版本

1.0.0

---

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 控制台的記錄檔探索工具中查看這些記錄檔。 在記錄檔探索工具中執行查詢 logName =~ "stdout"，即可查看記錄項目 由這個 API 建立

範例

const logToConsole = require('logToConsole');

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

語法

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

參數

API 會使用一或多個引數，每個引數都會轉換為字串 並登入控制台

關聯權限

logging

---

makeInteger

將指定值轉換成數字 (整數)。

語法

makeInteger(value);

參數

參數	類型	說明
value	任何類型	要轉換的值。

關聯權限

無。

---

makeNumber

將指定值轉換成數字。

語法

makeNumber(value);

參數

參數	類型	說明
value	任何類型	要轉換的值。

關聯權限

無。

---

makeString

傳回指定值，用做字串。

語法

makeString(value);

參數

參數	類型	說明
value	任何類型	要轉換的值。

關聯權限

無。

---

makeTableMap

將含有兩個資料欄的簡單資料表物件轉換為 Map。用途 將包含兩個資料欄的 SIMPLE_TABLE 範本欄位變更為易於管理 格式。

舉例來說，這個函式可以轉換資料表物件：

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

轉換成地圖：

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

傳回物件：已轉換鍵/值組合的 Map。 否則為 null

語法

makeTableMap(tableObj, keyColumnName, valueColumnName);

參數

參數	類型	說明
tableObj	清單	要轉換的資料表物件。畫面上列出 Map 表示資料表中的一個資料列。每個屬性名稱 列物件為欄名稱，而屬性值是資料欄 。
keyColumnName	string	資料欄名稱，其值會在轉換後成為鍵 Map。
valueColumnName	string	資料欄名稱，其值會在轉換後成為值 Map。

關聯權限

無。

---

parseUrl

傳回一個物件，其中包含指定網址的所有元件部分，類似以下的值： URL 物件。

如果網址的格式錯誤，這個 API 會傳回 undefined。適用格式正確 網址字串中未列出的欄位，其值會是空字串。 如果是 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:[e-mail]:8080/foo?param=val%2Cue#bar');

語法

parseUrl(url);

參數

參數	類型	說明
url	string	將剖析的完整網址。

關聯權限

無。

---

returnResponse

使用 API 套用先前由其他範本設定的回應 修改回應，包括 setCookie。 setPixelResponse、setResponseBody、 setResponseHeader 和 setResponseStatus.預設值為 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 Analytics，並傳回 承諾使用 location 金鑰解析為物件，或 拒絕具有 reason 鍵的物件。目的地，通用 Analytics 或 Google Analytics 4，以事件中的評估 ID 為依據 資料。

location 欄位會設為 location 標頭 (如有)。

範例

const logToConsole = require('logToConsole');
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();
}).catch((error) => {
  logToConsole(error.reason);
  setResponseStatus(500);
  data.gtmOnFailure();
});

語法

sendEventToGoogleAnalytics(event);

參數

參數	類型	說明
event	物體	採用統一結構定義格式的事件。

關聯權限

必須具備send_http權限。權限必須設為允許 至少擁有：

• 允許 Google 網域

---

sendHttpGet

對指定網址發出 HTTP GET 要求，並傳回 承諾：在要求完成或 逾時。

已解析的結果是一個物件，含有三個鍵：statusCode、headers、 和 body。如果要求失敗 (例如網址無效、沒有主機路由， SSL 交涉失敗等)，保證會拒絕：{reason: 'failed'}。如果已設定 timeout 選項且要求逾時， 保證會拒絕：{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	string	要求的網址。
options	物體	選填要求選項。(詳情請參閱 選項)。

選項

選項	類型	說明
headers	string	其他要求標頭。
timeout	數字	逾時 (以毫秒為單位) 要求。預設值為 15000。
authorization	物體	(選填) 授權物件 呼叫 getGoogleAuth，包括 發出請求時的授權標頭 至 googleapis.com。

關聯權限

send_http

---

sendHttpRequest

對指定網址發出 HTTP 要求，並傳回 promise 會在要求完成或逾時時傳回回應。

已解析的結果是一個物件，含有三個鍵：statusCode、headers、 和 body。如果要求失敗 (例如網址無效、沒有主機路由， SSL 交涉失敗等)，保證會拒絕：{reason: 'failed'}。如果已設定 timeout 選項且要求逾時， 保證會拒絕：{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	string	要求的網址。
options	物體	選填要求選項。(詳情請參閱 選項)。
body	string	選填要求主體。

選項

選項	類型	說明
headers	string	其他要求標頭。
method	物體	要求方法。預設值為 GET。
timeout	數字	逾時 (以毫秒為單位) 要求。預設值為 15000。
authorization	物體	(選填) 授權物件 呼叫 getGoogleAuth，包括 發出請求時的授權標頭 至 googleapis.com。

關聯權限

send_http

---

sendPixelFromBrowser

傳送指令至瀏覽器，以 <img> 標記的形式載入提供的網址。這個 GA4 的 Google 代碼支援指令通訊協定，且 Google Analytics：Google Analytics 事件網站代碼。您必須設定伺服器容器 網址。詳情請參閱操作說明。

如果傳入的要求不支援指令，這個 API 會傳回 false 或回應是否已清除回應。否則這個 API 會傳回 true。

範例：

const sendPixelFromBrowser = require('sendPixelFromBrowser');

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

語法

sendPixelFromBrowser(url)

參數

參數	類型	說明
url	string	要傳送到瀏覽器的網址。

關聯權限

send_pixel_from_browser

---

setCookie

使用指定的選項設定或刪除 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	string	Cookie 名稱。名稱不區分大小寫。
value	string	Cookie 值。
options	物體	選用的 Cookie 屬性：domain、 expires、 fallbackDomain、httpOnly、max- age、path、secure、 和 sameSite(詳情請參閱 選項)。
noEncode	布林值	如果是 true，系統就不會編碼 Cookie 值。預設為 false。

• domain：用來接收 Cookie 的主機。如果設為 「auto」值，系統就會使用 下列策略：

  • Forwarded 標頭的 eTLD+1 (如有)。
  • X-Forwarded-Host 標頭的 eTLD+1 (如有)。
  • Host 標頭的 eTLD+1。

• expires：Cookie 的生命週期上限。必須是 UTC 格式 日期字串，例如「1985 年 10 月 26 日週六 08:21:00 GMT」。如果同時有 expires 和 已設定max-age，且max-age的優先順序高。

• httpOnly：在 true 的情況下，禁止 JavaScript 存取 Cookie。

• max-age：Cookie 到期前的秒數。零或負 號碼會立即失效。如果同時包含 expires 和 max-age 設定，max-age 的優先順序最高。

• path：要求網址中必須存在的路徑，否則瀏覽器無法 傳送 Cookie 標頭。

• 安全：如果設為 true，則 Cookie 只有在 要求是否來自 https: 端點

• sameSite：聲明不得使用跨來源傳送 Cookie 要求。必須為 'strict'、'lax' 或 'none'。

關聯權限

set_cookie

---

setPixelResponse

將回應內文設為 1x1 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	string	要設為回應主體的值。
encoding	string	回應主體的字元編碼 (預設為 'utf8')。支援的值包括 'ascii'、 'utf8'、'utf16le'、'ucs2'、 'base64'、'latin1'、'binary'、 和 'hex'。

關聯權限

必須具備access_response權限。權限必須設為 允許存取至少：

• body

---

setResponseHeader

設定即將傳回的回應中的標頭。如果標頭包含這個名稱 (不區分大小寫) 先前是由此 API 設定，後者的呼叫將 覆寫或清除前一個呼叫端設定的值。

請注意，必須呼叫 returnResponse 以取得回應 傳回給用戶端

語法

setResponseHeader(name, value);

參數

參數	類型	說明
name	string	標頭名稱。HTTP 標頭名稱不區分大小寫，因此標頭 名稱為小寫。
value	string undefined	標頭值。如果是空值或未定義，則會清除已命名的標題 回應。

關聯權限

必須具備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	string	要雜湊的字串。
onSuccess	功能	使用產生的摘要來呼叫，且以 base64 編碼，除非 options 物件會指定不同的輸出編碼。
options	物體	「Optional」選項物件，用於指定輸出編碼。如果 則物件應包含 outputEncoding 索引鍵 值為 base64 或 hex。

關聯權限

無。

---

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	string	要雜湊的字串。
options	物體	「Optional」選項物件，用於指定輸出編碼。如果 則物件應包含 outputEncoding 索引鍵 值為 base64 或 hex。

關聯權限

無。

---

templateDataStorage

傳回具有存取範本資料儲存空間方法的物件。範本 資料儲存功能可在執行單一範本時，讓資料在不同執行之間共用。 範本資料儲存空間中儲存的資料會保留在執行 都會在 Docker 容器中執行在大部分情況下，會有多個伺服器執行容器 將資料儲存在範本資料儲存空間中，並不保證每次都會 請求可存取資料。

「資料」命名為「templateDataStorage」對我來說 非函式資料類型可以透過這個 API 儲存。任何函式或 傳遞給 API 的函式參照會改為儲存為 null。

注意： 來自偵錯、預覽模式或範本的要求 編輯者，可存取範本資料儲存空間的初始化為空白 且僅在要求的生命週期內保留 (以免混合偵錯或 測試資料)。

注意： 有別於 Web Storage API，templateDataStorage 不會 將資料序列化/反序列化為字串。

語法

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 setResponseStatus = require('setResponseStatus');
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).then((result) => {
  if (result.statusCode >= 200 && result.statusCode < 300) {
    setResponseBody(result.body);
    templateDataStorage.setItemCopy(data.key, result.body);
    data.gtmOnSuccess();
  } else {
    data.gtmOnFailure();
  }
  setResponseStatus(result.statusCode);
});

關聯權限

access_template_storage

---

testRegex

針對透過 createRegex API 建立的規則運算式測試字串。傳回 true 是否與規則運算式相符否則會傳回 false。

使用全域旗標建立的規則運算式具有狀態。詳情請參閱 RegExp 說明文件。

範例

const createRegex = require('createRegex');
const testRegex = require('testRegex');

const domainRegex = createRegex('\\w+\\.com', 'i');

// createRegex returns null if the regex is invalid or Re2 is not available.
if (domainRegex === null) return;

// Returns true
testRegex(domainRegex, 'example.com/foobar');

語法

testRegex(regex, string);

參數

參數	類型	說明
regex	物件	要測試的規則運算式 (從 createRegex API 傳回)。
string	string	要測試的測試字串。

關聯權限

無。

---

toBase64

將字串編碼為 base64 或 base64url。預設值為 Base64 編碼。

語法

toBase64(input, options);

參數

參數	類型	說明
input	string	要編碼的字串。
options	物體	選用 API 設定。(詳情請參閱 選項)。

選項

選項	類型	說明	最低版本
urlEncoding	布林值	如果為 true，結果將會 編碼方式為 base64url 格式。	1.0.0

範例

const toBase64 = require('toBase64');

const base64Hello = toBase64('hello');
const base64UrlHello = toBase64('hello', {urlEncoding: true});

關聯權限

無。

---

BigQuery

傳回提供 BigQuery 函式的物件。

BigQuery.insert 函式允許將資料寫入 BigQuery 資料表。這項服務 會傳回承諾，以成功插入或 並在發生錯誤時拒絕。

插入成功後，承諾就不會有引數。

插入失敗時，承諾會拒絕並顯示含有 錯誤原因；如果發生錯誤，可能屬於資料列物件。有可能 所需部分都會成功完成，但其他部分則不需要。 在此情況下，承諾會遭到拒絕，每個資料列都會在 列物件可協助您區分 (請參閱下方的錯誤範例)。詳情請見 BigQuery 的說明文件 錯誤 訊息。

語法

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

參數	類型	說明
connectionInfo	物體	定義連結 BigQuery 資料表的必要資訊。另有 一個自選參數和兩個必要參數： projectId - 選用 Google Cloud Platform 專案 ID如果省略，系統會從以下位置擷取 projectId： 環境變數 GOOGLE_CLOUD_PROJECT 作為 access_bigquery 專案 ID 的權限設定設為 *，或者 GOOGLE_CLOUD_PROJECT。如果伺服器容器 在 Google Cloud 中運作的時間GOOGLE_CLOUD_PROJECT 已設為 Google Cloud 專案的 ID datasetId - BigQuery 資料集 ID。 tableId - BigQuery 資料表 ID。
rows	陣列	要插入資料表的資料列。
options	物體	選填的要求選項。支援的選項如下： ignoreUnknownValues 和 skipInvalidRows.系統會忽略不明的選項鍵。(詳情請參閱 選項)。

參數	類型	說明
ignoreUnknownValues	布林值	如果設為「true」，則接受含有值的資料列 與結構定義不相符的項目系統會忽略不明的值。預設值 至 false。
skipInvalidRows	布林值	如果設為 true，則插入要求的所有有效資料列。 即使有無效的資料列也一樣預設為 false。

錯誤示例

「找不到模組」錯誤表示伺服器容器可能執行 舊版映像檔 (尚未包含 BigQuery 模組)。 請使用 部署指令碼。 作業完成後，系統就會自動加入該模組。

非插入錯誤通常包含一個含有 reason 鍵的錯誤物件：

[{reason: 'invalid'}]

插入錯誤可包含多個含有 errors 陣列的錯誤物件 和 row 物件以下為 插入只有一列發生錯誤的兩個資料列：

[
  {
    "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，不支援 Firestore in Datastore 模式。此外，API 僅支援使用預設資料庫。

Firestore.read

Firestore.read 函式會從 Firestore 文件讀取資料， 會傳回承諾，該憑證會解析為包含兩個鍵的物件： id和data。如果文件不存在，保證會遭到拒絕， 包含等於 not_found 的 reason 鍵的物件。

注意： 根據預設，Firestore.read 會在 容器執行如要停用快取，請參閱選項一節 以下章節。所有交易期間都會自動停用快取功能。

語法

Firestore.read(path[, options]);

參數	類型	說明
path	string	文件或集合的路徑。開頭或結尾不得為 「/」。
options	物體	選填要求選項。支援的選項如下： projectId、disableCache 和 transaction 方法。未知 會忽略選項鍵。(詳情請參閱 選項)。

參數	類型	說明
projectId	string	(選用) Google Cloud Platform 專案 ID。如果您省略這個屬性， 已從環境變數擷取 projectId GOOGLE_CLOUD_PROJECT、 access_firestore 專案 ID 的權限設定設為 *，或者 GOOGLE_CLOUD_PROJECT。如果伺服器容器 Google Cloud、GOOGLE_CLOUD_PROJECT 會設為 Google Cloud 專案的 ID
disableCache	布林值	(選用) 決定是否要停用快取。 快取功能預設為啟用， 接收時間
transaction	string	(選用) 擷取自 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 會傳回一個承諾，會解析為 已新增或修改文件。如果使用交易選項，API 仍會 會傳回承諾，但不會包含 ID，因為寫入作業會執行批次作業。

語法

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

參數

參數	類型	說明
path	string	文件或集合的路徑。開頭或結尾不得為 「/」。
input	物體	要寫入文件的值。如果已設定合併選項 API 會將輸入的鍵併入文件中
options	物體	選填要求選項。支援的選項如下： projectId、merge 及 transaction 方法。系統會忽略不明的選項鍵。(詳情請參閱 選項)。

參數	類型	說明
projectId	string	(選用) Google Cloud Platform 專案 ID。如果您省略這個屬性， 已從環境變數擷取 projectId GOOGLE_CLOUD_PROJECT、 access_firestore 專案 ID 的權限設定設為 *，或者 GOOGLE_CLOUD_PROJECT。如果伺服器容器 Google Cloud、GOOGLE_CLOUD_PROJECT 會設為 Google Cloud 專案的 ID
merge	布林值	(選用) 如果設為 true，然後將輸入內容中的鍵合併到文件中， 否則此方法會覆寫整份文件預設值為 false。
transaction	string	(選用) 擷取自 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 文件陣列 條件。Firestore 文件物件與前述 Firestore.read。如果沒有符合查詢條件的文件 傳回的承諾會解析為空白陣列

注意： 根據預設，Firestore.query 會在 容器執行如要停用快取，請參閱選項一節 以下章節。所有交易期間都會自動停用快取功能。

注意： Firestore 會自動為每個欄位建立索引。於 為查詢多個欄位，可能要建立複合式索引 指定的集合。若需更多資訊，請參閱： Firestore 的複合式索引說明文件。

語法

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

參數	類型	說明
collection	string	集合的路徑。開頭或結尾不得為 「/」。
queryConditions	陣列	查詢條件陣列。每項查詢的格式為 包含三個值的陣列：key、 operator 和 expectedValue，E.g.: [[‘id’、 ‘<’、 ‘5’]、[‘state’, ‘==’, ‘CA’]]。 條件會用 AND 結合在一起來建立查詢結果。請 參照 Firestore 的查詢運算子，可查看相容查詢清單 運算子
options	物體	選填要求選項。支援的選項如下： projectId、disableCache、 limit 和 transaction 方法。未知 會忽略選項鍵。(詳情請參閱 選項)。

參數	類型	說明
projectId	string	(選用) Google Cloud Platform 專案 ID。如果您省略這個屬性， 已從環境變數擷取 projectId GOOGLE_CLOUD_PROJECT、 access_firestore 專案 ID 的權限設定設為 *，或者 GOOGLE_CLOUD_PROJECT。如果伺服器容器 Google Cloud、GOOGLE_CLOUD_PROJECT 會設為 Google Cloud 專案的 ID
disableCache	布林值	(選用) 決定是否要停用快取。 快取功能預設為啟用， 接收時間
limit	數字	(選用) 變更先前傳回的結果數量上限 查詢時，預設為 5。
transaction	string	(選用) 擷取自 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並行寫入或其他交易 衝突時，最多將重試交易兩次。如果失敗了 總共嘗試三次後，API 就會拒絕並顯示錯誤。這個 API 會傳回 在每項寫入作業中解析為文件 ID 陣列的承諾， 如果交易成功，系統會拒絕交易失敗並顯示錯誤。

語法

Firestore.runTransaction(callback[, options]);

參數

參數	類型	說明
callback	功能	使用字串交易 ID 叫用的回呼。 交易 ID 可傳遞至讀取/寫入/查詢 API 呼叫。 這個回呼函式「必須」傳回承諾。 回呼作業最多可執行三次。
options	物體	選填要求選項。唯一支援的選項 為 projectId。系統會忽略不明的選項鍵。(詳情請參閱 選項)。

參數	類型	說明
projectId	string	(選用) Google Cloud Platform 專案 ID。如果您省略這個屬性， 已從環境變數擷取 projectId GOOGLE_CLOUD_PROJECT、 access_firestore 專案 ID 的權限設定設為 *，或者 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 (通常是透過標記) 傳送， 回呼將會同步執行。使用兩個參數執行回呼：

1. messageType:string
2. message:Object

如果回呼新增至用戶端，則回呼會在各種不同的 是用戶端建立的所有事件如果回呼應接收訊息 只從特定事件擷取這個 API，然後使用 bindToEvent 將此 API 繫結至該事件 在 runContainer API 的 onStart 函式中觸發。請參閱範例。

語法

const addMessageListener = require('addMessageListener');

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

參數

參數	類型	說明
messageType	string	要監聽的訊息類型。如果值不是字串，就會是 強制轉換成字串。
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權限。權限必須設為允許 最低：

• 包含 Usage 為 listen 或 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	string	要傳送的訊息類型。如果值不是字串，則將強制轉換為字串。
message	物體	要傳送的訊息。如果訊息不是物件，API 就不會執行任何動作。

關聯權限

必須具備use_message權限。權限必須設為允許 最低：

• 包含 Usage 為 listen_and_send 或 send 的訊息類型。

---

Object

傳回提供 Object 方法的物件。

keys() 方法會提供標準程式庫 Object.keys() 行為它會傳回指定物件本身的列舉屬性陣列 這些名稱的順序與 for...in... 迴圈相同。如果輸入值為 而非物件，就會強制轉換為物件

values() 方法會提供標準程式庫 Object.values() 行為它會傳回指定物件本身的列舉屬性值陣列 和 for...in... 迴圈的順序相同。如果輸入值不是 系統會將該物件強制轉換成物件。

entries() 方法提供標準程式庫 Object.entries() 行為它會傳回指定物件本身的列舉屬性陣列 [key, value] 組合的順序與 for...in... 迴圈相同。如果 輸入值不是物件，系統會將其強制轉換為物件。

freeze() 方法會提供標準程式庫 Object.freeze() 行為不能再變更凍結的物件；凍結了物體 避免新增資源、移除現有資源 現有屬性值維持不變freeze() 會傳回 與所傳入的相同物件原始或空值引數會視為 如果是凍結的物件，系統會傳回該物件

delete() 方法提供標準程式庫刪除運算子 行為除非物件凍結，否則現有的鍵會從物件中移除。 和 Standard Library Delete 運算子一樣，如果第一次輸入，會傳回 true 值 (objectInput) 是不會凍結的物件，即使第二次輸入也同樣不會凍結 值 (keyToDelete) 指定的鍵不存在。它會傳回 false 的 在其他情況下。但與 Standard Library Delete 運算子不同 包括：

• 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	任何	要列舉其鍵/值組合的物件。如果輸入 系統會將該物件強制轉換成物件。

Object.freeze

參數	類型	說明
objectInput	任何	要凍結的物件。如果輸入內容不是物件 系統就會將其視為凍結的物件

Object.delete

參數	類型	說明
objectInput	任何	要刪除鍵的物件。
keyToDelete	string	要刪除的頂層鍵。

範例

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 的功能與 JavaScript 承諾相同。每個執行個體都有 可傳回 Promise 的 3 種方法，並在承諾時 和解：

• .then() - 處理已解決和遭拒的案件。需要兩個 做為參數：一個用於成功案例，另一個用於失敗 確認是否屬於此情況
• .catch() - 僅處理遭拒的案件。將一個回呼做為 參數。
• .finally() - 讓程式碼能執行，無論承諾是如此 解決或遭拒的問題將一個回呼做為呼叫 沒有引數。

傳回承諾等於承諾的已解析值的變數，或 false。

注意： 採用沙箱機制的 JS 保證會在五秒後逾時 (拒絕) 尚未解決。

範例

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.all(inputs);

參數

參數	類型	說明
inputs	陣列	值或保證的陣列。如果輸入內容並無法提供承諾，則輸入 視為已傳遞承諾值視為已解決的值。擲回 錯誤。

範例

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.create(resolver);

參數

參數	類型	說明
resolver	功能	以兩個函式叫用的函式：解析和拒絕。 傳回的承諾為 參數。如果解析器不是函式，就會擲回錯誤。

範例

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	string	要檢查的 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] 程式庫的模型。其會傳回 物件，可用來有效率地對主體值做出斷言。一個 斷言失敗後，系統會立即停止測試並標示為失敗。不過 一項測試中的失敗不會影響其他測試案例。

語法

assertThat(actual, opt_message)

參數

參數	類型	說明
actual	任何	用於流利檢查的值。
opt_message	string	斷言失敗時要列印的選用訊息。

比對器

Matcher	說明
isUndefined()	斷言主體為 undefined。
isDefined()	斷言主體不是 undefined。
isNull()	斷言主體為 null。
isNotNull()	斷言主體不是 null。
isFalse()	斷言主體為 false。
isTrue()	斷言主體為 true。
isFalsy()	斷言主旨是恐怖的。假值是 undefined、null、false、 NaN、0 和 ''(空字串)。
isTruthy()	斷言主旨為「悲劇性」。假值是 undefined、null、false、 NaN、0 和 ''(空字串)。
isNaN()	斷言主體為值 NaN。
isNotNaN()	斷言主體為 NaN 以外的任何值。
isInfinity()	斷言主體為正面或負面 Infinity。
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	string	錯誤訊息文字 (選填)。

範例

fail('This test has failed.');

---

mock

mock API 可讓您覆寫沙箱 API 的行為。模擬圖 您可以在範本程式碼中安全地使用 API，但 API 僅能在測試模式中運作。 系統會在每次測試執行前重設模擬畫面。

語法

mock(apiName, returnValue);

參數

參數	類型	說明
apiName	string	要模擬的 API 名稱；與傳遞至 require()
returnValue	任何	要傳回給 API 的值或呼叫的函式，以取代 也能使用 Google Cloud CLI 或 Compute Engine API如果 returnValue 是函式，系統會在以下位置呼叫該函式： 來取代沙箱模式如果 returnValue 是任何其他來源 而不是函式，系統就會傳回該值，以取代沙箱模式 也能使用 Google Cloud CLI 或 Compute Engine API

範例

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

---

mockObject

mockObject API 可讓您覆寫採用沙箱機制的 API 行為， 會傳回物件。您可以在範本程式碼中安全地使用 API，但 API 確實可以運作 。系統會在每次測試執行前重設模擬畫面。

語法

mockObject(apiName, objectMock);

參數

參數	類型	說明
apiName	string	要模擬的 API 名稱；與傳遞至 require()
objectMock	物體	要傳回給 API 的值或呼叫的函式，以取代 也能使用 Google Cloud CLI 或 Compute Engine API必須是物件。

範例

const storage = {};
let firestoreId = 1;

function asTestPromise(result) {
  return {
    then: (callback) => callback(result)
  };
}

mockObject('Firestore', {
  write: (collection, input) => {
    storage[collection + '/' + (++firestoreId)] = input;
    return asTestPromise(firestoreId);
  },
  read: (document) => asTestPromise({data: storage[document]})
});

---

runCode

執行範本的程式碼，也就是「Code」分頁標籤的內容，也就是 使用特定輸入資料物件的目前測試環境。

語法

runCode(data)

參數

參數	類型	說明
data	物體	要在測試中使用的資料物件。

傳回值

傳回變數範本的變數值；傳回以下項目的 undefined： 所有其他範本類型

範例

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

---