本文將說明伺服器端自訂範本的權限。
每項權限都：
- 由需要這些權限的 API 檢查。
- 系統會根據使用的 API，在沙箱化 JavaScript 中自動偵測。在自訂範本編輯器中進行編輯 (快速意見回饋循環) 和編譯程式碼 (驗證是否強制執行正確權限) 時，就會發生這種情況。
- 可在自訂範本編輯器中編輯，讓權限更具體。
- 可透過
queryPermissionAPI 在沙箱化 JavaScript 中查詢。
access_bigquery
顯示名稱：存取 BigQuery
說明：允許存取 Google Cloud Platform 上的 BigQuery。
設定：可選擇允許指定的專案、資料集和資料表組合與 BigQuery 搭配使用。如果將專案 ID 設定設為 GOOGLE_CLOUD_PROJECT，當 projectId 從 BigQuery API
parameter 排除時，系統會使用 GOOGLE_CLOUD_PROJECT 環境變數做為專案 ID。
要求者： BigQuery
查詢簽章：
queryPermission('access_bigquery', <operation>, <options>)
注意： <operation> 是字串，可包含下列值：
- 寫入
<options> 是包含下列項目的物件：
{
'projectId': <project_id>,
'datasetId': <dataset_id>,
'tableId': <table_id>
}
程式碼範例
const BigQuery = require('BigQuery');
const queryPermission = require('queryPermission');
const connectionInfo = {
'projectId': 'gcp-cloud-project-id',
'datasetId': 'destination-dataset',
'tableId': 'destination-table',
};
if (queryPermission('access_bigquery', 'write', connectionInfo)) {
const rows = [{
'column1': 'String1',
'column2': 1234,
}];
const options = {
'ignoreUnknownValues': true,
'skipInvalidRows': false,
};
BigQuery.insert(connectionInfo, rows, options)
.then(data.gtmOnSuccess, data.gtmOnFailure);
}
access_firestore
顯示名稱：存取 Google Firestore
說明：允許存取 Google Firestore。
設定：可選擇允許指定的專案和路徑 (支援萬用字元語法) 組合與 Firestore 搭配使用。將專案 ID 設定為 GOOGLE_CLOUD_PROJECT，即可在 projectId 從 Firestore API parameter 排除時，使用 GOOGLE_CLOUD_PROJECT 環境變數做為專案 ID。
要求者： Firestore
查詢簽章：
queryPermission('access_firestore', <operation>, <options>)
注意： <operation> 是字串，可包含下列值：
- read：授予讀取和查詢 API 的權限
- write：授予寫入 API 的權限
- read_write：授予讀取、寫入和查詢 API 的權限
<options> 是包含下列項目的物件：
{
'projectId': <project_id>,
'path': <path>
}
程式碼範例
const Firestore = require('Firestore');
const queryPermission = require('queryPermission');
const options = {
'projectId': 'gcp-cloud-project-id',
'path': 'collection/document',
};
if (queryPermission('access_firestore', 'read', options)) {
Firestore.read('collection/document', {
projectId: 'gcp-cloud-project-id',
}).then(data.gtmOnSuccess, data.gtmOnFailure);
}
access_response
顯示名稱：存取回應
說明：存取回應內文、標頭或狀態。
設定：可選擇允許任何或特定存取權，並提供子選項，用於控管各種子元件的存取權。
必要條件： setPixelResponse、setResponseBody、setResponseHeader、setResponseStatus
查詢簽章：
queryPermission('access_response', 'write', <component>[, <optional component name>])
注意事項：控管是否可存取傳出 HTTP 回應元件。
程式碼範例
const queryPermission = require('queryPermission');
const setResponseBody = require('setResponseBody');
const setResponseHeader = require('setResponseHeader');
const setResponseStatus = require('setResponseStatus');
if (queryPermission('access_response', 'write', 'header', 'Content-Type')) {
setResponseHeader('Content-Type', 'text/plain');
}
if (queryPermission('access_response', 'write', 'body')) {
setResponseBody('Not Found');
}
if (queryPermission('access_response', 'write', 'status')) {
setResponseStatus(404);
}
access_template_storage
顯示名稱：存取範本儲存空間
說明：允許存取範本的暫存空間，該空間在伺服器端程序執行期間會持續存在。
設定：無
要求者： templateDataStorage
查詢簽章： queryPermission('access_template_storage')
程式碼範例
const queryPermission = require('queryPermission');
const templateDataStorage = require('templateDataStorage');
const key = 'my_key';
if (queryPermission('access_template_storage')) {
const value = templateDataStorage.getItemCopy(key);
}
get_cookies
顯示名稱：讀取 Cookie 值
說明：從名稱與指定名稱相符的 Cookie 讀取值。
設定：允許讀取的 Cookie 名稱清單。
要求者： getCookieValues
查詢簽章： queryPermission('get_cookies', <name>)
附註：根據 Cookie 名稱，控管是否可讀取 Cookie。
程式碼範例
const queryPermission = require('queryPermission');
const getCookieValues = require('getCookieValues');
const cookieName = 'info';
let cookieValues;
if (queryPermission('get_cookies', cookieName)) {
cookieValues = getCookieValues(cookieName);
}
記錄
顯示名稱：記錄至控制台
說明：將資料記錄至開發人員控制台和代碼管理工具預覽模式。
設定：可選擇在正式環境中啟用記錄功能。預設為只在偵錯/預覽期間啟用記錄功能。如果權限遭拒，logToConsole 不會擲回錯誤，但會隱藏記錄訊息。
要求者： logToConsole
查詢簽章： queryPermission('logging')
附註：控制自訂範本是否可記錄到開發人員控制台。
程式碼範例
const queryPermission = require('queryPermission');
const logToConsole = require('logToConsole');
// Note that it's fine to call log, since the log call will be ignored if
// logging isn't permitted in the current environment.
logToConsole('diagnostic info');
use_message
顯示名稱：使用訊息
說明：使用 addMessageListener 或 sendMessage API 傳送或接收訊息。
設定：可指定訊息類型，以及範本是否可監聽、傳送或兩者皆可。
必要條件： addMessageListener、sendMessage
查詢簽章： queryPermission('use_message', <usage>, <message type>)
注意：用途可以是 listen、send 或 listen_and_send。
程式碼範例
const queryPermission = require('queryPermission');
const sendMessage = require('sendMessage');
if (queryPermission('use_message', 'send', 'set_cookie')) {
sendMessage('set_cookie', {name: 'foo', value: 'bar'});
}
read_container_data
顯示名稱：讀取容器資料
說明：讀取容器相關資料。
設定：無。
必要條件： getClientName、getContainerVersion
查詢簽章： queryPermission('read_container_data')
附註：控制自訂範本是否能讀取容器資料。
程式碼範例
const getContainerVersion = require('getContainerVersion');
const queryPermission = require('queryPermission');
if (queryPermission('read_container_data')) {
return getContainerVersion();
}
read_event_data
顯示名稱：讀取事件資料
說明：從事件中讀取資料。
設定：可選擇允許任何存取權，或由允許金鑰路徑清單控管的特定存取權 (支援萬用字元語法)。
必要條件： getAllEventData、getEventData
查詢簽章： queryPermission('read_event_data'[, <optional key>])
附註：控制自訂範本是否能讀取指定鍵路徑上的事件資料 (如未指定鍵路徑，則為所有事件資料)。
程式碼範例
const getAllEventData = require('getAllEventData');
const queryPermission = require('queryPermission');
if (queryPermission('read_event_data')) {
return getAllEventData();
}
const getEventData = require('getEventData');
const queryPermission = require('queryPermission');
const keyPath = 'parentField.childField';
if (queryPermission('read_event_data', keyPath)) {
return getEventData(keyPath);
}
read_event_metadata
顯示名稱：讀取事件中繼資料
說明：讀取事件回呼中的事件中繼資料
設定：無
要求者： addEventCallback
查詢簽章： queryPermission('read_event_metadata')
附註：控管自訂範本是否能讀取回呼中的事件中繼資料。
程式碼範例
const queryPermission = require('queryPermission');
const addEventCallback = require('addEventCallback');
if (queryPermission('read_event_metadata')) {
addEventCallback((containerId, eventMetadata) => {
// Read event metadata.
});
}
read_request
顯示名稱：讀取 HTTP 要求
說明：讀取要求標頭、查詢參數、內文、路徑或遠端 IP 位址。
設定：可選擇允許任何或特定存取權，並提供子選項，用於控管各種子元件的存取權。
必要條件： extractEventsFromMpv1、extractEventsFromMpv2、getRemoteAddress、getRequestBody、getRequestHeader、getRequestPath、getRequestQueryParameter、getRequestQueryParameters、getRequestQueryString
查詢簽章：
queryPermission('read_request', <component>[, <optional component name>])
附註：控管是否可存取傳入的 HTTP 回應元件。
程式碼範例
const queryPermission = require('queryPermission');
const getRequestBody = require('getRequestBody');
const getRequestHeader = require('getRequestHeader');
let body, contentType;
if (queryPermission('read_request', 'body')) {
body = getRequestBody();
}
if (queryPermission('read_request', 'header', 'content-type')) {
contentType = getRequestHeader('content-type');
}
if (body && contentType == 'application/json') { ... }
return_response
顯示名稱：Returns response
說明：將回應傳回給呼叫端。
設定：無
要求者： returnResponse
查詢簽章： queryPermission('return_response')
注意：這項權限沒有可縮小範圍的欄位，通常不會用於查詢。
run_container
顯示名稱：執行容器
說明：執行包含一項事件的容器
設定：無
要求者： runContainer
查詢簽章： queryPermission('run_container')
注意：這項權限沒有可縮小範圍的欄位，通常不會用於查詢。
send_http
顯示名稱：傳送 HTTP 要求
說明：向指定網址傳送 HTTP 要求。
必要條件： getGoogleScript、sendEventToGoogleAnalytics、sendHttpGet、sendHttpRequest
查詢簽章： queryPermission('send_http', <url>)
附註：根據網址，控管是否可以提出 HTTP 要求。 為確保連線安全，系統只允許安全 (HTTPS) 網址。
程式碼範例
const queryPermission = require('queryPermission');
const sendHttpGet = require('sendHttpGet');
const url = 'https://example.com/search?query=foo&results=10';
if (queryPermission('send_http', url)) {
sendHttpGet(url);
}
send_pixel_from_browser
顯示名稱：透過瀏覽器傳送像素
說明：從瀏覽器傳送 GET 要求到指定網址。
要求者： sendPixelFromBrowser
查詢簽章： queryPermission('send_pixel_from_browser', <url>)
附註：根據網址，控管是否可以從瀏覽器傳送要求。
程式碼範例
const queryPermission = require('queryPermission');
const sendPixelFromBrowser = require('sendPixelFromBrowser');
const url = 'https://example.com/search?query=foo&results=10';
if (queryPermission('send_pixel_from_browser', url)) {
sendPixelFromBrowser(url);
}
set_cookies
顯示名稱：設定 Cookie
說明：設定包含指定名稱和參數的 Cookie。
設定：允許的 Cookie 名稱表格，每個名稱都有選用的限制，包括名稱、網域、路徑、secure 屬性和到期時間。
要求者： setCookie
查詢簽章： queryPermission('set_cookies', <name>, <options>)
注意：根據 Cookie 名稱、網域、路徑、secure 屬性和到期時間，控管是否可將指定的「Set-Cookie」標頭新增至回應。
程式碼範例
const queryPermission = require('queryPermission');
const setCookie = require('setCookie');
const options = {
'domain': 'www.example.com',
'path': '/',
'max-age': 60*60*24*365,
'secure': true
};
if (queryPermission('set_cookies', 'info', options)) {
setCookie('info', 'xyz', options);
}
use_custom_private_keys
顯示名稱：使用自訂私密金鑰
說明：使用 JSON 金鑰檔案中的私密金鑰執行加密編譯作業。
設定：允許的金鑰 ID 清單。這些 ID 必須與伺服器上 SGTM_CREDENTIALS 環境變數參照的 JSON 金鑰檔案中的金鑰相符。
要求者： hmacSha256
查詢簽章： queryPermission('use_custom_private_keys', <key id>)
附註：控管允許的私密金鑰清單。
程式碼範例
const hmacSha256= require('hmacSha256');
const queryPermission = require('queryPermission');
const keyId = 'key1';
let result;
if (queryPermission('use_custom_private_keys', keyId)) {
result = hmacSha256('my_data', keyId);
}
use_google_credentials
顯示名稱：使用 Google 應用程式預設憑證
說明：使用 Google 預設憑證呼叫 Google API。
設定：允許的 Google OAuth 2.0 範圍清單。
要求者： getGoogleAuth
查詢簽章： queryPermission('use_google_credentials', <scopes>)
注意：限制可與 Google API 搭配使用的 Google OAuth 2.0 範圍。
程式碼範例
const getGoogleAuth = require('getGoogleAuth');
const queryPermission = require('queryPermission');
const scopes = [
'https://www.googleapis.com/auth/datastore'
];
let auth;
if (queryPermission('use_google_credentials', scopes)) {
auth = getGoogleAuth(scopes);
}
user_ip
顯示名稱：讀取使用者 IP 位址
說明：讀取使用者的 IP 位址。
設定：無
查詢簽章： queryPermission('user_ip')
附註：控制自訂範本是否可讀取使用者的 IP 位址。
程式碼範例
const getAnonymizedIpAddress = require('getAnonymizedIpAddress');
const queryPermission = require('queryPermission');
if (queryPermission('user_ip')) {
return getAnonymizedIpAddress();
}