服务器端自定义模板权限

本文档简要介绍了服务器端自定义模板的权限。

每项权限均具有以下特点：

由需要相应权限的 API 进行检查。
由系统根据所使用的 API 在沙盒化 JavaScript 中自动检测。当为了实现快速反馈环而在自定义模板编辑器中进行修改时，以及为了验证是否强制执行了正确权限而编译代码时，系统均会执行此项自动检测。
可在自定义模板编辑器中修改，让权限更为具体。
可通过 queryPermission API 在沙盒化 JavaScript 中查询。

access_bigquery

显示名：Accesses BigQuery

说明：允许访问 Google Cloud Platform 上的 BigQuery。

配置：用于允许将指定项目、数据集和表的组合与 BigQuery 结合使用的选项。将项目 ID 配置设置为 GOOGLE_CLOUD_PROJECT 后，如果从 BigQuery API parameter 中排除 projectId，系统将允许把 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

显示名称：Accesses Google Firestore

说明：允许访问 Google Firestore。

配置：用于允许将指定项目和路径（支持通配符语法）的组合与 Firestore 结合使用的选项。将项目 ID 配置设置为 GOOGLE_CLOUD_PROJECT 后，如果从 Firestore API parameter 中排除 projectId，系统将允许把 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

显示名：Accesses 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

显示名称：Accesses 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

显示名：Reads cookie value(s)

说明：读取具有指定名称的 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);
}

日志记录

显示名称：Logs to console

说明：将日志记录到开发者控制台和跟踪代码管理器的预览模式。

配置：用于在生产环境中启用日志记录的选项。默认为仅在调试/预览模式下启用日志记录。如果权限遭拒，则 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

显示名称：Uses messages

说明：使用 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

显示名：Reads 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

显示名：Reads 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

显示名：Reads 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

显示名称：Reads HTTP request

说明：读取请求标头、查询参数、正文、路径或远程 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

显示名：Runs the container

说明：运行包含事件的容器

配置：无

所需者：runContainer

查询签名：queryPermission('run_container')

备注：此权限没有可用于缩小范围的字段，而且通常不会被查询。

send_http

显示名：Sends HTTP requests

说明：向指定网址发送 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

显示名：Sets a cookie

说明：设置具有指定名称和参数的 Cookie。

配置：一个包含允许的 Cookie 名称的表，您可以根据需要在名称、网域、路径、secure 属性和有效期方面对每个 Cookie 施加限制。

所需者：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);
}