本文件概述適用於伺服器端代碼的 API。
addEventCallback
註冊將在事件結束時叫用的回呼函式。事件的所有代碼執行完畢後,系統就會叫用回呼。回呼會傳送兩個值:叫用函式的容器 ID,以及包含事件相關資訊的物件。
如果在代碼中使用這個 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.
});
關聯權限
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` (不區分大小寫)。系統會在不發出通知的情況下忽略所有其他字元。 |
關聯權限
無。
最低映像檔版本
decodeUri
將指定 URI 中的任何編碼字元解碼。傳回代表已解碼 URI 的字串。如果提供的輸入無效,就會傳回 undefined
。
範例
const decodeUri = require('decodeUri');
const decodedUrl = decodeUri(data.encodedUrl);
if (decodedUrl) {
// ...
}
語法
decodeUri(encoded_uri);
參數
參數 | 類型 | 說明 |
---|---|---|
encoded_uri |
string |
以 encodeUri() 或其他方式編碼的 URI。 |
關聯權限
無。
decodeUriComponent
將指定 URI 元件中的任何編碼字元解碼。傳回代表已解碼 URI 元件的字串。如果指定的輸入無效,就會傳回 undefined
。
範例
const decodeUriComponent = require('decodeUriComponent');
const decodedQuery = decodeUriComponent(data.query);
if (decodedQuery) {
// ...
}
語法
decodeUriComponent(encoded_uri_component);
參數
參數 | 類型 | 說明 |
---|---|---|
encoded_uri_component |
string |
以 encodeUriComponent() 或其他方式編碼的 URI 元件。 |
關聯權限
無。
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();
關聯權限
getClientName
傳回包含目前用戶端名稱的字串。
語法
getClientName();
關聯權限
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();
關聯權限
getCookieValues
傳回包含特定名稱所有 Cookie 值的陣列。
範例
const getCookieValues = require('getCookieValues');
const lastVisit = getCookieValues('lastVisit')[0];
if (lastVisit) {
// ...
}
語法
getCookieValues(name[, noDecode]);
參數
參數 | 類型 | 說明 |
---|---|---|
name |
string | Cookie 的名稱。 |
noDecode |
boolean |
如果為 true ,系統就不會在傳回 Cookie 值前解碼 Cookie 值。這個變數預設為 false 。
|
關聯權限
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);
關聯權限
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' 選項會從 https://www.google-analytics.com/analytics.js 擷取 Google Analytics (分析) 指令碼。'GTAG' 選項會從 https://www.googletagmanager.com/gtag/js 擷取全域網站代碼 (gtag.js) 指令碼。'GTM' 選項會從 https://www.googletagmanager.com/gtm.js 擷取 Google 代碼管理工具指令碼。
|
options |
物體 | 選填的要求選項。如要瞭解支援的選項,請參閱下文。 |
選項
選項 | 類型 | 說明 |
---|---|---|
id |
string |
適用於使用 gtag 評估 ID 的 'GTAG' ,以及含有網站容器 ID 的 'GTM' (例如GTM-XXXX)。
|
debug |
任何 | 如果壓力,系統就會要求並傳回評估指令碼的偵錯版本。 |
timeout |
數字 |
要求逾時 (以毫秒為單位);忽略非正值。如果要求逾時,系統會使用 undefined 叫用指令碼值,針對中繼資料物件使用 {} 。 |
系統會忽略無法辨識的選項鍵。
關聯權限
必須具備send_http
權限。權限必須設為允許至少存取:
- 允許 Google 網域
getRemoteAddress
透過讀取要求標頭 (例如 Forwarded 和 X-Forwarded-For) 傳回要求來源 IP 位址的 string (字串),例如 IPv4 為 12.345.67.890
,IPv6 則傳回 2001:0db8:85a3:0:0:8a2e:0370:7334
。注意:這個 API 會盡可能嘗試找出來源 IP,但無法保證結果正確無誤。
語法
getRemoteAddress();
關聯權限
必須具備read_request
權限。權限必須設為允許存取至少:
- 標題
Forwarded
和X-Forwarded-For
- 遠端 IP 位址
getRequestBody
如有字串,則傳回要求主體,否則會傳回 undefined
。
語法
getRequestBody();
關聯權限
getRequestHeader
如有字串,則傳回已命名要求標頭的值,否則傳回 undefined
。如果標頭重複,傳回的值會與 ', '
合併。
範例
const getRequestHeader = require('getRequestHeader');
const host = getRequestHeader('host');
語法
getRequestHeader(headerName);
參數
參數 | 類型 | 說明 |
---|---|---|
headerName |
string | 標頭名稱。這個值不區分大小寫。 |
關聯權限
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();
關聯權限
getRequestQueryParameter
以字串形式傳回已命名查詢字串參數的已解碼值;如果沒有參數,則傳回 undefined
。如果參數在查詢字串中重複,系統會傳回出現在查詢字串中的第一個值。
範例
const getRequestQueryParameter = require('getRequestQueryParameter');
const query = getRequestQueryParameter('query');
if (query) {
// Process query here.
}
語法
getRequestQueryParameter(name);
參數
參數 | 類型 | 說明 |
---|---|---|
name |
string | 查詢參數名稱。 |
關聯權限
getRequestQueryParameters
傳回傳入 HTTP 要求的查詢參數,做為將查詢參數名稱對應至對應值的物件。參數名稱和值會經過解碼。
範例
const getRequestQueryParameters = require('getRequestQueryParameters');
const queryParameters = getRequestQueryParameters();
if (queryParameters['search']) {
// Handle the search query here.
const maxResults = queryParameters['max_results'];
}
語法
getRequestQueryParameters();
關聯權限
getRequestQueryString
傳回要求查詢 (不含前置問號) 或空白字串 (如果要求網址不包含查詢字串)。
範例
const getRequestQueryString = require('getRequestQueryString');
const queryString = getRequestQueryString();
if (queryString !== '') {
// Handle the query string.
}
語法
getRequestQueryString();
關聯權限
getTimestamp
已淘汰。優先使用 getTimestampMillis。
傳回「數字」,代表自 Unix 紀元以來的目前時間 (以毫秒為單位),由 Date.now()
傳回。
語法
getTimestamp();
關聯權限
無。
getTimestampMillis
傳回「數字」,代表自 Unix 紀元以來的目前時間 (以毫秒為單位),由 Date.now()
傳回。
語法
getTimestampMillis();
關聯權限
無。
getType
傳回描述指定值類型的字串。
輸入類型 | 傳回的值 |
---|---|
string | 'string' |
數字 | 'number' |
boolean | '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
|
string | 從 JSON 金鑰檔案中參照所用金鑰的金鑰 ID。 |
options
|
object | 選用 API 設定。(請參閱下方的選項)。 |
選項
選項 | 類型 | 說明 |
---|---|---|
outputEncoding
|
字串 | 指定傳回值的編碼格式。支援的格式為 hex 、base64 或 base64url 。如未指定,預設值為 base64url 。 |
關聯權限
最低映像檔版本
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 會使用一或多個引數,每個引數都會視需要轉換為字串,並記錄到控制台。
關聯權限
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:xyz@example.com:8080/foo?param=val%2Cue#bar');
語法
parseUrl(url);
參數
參數 | 類型 | 說明 |
---|---|---|
url |
string | 將剖析的完整網址。 |
關聯權限
無。
returnResponse
整理先前由其他範本使用修改回應的 API 設定的回應,包括 setCookie、setPixelResponse、setResponseBody、setResponseHeader 和 setResponseStatus。預設值為 HTTP 狀態碼 200、空白主體,而且沒有標頭。
建議您從用戶端範本使用這個 API。
語法
returnResponse();
範例
請參閱 runContainer
範例。
關聯權限
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 |
功能 | 在代碼開始觸發之前立即叫用的回呼。 |
關聯權限
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
|
object | 選填要求選項。(請參閱下方的選項)。 |
選項
選項 | 類型 | 說明 |
---|---|---|
headers |
string | 其他要求標頭。 |
timeout
|
number | 取消要求前的逾時時間 (以毫秒為單位)。預設值為 15000 。 |
authorization
|
object | 此為選用的授權物件,指透過呼叫 getGoogleAuth 的方式向 googleapis.com 發出要求時包含授權標頭。 |
關聯權限
sendHttpRequest
向指定的網址發出 HTTP 要求,並傳回在要求完成或逾時後與回應來解析的承諾。
已解析的結果是一個物件,含有三個鍵: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
|
object | 選填要求選項。(請參閱下方的選項)。 |
body |
string | 選填要求主體。 |
選項
選項 | 類型 | 說明 |
---|---|---|
headers |
string | 其他要求標頭。 |
method |
物體 | 要求方法。預設值為 GET 。 |
timeout
|
number | 取消要求前的逾時時間 (以毫秒為單位)。預設值為 15000 。 |
authorization
|
object | 此為選用的授權物件,指透過呼叫 getGoogleAuth 的方式向 googleapis.com 發出要求時包含授權標頭。 |
關聯權限
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 | 要傳送至瀏覽器的網址。 |
關聯權限
setCookie
使用指定的選項設定或刪除 Cookie。
如要刪除 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 |
string | Cookie 名稱。名稱不區分大小寫。 |
value |
string | Cookie 值。 |
options |
物體 | 選用的 Cookie 屬性:domain、expires、fallbackDomain、httpOnly、max- age、path、secure 和 sameSite。(請參閱下方的選項)。 |
noEncode |
boolean |
如果是 true,系統就不會編碼 Cookie 值。預設值為 false 。 |
domain:用來接收 Cookie 的主機。如果設為特殊值「auto」,系統將使用下列策略自動計算主機:
Forwarded
標頭的 eTLD+1 (如有)。X-Forwarded-Host
標頭的 eTLD+1 (如有)。Host
標頭的 eTLD+1。
expires:Cookie 的生命週期上限。這必須是世界標準時間格式的日期字串,例如「1985 年 10 月 26 日 08:21:00 GMT」。如果同時設定
expires
和max-age
,系統會優先採用max-age
。httpOnly:在
true
的情況下,禁止 JavaScript 存取 Cookie。max-age:Cookie 到期前的秒數。如果數字為零或負數,則 Cookie 會立即失效。如果同時設定
expires
和max-age
,系統會優先採用max-age
。路徑:要求網址中必須存在的路徑,否則瀏覽器不會傳送 Cookie 標頭。
secure:如果設為
true
,則只有在https:
端點發出要求時,Cookie 才會傳送至伺服器。sameSite:宣告 Cookie 不得與跨來源要求一起傳送。必須為
'strict'
、'lax'
或'none'
。
關聯權限
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
除非 options
物件指定不同的輸出編碼,否則會計算輸入的 SHA-256 摘要,並使用以 Base64 編碼的摘要叫用回呼。
這個 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 |
功能 |
除非 options 物件指定不同的輸出編碼,否則使用產生的摘要並採用 Base64 編碼。 |
options |
物體 |
「Optional」選項物件,用於指定輸出編碼。如果有指定,物件應包含 outputEncoding 索引鍵,且值為 base64 或 hex 。 |
關聯權限
無。
sha256Sync
計算並傳回以 Base64 編碼的輸入 SHA-256 摘要,除非 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
傳回具有存取範本資料儲存空間方法的物件。範本資料儲存功能可在執行單一範本時共用資料。範本資料儲存空間中儲存的資料會保留在執行容器的伺服器中。在大部分的情況下,會有多個伺服器執行容器,因此將資料儲存在範本資料儲存空間中,並不保證每個後續要求都能存取資料。
「templateDataStorage」的名稱中的「資料」是指只能利用這個 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 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);
});
關聯權限
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
|
object | 選用 API 設定。(請參閱下方的選項)。 |
選項
選項 | 類型 | 說明 | 最低版本 |
---|---|---|---|
urlEncoding
|
boolean | 如果為 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 資料表的必要資訊。其中有一個選用參數和兩個必要參數:
|
rows |
陣列 | 要插入資料表的資料列。 |
options |
物體 | 選填的要求選項。支援的選項為:ignoreUnknownValues 和 skipInvalidRows。系統會忽略不明的選項鍵。(請參閱下方的選項)。 |
參數 | 類型 | 說明 |
---|---|---|
ignoreUnknownValues |
boolean | 如果設為 true ,系統會接受與結構定義不相符的資料列。系統會忽略不明的值。預設值為 false 。 |
skipInvalidRows |
boolean | 如果設為 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);
關聯權限
Firestore
傳回提供 Firestore 函式的物件。
這個 API 僅支援原生模式的 Firestore,不支援 Datastore 模式的 Firestore。此外,API 僅支援使用預設資料庫。
Firestore.read
Firestore.read
函式會從 Firestore 文件中讀取資料,並傳回「承諾」,該憑證會解析為包含兩個金鑰的物件:id
和 data
。如果文件不存在,承諾就會拒絕含有等於 not_found
的 reason
金鑰的物件。
語法
Firestore.read(path[, options]);
參數 | 類型 | 說明 |
---|---|---|
path |
string | 文件或集合的路徑。開頭或結尾不得為「/」。 |
options |
物體 | 選填要求選項。支援的選項為:projectId、disableCache 和 transaction。系統會忽略不明的選項鍵。(請參閱下方的選項)。 |
參數 | 類型 | 說明 |
---|---|---|
projectId |
string | (選用) Google Cloud Platform 專案 ID。如果省略,則只要專案 ID 的 access_firestore 權限設定設為 * 或 GOOGLE_CLOUD_PROJECT ,系統就會從環境變數 GOOGLE_CLOUD_PROJECT 擷取 projectId 。如果伺服器容器是在 Google Cloud 中執行,GOOGLE_CLOUD_PROJECT 就會設為 Google Cloud 專案的 ID。 |
disableCache |
boolean | (選用) 決定是否要停用快取。 快取功能預設為啟用,在要求期間快取結果。 |
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 會傳回解析為新增或修改文件 ID 的承諾。如果使用交易選項,API 仍會傳回承諾值,但不會包含 ID,因為寫入作業已批次處理。
語法
Firestore.write(path, input[, options]);
參數
參數 | 類型 | 說明 |
---|---|---|
path |
string | 文件或集合的路徑。開頭或結尾不得為「/」。 |
input |
物體 | 要寫入文件的值。如果設定了合併選項,API 會將輸入內容中的金鑰合併至文件。 |
options |
物體 | 選填要求選項。支援的選項為 projectId、merge 和 transaction。系統會忽略不明的選項鍵。(請參閱下方的選項)。 |
參數 | 類型 | 說明 |
---|---|---|
projectId |
string | (選用) Google Cloud Platform 專案 ID。如果省略,則只要專案 ID 的 access_firestore 權限設定設為 * 或 GOOGLE_CLOUD_PROJECT ,系統就會從環境變數 GOOGLE_CLOUD_PROJECT 擷取 projectId 。如果伺服器容器是在 Google Cloud 中執行,GOOGLE_CLOUD_PROJECT 就會設為 Google Cloud 專案的 ID。 |
merge |
boolean | (選用) 如果設為 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(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。如果省略,則只要專案 ID 的 access_firestore 權限設定設為 * 或 GOOGLE_CLOUD_PROJECT ,系統就會從環境變數 GOOGLE_CLOUD_PROJECT 擷取 projectId 。如果伺服器容器是在 Google Cloud 中執行,GOOGLE_CLOUD_PROJECT 就會設為 Google Cloud 專案的 ID。 |
disableCache |
boolean | (選用) 決定是否要停用快取。 快取功能預設為啟用,在要求期間快取結果。 |
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。如果省略,則只要專案 ID 的 access_firestore 權限設定設為 * 或 GOOGLE_CLOUD_PROJECT ,系統就會從環境變數 GOOGLE_CLOUD_PROJECT 擷取 projectId 。如果伺服器容器是在 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 錯誤代碼。
關聯權限
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 傳送該類型訊息 (通常是透過標記) 時,系統會同步執行回呼。使用兩個參數執行回呼:
messageType:string
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 |
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() 行為。它會以 for...in...
迴圈的順序,傳回指定物件自有列舉屬性 [key, value]
組合的陣列。如果輸入值不是物件,就將強制轉換成物件。
freeze()
方法提供標準程式庫的 Object.freeze() 行為。凍結物件無法再變更;凍結物件會禁止新增屬性、移除現有屬性,以及變更現有屬性值。freeze()
會傳回先前傳入的物件。原始或空值引數會視為凍結物件,並傳回。
delete()
方法提供標準程式庫的刪除運算子行為。除非物件凍結,否則現有的鍵會從物件中移除。與標準程式庫刪除運算子一樣,如果第一個輸入值 (objectInput
) 是沒有凍結的物件,即使第二個輸入值 (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 | 任何 | 要列舉其鍵/值組合的物件。如果輸入內容不是物件,就會強制轉換為物件。 |
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 的方法,讓您在承諾和承諾發生時進一步採取行動:
.then()
- 處理已解決和遭拒的案件。這會使用兩個回呼做為參數:一個用於成功案例,另一個用於失敗情況。.catch()
- 僅處理遭拒的案件。使用一個回呼做為參數。.finally()
:讓程式碼執行,無論承諾產品是否已解決或遭拒。將一個回呼當做在沒有引數的情況下叫用的參數。
傳回承諾的變數等於承諾的解析值,或 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.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() |
斷言主體為正值或負 Infinity 以外的任何值。 |
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 傳回的值或呼叫的函式,取代 API 所傳回的值。如果 returnValue 是函式,系統會呼叫該函式,取代沙箱 API;如果 returnValue 是函式以外的任何內容,會傳回該值取代沙箱 API。 |
例子
mock('encodeUri', "https://endpoint.example.com/?account=12345");
mock('sendPixel', function(url, onSuccess, onFailure) {
onSuccess();
});
runCode
在目前的測試環境中使用指定的輸入資料物件執行範本的程式碼,也就是「Code」分頁的內容。
語法
runCode(data)
參數
參數 | 類型 | 說明 |
---|---|---|
data |
物體 | 要在測試中使用的資料物件。 |
傳回值
傳回變數範本的變數值;針對所有其他範本類型傳回 undefined
。
範例
runCode({field1: 123, field2: 'value'});