本文件概述適用於伺服器端代碼的 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.
});
關聯權限
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 |
經過編碼的 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();
關聯權限
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 |
布林值 |
如果是 true ,系統就不會在 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'
這個選項會擷取 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();
關聯權限
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()
傳回的 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 (如果未指定)。 |
關聯權限
最低映像檔版本
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
|
物體 | 選填要求選項。(詳情請參閱 選項)。 |
選項
選項 | 類型 | 說明 |
---|---|---|
headers |
string | 其他要求標頭。 |
timeout
|
數字 | 逾時 (以毫秒為單位)
要求。預設值為 15000 。 |
authorization
|
物體 | (選填) 授權物件
呼叫 getGoogleAuth ,包括
發出請求時的授權標頭
至 googleapis.com 。 |
關聯權限
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 。 |
關聯權限
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 建立
並指定過期值
例如:"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'
。
關聯權限
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
。
語法
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
|
物體 | 選用 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 資料表的必要資訊。另有
一個自選參數和兩個必要參數:
|
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);
關聯權限
Firestore
傳回提供 Firestore 函式的物件。
這個 API 僅支援原生模式的 Firestore,不支援 Firestore in Datastore 模式。此外,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。如果您省略這個屬性,
已從環境變數擷取 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(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 錯誤 代碼。
關聯權限
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
如果回呼新增至用戶端,則回呼會在各種不同的
是用戶端建立的所有事件如果回呼應接收訊息
只從特定事件擷取這個 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
。
範例
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'});