本頁面由 Cloud Translation API 翻譯而成。

伺服器端自訂範本權限

本文件概述伺服器端自訂範本的權限。

每項權限如下：

由需要這些資訊的 API 檢查。
根據所使用的 API，在沙箱 JavaScript 中自動偵測。這會發生在自訂範本編輯器中進行編輯 (快速回饋循環) 以及編譯程式碼時 (驗證是否強制執行正確的權限)。
可在自訂範本編輯器中編輯，以便進一步指定權限。
透過 queryPermission API 在沙箱 JavaScript 中進行查詢。

access_bigquery

顯示名稱：存取 BigQuery

說明：允許存取 Google Cloud Platform 上的 BigQuery。

設定：允許指定的專案、資料集和資料表組合與 BigQuery 搭配使用的選項。設定 GOOGLE_CLOUD_PROJECT 的專案 ID 設定後，當 projectId 從 BigQuery API parameter 中排除時，即可使用 GOOGLE_CLOUD_PROJECT 環境變數做為專案 ID。

依下列項目規定為必填： BigQuery

查詢簽名： queryPermission('access_bigquery', <operation>, <options>)

注意： <operation> 是字串，可使用下列值：

write

<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 搭配使用的選項。設定 GOOGLE_CLOUD_PROJECT 的專案 ID 設定後，當 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

顯示名稱：傳回回應

說明：將回應傳回給呼叫端。

設定：無

依下列項目規定為必填： 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>)

附註：可控管是否可將特定的「Set-Cookie」標頭加入回應，這取決於 Cookie 名稱、網域、路徑、secure 屬性和到期日。

程式碼範例

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);
}