API gắn thẻ phía máy chủ

Tài liệu này trình bày các API để gắn thẻ phía máy chủ.

addEventCallback

Đăng ký một hàm gọi lại sẽ được gọi ở cuối một sự kiện. Lệnh gọi lại sẽ được gọi khi tất cả các thẻ cho sự kiện đã thực thi. Lệnh gọi lại được truyền hai giá trị: mã nhận dạng của vùng chứa gọi hàm và một đối tượng chứa thông tin về sự kiện.

Khi được dùng trong một thẻ, API này sẽ được liên kết với sự kiện hiện tại. Khi được dùng trong một ứng dụng, API này phải được liên kết với một sự kiện cụ thể bằng cách dùng hàm bindToEvent của API runContainer. Hãy xem ví dụ để biết thêm thông tin.

Cú pháp

const addEventCallback = require('addEventCallback');

addEventCallback((containerId, eventData) => {
  // Take some action based on the event data.
});

Tham số

Tham số Loại Mô tả
callback hàm Hàm sẽ được gọi ở cuối sự kiện.

Đối tượng eventData chứa dữ liệu sau:

Tên khóa Loại Mô tả
tags Mảng Một mảng gồm các đối tượng dữ liệu thẻ. Mỗi thẻ đã kích hoạt trong sự kiện sẽ có một mục trong mảng này. Đối tượng dữ liệu thẻ chứa mã nhận dạng của thẻ (id), trạng thái thực thi (status) và thời gian thực thi (executionTime). Dữ liệu thẻ cũng sẽ bao gồm siêu dữ liệu thẻ bổ sung đã được định cấu hình trên thẻ.

Ví dụ

Trong một ứng dụng:

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

Trong thẻ:

const addEventCallback = require('addEventCallback');

addEventCallback((containerId, eventData) => {
  // This will be called at the end of the current event.
});

Các quyền liên quan

read_event_metadata

callLater

Lên lịch gọi một hàm để thực hiện không đồng bộ. Hàm này sẽ được gọi sau khi mã hiện tại trả về. Điều này tương đương với setTimeout(<function>, 0).

Ví dụ

const callLater = require('callLater');
const logToConsole = require('logToConsole');

callLater(() => {
  logToConsole('Logged asynchronously');
});

Cú pháp

callLater(function)

Tham số

Tham số Loại Mô tả
function hàm Hàm cần gọi.

Các quyền liên quan

Không có.

claimRequest

Sử dụng API này trong một ứng dụng để xác nhận yêu cầu. Sau khi một yêu cầu được xác nhận, vùng chứa sẽ không chạy các máy khách bổ sung.

API này sẽ gửi một ngoại lệ nếu được gọi trong thẻ hoặc biến. API này sẽ gửi một ngoại lệ nếu được gọi sau khi ứng dụng khách trả về (ví dụ: nếu được gọi trong một lệnh gọi lại không đồng bộ như trong callLater hoặc hàm runContainer onComplete).

Ứng dụng cần xác nhận yêu cầu bằng API này trước khi gọi API runContainer.

Ví dụ

const claimRequest = require('claimRequest');

claimRequest();

Cú pháp

claimRequest();

Các quyền liên quan

Không có.

computeEffectiveTldPlusOne

Trả về miền cấp cao nhất + 1 (eTLD+1) có hiệu lực của miền hoặc URL đã cho. eTLD+1 được tính bằng cách đánh giá miền dựa trên các quy tắc trong Danh sách hậu tố công khai. eTLD+1 thường là miền cấp cao nhất mà bạn có thể đặt cookie.

Nếu đối số là giá trị rỗng hoặc không xác định, thì giá trị đối số sẽ được trả về mà không thay đổi. Nếu không, đối số sẽ được chuyển đổi thành một chuỗi. Nếu đối số không phải là một miền hoặc URL hợp lệ, thì một chuỗi trống sẽ được trả về. Nếu máy chủ không thể tìm nạp danh sách hậu tố công khai, thì giá trị đối số sẽ được trả về mà không thay đổi.

Ví dụ

const computeEffectiveTldPlusOne = require('computeEffectiveTldPlusOne');

// Returns 'example.co.uk'
computeEffectiveTldPlusOne('analytics.example.co.uk');

// Returns 'example.co.uk'
computeEffectiveTldPlusOne('https://analytics.example.co.uk/path');

Cú pháp

computeEffectiveTldPlusOne(domainOrUrl);

Tham số

Tham số Loại Mô tả
domainOrUrl string Một miền hoặc URL để tính toán eTLD+1.

Các quyền liên quan

Không có.

createRegex

Tạo một phiên bản biểu thức chính quy mới và trả về phiên bản đó được bao bọc trong một đối tượng. Bạn không thể truy cập trực tiếp vào biểu thức chính quy. Tuy nhiên, bạn có thể truyền mã này vào API testRegex, String.replace(), String.match() và String.search().

Trả về null nếu biểu thức chính quy không hợp lệ hoặc Re2 không có trên máy chủ.

API này sử dụng chế độ triển khai Re2. Hình ảnh Docker của máy chủ phải ở phiên bản 2.0.0 trở lên.

Ví dụ

const createRegex = require('createRegex');

const domainRegex = createRegex('\\w+\\.com', 'i');

// Returns '/foobar'
'example.com/foobar'.replace(domainRegex, '');

Cú pháp

createRegex(pattern, flags);

Tham số

Tham số Loại Mô tả
pattern string Văn bản của biểu thức chính quy.
flags string Một chuỗi không bắt buộc chứa các cờ cho biểu thức chính quy đang được tạo. `g` (toàn cục) và `i` (không phân biệt chữ hoa chữ thường) được hỗ trợ. Tất cả các ký tự khác đều bị bỏ qua một cách âm thầm.

Các quyền liên quan

Không có.

Phiên bản hình ảnh tối thiểu

2.0.0

decodeUri

Giải mã mọi ký tự được mã hoá trong URI đã cho. Trả về một string biểu thị URI đã giải mã. Trả về undefined khi được cung cấp dữ liệu đầu vào không hợp lệ.

Ví dụ

const decodeUri = require('decodeUri');

const decodedUrl = decodeUri(data.encodedUrl);
if (decodedUrl) {
  // ...
}

Cú pháp

decodeUri(encoded_uri);

Tham số

Tham số Loại Mô tả
encoded_uri string Một URI đã được mã hoá bằng encodeUri() hoặc bằng các phương tiện khác.

Các quyền liên quan

Không có.

decodeUriComponent

Giải mã mọi ký tự được mã hoá trong thành phần URI được cung cấp. Trả về một string biểu thị thành phần URI đã giải mã. Trả về undefined khi có thông tin đầu vào không hợp lệ.

Ví dụ

const decodeUriComponent = require('decodeUriComponent');

const decodedQuery = decodeUriComponent(data.query);
if (decodedQuery) {
  // ...
}

Cú pháp

decodeUriComponent(encoded_uri_component);

Tham số

Tham số Loại Mô tả
encoded_uri_component string Một thành phần URI đã được mã hoá bằng encodeUriComponent() hoặc bằng các phương tiện khác.

Các quyền liên quan

Không có.

encodeUri

Trả về một Giá trị nhận dạng tài nguyên đồng nhất (URI) được mã hoá bằng cách thoát các ký tự đặc biệt. Trả về một string biểu thị chuỗi được cung cấp đã mã hoá dưới dạng URI.

Ví dụ

const encodeUri = require('encodeUri');
const sendHttpGet = require('sendHttpGet');

sendHttpGet('https://www.example.com/' + encodeUri(pathInput));

Cú pháp

encodeUri(uri);

Tham số

Tham số Loại Mô tả
uri string Một URI hoàn chỉnh.

Các quyền liên quan

Không có.

encodeUriComponent

Trả về một Giá trị nhận dạng tài nguyên đồng nhất (URI) được mã hoá bằng cách thoát các ký tự đặc biệt. Trả về một string biểu thị chuỗi đã cho được mã hoá dưới dạng một URI.

Ví dụ

const encodeUriComponent = require('encodeUriComponent');
const sendHttpGet = require('sendHttpGet');

sendHttpGet('https://www.example.com/?' + encodeUriComponent(queryInput));

Cú pháp

encodeUriComponent(str);

Tham số

Tham số Loại Mô tả
str string Một thành phần của URI.

Các quyền liên quan

Không có.

extractEventsFromMpv1

Dịch một yêu cầu Measurement Protocol phiên bản 1 đến thành một danh sách các sự kiện ở định dạng Giản đồ hợp nhất. Trả về danh sách các sự kiện được trích xuất. Đưa ra lỗi nếu yêu cầu không có định dạng chính xác.

Ví dụ

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.
  }
}

Cú pháp

extractEventsFromMpv1();

Các quyền liên quan

Cần có quyền read_request. Bạn phải định cấu hình quyền để cho phép truy cập vào ít nhất:

  • body
  • query parameters

extractEventsFromMpv2

Dịch một yêu cầu Measurement Protocol phiên bản 2 đến thành một danh sách các sự kiện ở định dạng Giản đồ hợp nhất. Trả về danh sách các sự kiện được trích xuất. Đưa ra lỗi nếu yêu cầu không có định dạng chính xác.

Ví dụ

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.
  }
}

Cú pháp

extractEventsFromMpv2();

Các quyền liên quan

Cần có quyền read_request. Bạn phải định cấu hình quyền để cho phép truy cập vào ít nhất:

  • body
  • query parameters

fromBase64

Giải mã một chuỗi được mã hoá base64. Trả về undefined nếu thông tin đầu vào không hợp lệ.

Cú pháp

fromBase64(base64EncodedString);

Tham số

Tham số Loại Mô tả
base64EncodedString string Chuỗi được mã hoá Base64.

Ví dụ

const fromBase64 = require('fromBase64');

const greeting = fromBase64('aGVsbG8=');
if (greeting === 'hello') {
  // ...
}

Các quyền liên quan

Không có.

generateRandom

Trả về một số (số nguyên) ngẫu nhiên trong dải ô đã cho.

Ví dụ

const generateRandom = require('generateRandom');

const randomValue = generateRandom(0, 10000000);

Cú pháp

generateRandom(min, max);

Tham số

Tham số Loại Mô tả
min number Giá trị tối thiểu có thể có của số nguyên được trả về (bao gồm cả giá trị này).
max number Giá trị tiềm năng tối đa của số nguyên được trả về (bao gồm cả giá trị này).

Các quyền liên quan

Không có.

getAllEventData

Trả về một bản sao của dữ liệu sự kiện.

Cú pháp

getAllEventData();

Các quyền liên quan

read_event_data

getClientName

Trả về một chuỗi chứa tên của ứng dụng hiện tại.

Cú pháp

getClientName();

Các quyền liên quan

read_container_data

getContainerVersion

Trả về một đối tượng chứa dữ liệu về vùng chứa hiện tại. Đối tượng được trả về sẽ có các trường sau:

{
  containerId: string,
  debugMode: boolean,
  environmentName: string,
  environmentMode: boolean,
  previewMode: boolean,
  version: string,
}

Ví dụ

const getContainerVersion = require('getContainerVersion');

const containerVersion = getContainerVersion();
const containerId = containerVersion['containerId'];
const isDebug = containerVersion['debugMode'];

Cú pháp

getContainerVersion();

Các quyền liên quan

read_container_data

getCookieValues

Trả về một mảng chứa các giá trị của tất cả cookie có tên đã cho.

Ví dụ

const getCookieValues = require('getCookieValues');

const lastVisit = getCookieValues('lastVisit')[0];
if (lastVisit) {
  // ...
}

Cú pháp

getCookieValues(name[, noDecode]);

Tham số

Tham số Loại Mô tả
name string Tên của cookie.
noDecode boolean Nếu true, các giá trị cookie sẽ không được giải mã trước khi được trả về. Giá trị mặc định là false.

Các quyền liên quan

get_cookies

getEventData

Trả về bản sao của giá trị tại đường dẫn đã cho trong dữ liệu sự kiện. Trả về undefined nếu không có dữ liệu sự kiện hoặc nếu không có giá trị tại đường dẫn đã cho.

Ví dụ

const getEventData = require('getEventData');

const campaignId = getEventData('campaign.id');
const itemId = getEventData('items.0.id');
const referrer = getEventData('page_referrer');

Tham số

Tham số Loại Mô tả
keyPath any Đường dẫn của khóa, trong đó các thành phần đường dẫn được phân tách bằng dấu chấm. Các thành phần của đường dẫn có thể là các khoá trong một đối tượng hoặc chỉ mục trong một mảng. Nếu keyPath không phải là một chuỗi, thì nó sẽ được chuyển đổi thành một chuỗi.

Cú pháp

getEventData(keyPath);

Các quyền liên quan

read_event_data

getGoogleAuth

Trả về một đối tượng uỷ quyền. Khi được dùng với sendHttpGet hoặc sendHttpRequest, đối tượng này sẽ bao gồm một tiêu đề uỷ quyền cho các API Google Cloud. API này sử dụng Thông tin đăng nhập mặc định của ứng dụng để tự động tìm thông tin đăng nhập trong môi trường máy chủ.

Ví dụ

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

Cú pháp

getGoogleAuth(scopes);

Tham số

Tham số Loại Mô tả
scopes Mảng Một mảng gồm các phạm vi API của Google theo OAuth 2.0 để yêu cầu quyền truy cập.

Các quyền liên quan

Cần có quyền use_google_credentials. Bạn phải định cấu hình quyền bằng một hoặc nhiều phạm vi được cho phép.

getGoogleScript

Truy xuất một tài nguyên từ một nhóm tập lệnh Google được xác định trước và trả về một promise có tập lệnh và siêu dữ liệu lưu vào bộ nhớ đệm được liên kết.

Lệnh hứa sẽ phân giải thành một đối tượng chứa hai khoá: script và metadata. Nếu yêu cầu không thành công, lời hứa sẽ từ chối bằng khoá reason.

Đối tượng metadata sẽ chứa siêu dữ liệu lưu vào bộ nhớ đệm sau đây dựa trên tiêu đề phản hồi tài nguyên; mỗi trường sẽ chỉ xuất hiện nếu tiêu đề tương ứng xuất hiện trong phản hồi tài nguyên.

{
  'cache-control': string,
  'expires': string,
  'last-modified': string,
}

Ví dụ

const getGoogleScript = require('getGoogleScript');

getGoogleScript('ANALYTICS').then((result) => {
  // Operate on result.script and result.metadata here.
});

Cú pháp

getGoogleScript(script[, options]);

Tham số

Tham số Loại Mô tả
script string Tên của tập lệnh. Các tập lệnh được hỗ trợ là 'ANALYTICS', 'GTAG' và 'GTM'.

Lựa chọn 'ANALYTICS' sẽ tìm nạp tập lệnh Google Analytics từ https://www.google-analytics.com/analytics.js.

Lựa chọn 'GTAG' sẽ tìm nạp tập lệnh thẻ toàn trang web (gtag.js) từ https://www.googletagmanager.com/gtag/js.

Lựa chọn 'GTM' sẽ tìm nạp tập lệnh Trình quản lý thẻ của Google từ https://www.googletagmanager.com/gtm.js.
options object Các lựa chọn yêu cầu không bắt buộc. Hãy xem các lựa chọn được hỗ trợ bên dưới.

Lựa chọn

Phương thức Loại Mô tả
id string Áp dụng cho 'GTAG' có mã đo lường gtag và 'GTM' có mã nhận dạng vùng chứa trên web (ví dụ: GTM-XXXX).
debug any Nếu có giá trị, hãy yêu cầu và trả về phiên bản gỡ lỗi của tập lệnh đo lường.
timeout number Thời gian chờ yêu cầu tính bằng mili giây; các giá trị không dương sẽ bị bỏ qua. Nếu yêu cầu hết thời gian chờ, lệnh gọi lại sẽ được gọi bằng undefined cho giá trị tập lệnh và {} cho đối tượng siêu dữ liệu.

Các khoá tuỳ chọn không nhận dạng được sẽ bị bỏ qua.

Các quyền liên quan

Cần có quyền send_http. Bạn phải định cấu hình quyền để cho phép truy cập vào ít nhất:

  • Cho phép Google Domains

getRemoteAddress

Trả về một giá trị string biểu thị địa chỉ IP nơi yêu cầu bắt nguồn, ví dụ: 12.345.67.890 cho IPv4 hoặc 2001:0db8:85a3:0:0:8a2e:0370:7334 cho IPv6, bằng cách đọc các tiêu đề yêu cầu như Forwarded và X-Forwarded-For. Lưu ý: API này cố gắng hết sức để phát hiện IP ban đầu, nhưng không thể đảm bảo rằng kết quả là chính xác.

Cú pháp

getRemoteAddress();

Các quyền liên quan

Cần có quyền read_request. Bạn phải định cấu hình quyền để cho phép truy cập vào ít nhất:

  • Tiêu đề Forwarded và X-Forwarded-For
  • Địa chỉ IP từ xa

getRequestBody

Trả về nội dung yêu cầu dưới dạng string (nếu có) hoặc undefined (nếu không).

Cú pháp

getRequestBody();

Các quyền liên quan

read_request

getRequestHeader

Trả về giá trị của tiêu đề yêu cầu được đặt tên dưới dạng chuỗi, nếu có hoặc undefined nếu không. Nếu tiêu đề được lặp lại, các giá trị được trả về sẽ được kết hợp với nhau bằng ', '.

Ví dụ

const getRequestHeader = require('getRequestHeader');

const host = getRequestHeader('host');

Cú pháp

getRequestHeader(headerName);

Tham số

Tham số Loại Mô tả
headerName string Tên tiêu đề. Giá trị này không phân biệt chữ hoa chữ thường.

Các quyền liên quan

read_request

getRequestMethod

Trả về phương thức yêu cầu, ví dụ: 'GET' hoặc 'POST', dưới dạng một chuỗi.

Ví dụ

const getRequestMethod = require('getRequestMethod');

if (getRequestMethod() === 'POST') {
  // Handle the POST request here.
}

Cú pháp

getRequestMethod();

Các quyền liên quan

Không có.

getRequestPath

Trả về đường dẫn yêu cầu mà không có chuỗi truy vấn. Ví dụ: nếu URL là '/foo?id=123', thì hàm này sẽ trả về '/foo'. Tự động xoá tiền tố URL vùng chứa Máy chủ khỏi đường dẫn. Ví dụ: nếu URL vùng chứa phía máy chủ là https://example.com/analytics và đường dẫn yêu cầu là '/analytics/foo', thì hàm này sẽ trả về '/foo'.

Ví dụ

const getRequestPath = require('getRequestPath');

const requestPath = getRequestPath();
if (requestPath === '/') {
  // Handle a request for the root path.
}

Cú pháp

getRequestPath();

Các quyền liên quan

read_request

getRequestQueryParameter

Trả về giá trị đã giải mã của tham số chuỗi truy vấn được đặt tên dưới dạng string hoặc undefined nếu tham số không có. Nếu tham số được lặp lại trong chuỗi truy vấn, thì giá trị đầu tiên xuất hiện trong chuỗi truy vấn sẽ được trả về.

Ví dụ

const getRequestQueryParameter = require('getRequestQueryParameter');

const query = getRequestQueryParameter('query');
if (query) {
  // Process query here.
}

Cú pháp

getRequestQueryParameter(name);

Tham số

Tham số Loại Mô tả
name string Tên tham số truy vấn.

Các quyền liên quan

read_request

getRequestQueryParameters

Trả về các tham số truy vấn của yêu cầu HTTP đến dưới dạng một đối tượng ánh xạ tên tham số truy vấn đến (các) giá trị tương ứng. Tên và giá trị của tham số được giải mã.

Ví dụ

const getRequestQueryParameters = require('getRequestQueryParameters');

const queryParameters = getRequestQueryParameters();
if (queryParameters['search']) {
  // Handle the search query here.
  const maxResults = queryParameters['max_results'];
}

Cú pháp

getRequestQueryParameters();

Các quyền liên quan

read_request

getRequestQueryString

Trả về cụm từ tìm kiếm trong yêu cầu dưới dạng một chuỗi, không có dấu chấm hỏi ở đầu hoặc một chuỗi trống nếu URL yêu cầu không có chuỗi truy vấn.

Ví dụ

const getRequestQueryString = require('getRequestQueryString');

const queryString = getRequestQueryString();
if (queryString !== '') {
  // Handle the query string.
}

Cú pháp

getRequestQueryString();

Các quyền liên quan

read_request

getTimestamp

Không dùng nữa. Ưu tiên getTimestampMillis.

Trả về một số biểu thị thời gian hiện tại tính bằng mili giây kể từ thời gian bắt đầu của hệ thống Unix, do Date.now() trả về.

Cú pháp

getTimestamp();

Các quyền liên quan

Không có.

getTimestampMillis

Trả về một số biểu thị thời gian hiện tại tính bằng mili giây kể từ thời gian bắt đầu của hệ thống Unix, do Date.now() trả về.

Cú pháp

getTimestampMillis();

Các quyền liên quan

Không có.

getType

Trả về một chuỗi mô tả kiểu của giá trị đã cho.

Loại nội dung nhập Giá trị trả về
string 'string'
number 'number'
boolean 'boolean'
null 'null'
undefined 'undefined'
Mảng 'array'
Đối tượng 'object'
Chức năng 'function'

Ví dụ

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

Cú pháp

getType(value);

Tham số

Tham số Loại Mô tả
value any Giá trị nhập.

Các quyền liên quan

Không có.

hmacSha256

Tính toán chữ ký được mã hoá bằng Mã xác thực thông báo dựa trên hàm băm (HMAC) với SHA-256. Mặc định là mã hoá base64url.

Để sử dụng API này, hãy đặt biến môi trường SGTM_CREDENTIALS trên máy chủ thành đường dẫn của một tệp khoá JSON được mã hoá theo UTF-8 có định dạng sau:

{
  "keys": {
    "key1": "YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXowMTIzNDU2Nzg5",
    "key2": "OTg3NjU0MzIxMHp5eHd2dXRzcnFwb25tbGtqaWhnZmVkY2Jh",
    ...
  }
}

Các giá trị này là khoá HMAC được mã hoá base64. Văn bản JSON không được bắt đầu bằng một dấu đánh dấu thứ tự byte.

Ví dụ

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;

Cú pháp

hmacSha256(data, keyId, options)

Tham số

Tham số Loại Mô tả
data string Dữ liệu để tính giá trị HMAC.
keyId string Mã khoá trong tệp khoá JSON đề cập đến khoá cần sử dụng.
options object Cấu hình API không bắt buộc. (Xem phần Tuỳ chọn bên dưới.)

Lựa chọn

Phương thức Loại Mô tả
outputEncoding string Chỉ định định dạng mã hoá cho giá trị trả về. Các định dạng được hỗ trợ là hex, base64 hoặc base64url. Mặc định là base64url nếu bạn không chỉ định.

Các quyền liên quan

use_custom_private_keys

Phiên bản hình ảnh tối thiểu

1.0.0

isRequestMpv1

Trả về true nếu yêu cầu đến là yêu cầu Measurement Protocol phiên bản 1, hoặc false nếu không.

Ví dụ

const isRequestMpv1 = require('isRequestMpv1');

if (isRequestMpv1()) {
  // Handle Measurement Protocol V1 request.
  const events = extractEventsFromMpv1();
}

Cú pháp

isRequestMpv1();

Các quyền liên quan

Không có.

isRequestMpv2

Trả về true nếu yêu cầu đến là yêu cầu Measurement Protocol phiên bản 2, hoặc false nếu không.

Ví dụ

const isRequestMpv2 = require('isRequestMpv2');

if (isRequestMpv2()) {
  // Handle Measurement Protocol V2 request.
  const events = extractEventsFromMpv2();
}

Cú pháp

isRequestMpv2();

Các quyền liên quan

Không có.

logToConsole

Ghi(các) đối số của nó vào bảng điều khiển.

Bạn có thể xem các nhật ký này trong Trình khám phá nhật ký trong Bảng điều khiển Google Cloud. Từ Logs Explorer, hãy chạy truy vấn logName =~ "stdout" để xem các mục nhật ký do API này tạo.

Ví dụ

const logToConsole = require('logToConsole');

const that = 123;
const those = { ... };
logToConsole('that is: ', that, ' and those is: ', those);

Cú pháp

logToConsole(argument1[, argument2, ...]);

Tham số

API này lấy một hoặc nhiều đối số, mỗi đối số được chuyển đổi thành một chuỗi (nếu cần) và được ghi vào bảng điều khiển.

Các quyền liên quan

logging

makeInteger

Chuyển đổi giá trị đã cho thành number (số nguyên).

Cú pháp

makeInteger(value);

Tham số

Tham số Loại Mô tả
value mọi loại Giá trị cần chuyển đổi.

Các quyền liên quan

Không có.

makeNumber

Chuyển đổi giá trị đã cho thành số.

Cú pháp

makeNumber(value);

Tham số

Tham số Loại Mô tả
value mọi loại Giá trị cần chuyển đổi.

Các quyền liên quan

Không có.

makeString

Trả về giá trị đã cho dưới dạng chuỗi.

Cú pháp

makeString(value);

Tham số

Tham số Loại Mô tả
value mọi loại Giá trị cần chuyển đổi.

Các quyền liên quan

Không có.

makeTableMap

Chuyển đổi một đối tượng bảng đơn giản có hai cột thành một Map. Thao tác này được dùng để thay đổi một trường mẫu SIMPLE_TABLE có 2 cột thành một định dạng dễ quản lý hơn.

Ví dụ: hàm này có thể chuyển đổi một đối tượng bảng:

[
  {'key': 'k1', 'value': 'v1'},
  {'key': 'k2', 'value': 'v2'}
]

vào Bản đồ:

{
  'k1': 'v1',
  'k2': 'v2'
}

Trả về một Object: Map đã chuyển đổi của các cặp khoá-giá trị đã được thêm vào đối tượng này hoặc null nếu không.

Cú pháp

makeTableMap(tableObj, keyColumnName, valueColumnName);

Tham số

Tham số Loại Mô tả
tableObj List (Danh sách) Đối tượng bảng cần chuyển đổi. Đây là danh sách các bản đồ, trong đó mỗi Map đại diện cho một hàng trong bảng. Mỗi tên thuộc tính trong một đối tượng hàng là tên cột và giá trị thuộc tính là giá trị cột trong hàng.
keyColumnName string Tên của cột có các giá trị sẽ trở thành khoá trong Map đã chuyển đổi.
valueColumnName string Tên của cột có các giá trị sẽ trở thành giá trị trong Map đã chuyển đổi.

Các quyền liên quan

Không có.

parseUrl

Trả về một đối tượng chứa tất cả các thành phần của một URL nhất định, tương tự như đối tượng URL.

API này sẽ trả về undefined cho mọi URL có định dạng không hợp lệ. Đối với các URL có định dạng phù hợp, các trường không có trong chuỗi URL sẽ có giá trị là một chuỗi trống hoặc trong trường hợp searchParams, một đối tượng trống.

Đối tượng được trả về sẽ có các trường sau:

{
  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,
}

Ví dụ

const parseUrl = require('parseUrl');

const urlObject = parseUrl('https://abc:xyz@example.com:8080/foo?param=val%2Cue#bar');

Cú pháp

parseUrl(url);

Tham số

Tham số Loại Mô tả
url string URL đầy đủ sẽ được phân tích cú pháp.

Các quyền liên quan

Không có.

returnResponse

Xoá phản hồi mà trước đó được đặt bởi các mẫu khác bằng cách sử dụng các API sửa đổi phản hồi, bao gồm setCookie, setPixelResponse, setResponseBody, setResponseHeader và setResponseStatus. Mặc định là mã trạng thái HTTP 200, nội dung trống và không có tiêu đề.

Bạn nên sử dụng API này từ một mẫu ứng dụng.

Cú pháp

returnResponse();

Ví dụ

Xem ví dụ về runContainer.

Các quyền liên quan

return_response

runContainer

Chạy logic vùng chứa (biến, điều kiện kích hoạt, thẻ) trong phạm vi của một sự kiện. Nếu API này được gọi trong quá trình thực thi vùng chứa, thì vùng chứa sẽ chạy lại.

Các lệnh gọi lại onComplete và onStart nhận được một hàm có tên là bindToEvent. Sử dụng bindToEvent để chạy một API trong bối cảnh của sự kiện. Hãy xem ví dụ addEventCallback để biết thêm thông tin chi tiết.

Bạn nên sử dụng API này từ một mẫu ứng dụng.

Ví dụ

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

Cú pháp

runContainer(event, onComplete, onStart);

Tham số

Tham số Loại Mô tả
event object Thông số sự kiện.
onComplete hàm Một lệnh gọi lại được gọi sau khi tất cả các thẻ hoàn tất việc kích hoạt.
onStart hàm Một lệnh gọi lại được gọi ngay lập tức, trước khi các thẻ bắt đầu kích hoạt.

Các quyền liên quan

run_container

sendEventToGoogleAnalytics

Gửi một sự kiện bằng cách sử dụng Dữ liệu sự kiện chung đến Google Analytics và trả về một promise phân giải thành một đối tượng có khoá location hoặc từ chối thành một đối tượng có khoá reason. Đích đến, Google Analytics 4, dựa trên mã đo lường trong dữ liệu sự kiện.

Trường location được đặt thành tiêu đề location, nếu có.

Ví dụ

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

Cú pháp

sendEventToGoogleAnalytics(event);

Tham số

Tham số Loại Mô tả
event object Sự kiện ở định dạng Giản đồ hợp nhất.

Các quyền liên quan

Cần có quyền send_http. Bạn phải định cấu hình quyền để cho phép truy cập vào ít nhất:

  • Cho phép Google Domains

sendHttpGet

Đưa ra yêu cầu HTTP GET đến URL đã chỉ định và trả về một lời hứa sẽ phân giải bằng kết quả sau khi yêu cầu hoàn tất hoặc hết thời gian chờ.

Kết quả được phân giải là một đối tượng chứa 3 khoá: statusCode, headers và body. Nếu yêu cầu không thành công (ví dụ: URL không hợp lệ, không có tuyến đường đến máy chủ lưu trữ, lỗi thương lượng SSL, v.v.), thì lời hứa sẽ từ chối bằng: {reason: 'failed'}. Nếu bạn đặt tuỳ chọn timeout và yêu cầu hết thời gian chờ, thì lời hứa sẽ từ chối bằng: {reason: 'timed_out'}

Ví dụ

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

Cú pháp

sendHttpGet(url[, options]);

Tham số

Tham số Loại Mô tả
url string URL được yêu cầu.
options object Không bắt buộc đối với các lựa chọn yêu cầu. (Xem phần Tuỳ chọn bên dưới.)

Lựa chọn

Phương thức Loại Mô tả
headers string Tiêu đề yêu cầu bổ sung.
timeout number Thời gian chờ (tính bằng mili giây) trước khi yêu cầu bị huỷ. Giá trị mặc định là 15000.
authorization object Đối tượng uỷ quyền Không bắt buộc từ lệnh gọi đến getGoogleAuth để thêm tiêu đề uỷ quyền khi đưa ra yêu cầu đến googleapis.com.

Các quyền liên quan

send_http

sendHttpRequest

Gửi yêu cầu HTTP đến URL đã chỉ định và trả về một promise (lời hứa) sẽ phân giải bằng phản hồi sau khi yêu cầu hoàn tất hoặc hết thời gian chờ.

Kết quả được phân giải là một đối tượng chứa 3 khoá: statusCode, headers và body. Nếu yêu cầu không thành công (ví dụ: URL không hợp lệ, không có tuyến đường đến máy chủ lưu trữ, lỗi thương lượng SSL, v.v.), thì lời hứa sẽ từ chối bằng: {reason: 'failed'}. Nếu bạn đặt tuỳ chọn timeout và yêu cầu hết thời gian chờ, thì lời hứa sẽ từ chối bằng: {reason: 'timed_out'}

Ví dụ

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

Cú pháp

sendHttpRequest(url[, options[, body]]);

Tham số

Tham số Loại Mô tả
url string URL được yêu cầu.
options object Không bắt buộc đối với các lựa chọn yêu cầu. (Xem phần Tuỳ chọn bên dưới.)
body string Nội dung yêu cầu không bắt buộc.

Lựa chọn

Phương thức Loại Mô tả
headers string Tiêu đề yêu cầu bổ sung.
method object Phương thức yêu cầu. Giá trị mặc định là GET.
timeout number Thời gian chờ (tính bằng mili giây) trước khi yêu cầu bị huỷ. Giá trị mặc định là 15000.
authorization object Đối tượng uỷ quyền Không bắt buộc từ lệnh gọi đến getGoogleAuth để thêm tiêu đề uỷ quyền khi đưa ra yêu cầu đến googleapis.com.

Các quyền liên quan

send_http

sendPixelFromBrowser

Gửi một lệnh đến trình duyệt để tải URL được cung cấp dưới dạng thẻ <img>. Giao thức lệnh này được hỗ trợ trong Thẻ Google cho GA4 và thẻ web Google Analytics: Sự kiện GA. Bạn phải định cấu hình URL vùng chứa máy chủ. Hãy xem hướng dẫn để biết thêm thông tin chi tiết.

API này trả về false nếu yêu cầu đến không hỗ trợ giao thức lệnh hoặc nếu phản hồi đã được xoá. Nếu không, API này sẽ trả về true.

Ví dụ:

const sendPixelFromBrowser = require('sendPixelFromBrowser');

sendPixelFromBrowser('https://example.com/?id=123');

Cú pháp

sendPixelFromBrowser(url)

Tham số

Tham số Loại Mô tả
url string URL để gửi đến trình duyệt.

Các quyền liên quan

send_pixel_from_browser

setCookie

Đặt hoặc xoá một cookie bằng các lựa chọn đã chỉ định.

Để xoá một cookie, bạn phải đặt một cookie có cùng đường dẫn và miền mà cookie đó được tạo, đồng thời chỉ định cho cookie đó một giá trị hết hạn trong quá khứ, ví dụ: "Thu, 01 Jan 1970 00:00:00 GMT".

Xin lưu ý rằng bạn phải gọi returnResponse để phản hồi được gửi lại cho ứng dụng khách.

Ví dụ

const setCookie = require('setCookie');

// Sets an httpOnly cookie with a max-age of 3600.
setCookie('cookieName', 'cookieValue', {'max-age': 3600, httpOnly: true});

Cú pháp

setCookie(name, value[, options[, noEncode]]);

Tham số

Tham số Loại Mô tả
name string Tên cookie. Tên này không phân biệt chữ hoa chữ thường.
value string Giá trị cookie.
options object Thuộc tính cookie không bắt buộc:domain, expires, fallbackDomain, httpOnly, max-age, path, secure và sameSite. (Xem phần Lựa chọn bên dưới.)
noEncode boolean Nếu đúng, giá trị cookie sẽ không được mã hoá. Giá trị mặc định là false.

Lựa chọn

  • domain: Máy chủ lưu trữ mà cookie sẽ được gửi đến. Nếu được đặt thành giá trị đặc biệt "auto", thì máy chủ lưu trữ sẽ được tự động tính toán bằng cách sử dụng chiến lược sau:

    • eTLD+1 của tiêu đề Forwarded (nếu có).
    • eTLD+1 của tiêu đề X-Forwarded-Host (nếu có).
    • eTLD+1 của tiêu đề Host.

  • expires: Thời gian tồn tại tối đa của cookie. Đây phải là chuỗi ngày ở định dạng UTC, ví dụ: "Sat, 26 Oct 1985 08:21:00 GMT". Nếu bạn đặt cả expires và max-age, thì max-age sẽ được ưu tiên.

  • httpOnly: Ngăn JavaScript truy cập vào cookie nếu true.

  • max-age: Số giây cho đến khi cookie hết hạn. Số 0 hoặc số âm sẽ khiến cookie hết hạn ngay lập tức. Nếu bạn đặt cả expires và max-age, thì max-age sẽ được ưu tiên.

  • path: Một đường dẫn phải có trong URL được yêu cầu, nếu không trình duyệt sẽ không gửi tiêu đề Cookie.

  • secure: Nếu được đặt thành true, cookie sẽ chỉ được gửi đến máy chủ khi một yêu cầu được thực hiện từ điểm cuối https:.

  • sameSite: Xác nhận rằng cookie không được gửi cùng với các yêu cầu trên nhiều nguồn gốc. Phải là 'strict', 'lax' hoặc 'none'.

Các quyền liên quan

set_cookie

setPixelResponse

Đặt nội dung phản hồi thành GIF 1x1, đặt tiêu đề Content-Type thành "image/gif", đặt tiêu đề lưu vào bộ nhớ đệm để các tác nhân người dùng sẽ không lưu phản hồi vào bộ nhớ đệm và đặt trạng thái phản hồi thành 200.

Xin lưu ý rằng bạn phải gọi returnResponse để phản hồi được gửi lại cho ứng dụng khách.

Cú pháp

setPixelResponse();

Các quyền liên quan

Cần có quyền access_response. Bạn phải định cấu hình quyền để cho phép truy cập vào ít nhất:

  • headers – Phải cho phép các khoá sau
    • content-type
    • cache-control
    • expires
    • pragma
  • body
  • status

setResponseBody

Đặt nội dung phản hồi thành đối số.

Xin lưu ý rằng bạn phải gọi returnResponse để phản hồi được gửi lại cho ứng dụng khách.

Cú pháp

setResponseBody(body[, encoding]);

Tham số

Tham số Loại Mô tả
body string Giá trị cần đặt làm nội dung phản hồi.
encoding string Bộ mã hoá ký tự của nội dung phản hồi (mặc định là 'utf8'). Các giá trị được hỗ trợ bao gồm 'ascii', 'utf8', 'utf16le', 'ucs2', 'base64', 'latin1', 'binary' và 'hex'.

Các quyền liên quan

Cần có quyền access_response. Bạn phải định cấu hình quyền để cho phép truy cập vào ít nhất:

  • body

setResponseHeader

Đặt một tiêu đề trong phản hồi sẽ được trả về. Nếu trước đó API này đã đặt một tiêu đề có tên này (không phân biệt chữ hoa chữ thường), thì lệnh gọi sau sẽ ghi đè hoặc xoá giá trị do phương thức gọi trước đó đặt.

Xin lưu ý rằng bạn phải gọi returnResponse để phản hồi được gửi lại cho ứng dụng khách.

Cú pháp

setResponseHeader(name, value);

Tham số

Tham số Loại Mô tả
name string Tên tiêu đề. Tên tiêu đề HTTP không phân biệt chữ hoa chữ thường, vì vậy tên tiêu đề sẽ được viết thường.
value string undefined Giá trị tiêu đề. Nếu là giá trị rỗng hoặc không xác định, thì thao tác này sẽ xoá tiêu đề có tên khỏi phản hồi sẽ được trả về.

Các quyền liên quan

Cần có quyền access_response. Bạn phải định cấu hình quyền để cho phép truy cập vào ít nhất:

  • headers

setResponseStatus

Đặt mã trạng thái HTTP của phản hồi sẽ được trả về.

Xin lưu ý rằng bạn phải gọi returnResponse để phản hồi được gửi lại cho ứng dụng khách.

Cú pháp

setResponseStatus(statusCode);

Tham số

Tham số Loại Mô tả
statusCode number Mã trạng thái HTTP sẽ được trả về.

Các quyền liên quan

Cần có quyền access_response. Bạn phải định cấu hình quyền để cho phép truy cập vào ít nhất:

  • status

sha256

Tính toán thông báo SHA-256 của dữ liệu đầu vào và gọi một lệnh gọi lại với thông báo được mã hoá theo chuẩn base64, trừ phi đối tượng options chỉ định một phương thức mã hoá đầu ra khác.

Chữ ký và hành vi của API này khớp với API sha256 cho các vùng chứa web; tuy nhiên, Mẫu tuỳ chỉnh trong vùng chứa máy chủ nên sử dụng API sha256Sync để có mã đơn giản hơn.

Ví dụ

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

Cú pháp

sha256(input, onSuccess, options = undefined);

Tham số

Tham số Loại Mô tả
input string Chuỗi cần băm.
onSuccess hàm Được gọi bằng bản tóm tắt kết quả, được mã hoá bằng base64, trừ phi đối tượng options chỉ định một phương thức mã hoá đầu ra khác.
options object Đối tượng Không bắt buộc để chỉ định phương thức mã hoá đầu ra. Nếu được chỉ định, đối tượng phải chứa khoá outputEncoding có giá trị là một trong các giá trị base64 hoặc hex.

Các quyền liên quan

Không có.

sha256Sync

Tính toán và trả về thông báo SHA-256 của dữ liệu đầu vào, được mã hoá ở base64, trừ phi đối tượng options chỉ định một phương thức mã hoá đầu ra khác.

Ví dụ

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

Cú pháp

sha256Sync(input, options = undefined);

Tham số

Tham số Loại Mô tả
input string Chuỗi cần băm.
options object Đối tượng Không bắt buộc để chỉ định phương thức mã hoá đầu ra. Nếu được chỉ định, đối tượng phải chứa khoá outputEncoding có giá trị là một trong các giá trị base64 hoặc hex.

Các quyền liên quan

Không có.

templateDataStorage

Trả về một đối tượng có các phương thức để truy cập vào bộ nhớ dữ liệu mẫu. Bộ nhớ dữ liệu mẫu cho phép chia sẻ dữ liệu giữa các lần thực thi của một mẫu duy nhất. Dữ liệu được lưu trữ trong bộ nhớ lưu trữ dữ liệu mẫu sẽ vẫn tồn tại trên máy chủ đang chạy vùng chứa. Trong hầu hết các trường hợp, có nhiều máy chủ chạy vùng chứa, vì vậy, việc lưu trữ dữ liệu trong bộ nhớ dữ liệu mẫu không đảm bảo rằng mọi yêu cầu tiếp theo sẽ có quyền truy cập vào dữ liệu.

"data" trong tên "templateDataStorage" đề cập đến việc chỉ các loại dữ liệu thuần tuý, không phải hàm mới có thể được lưu trữ bằng API này. Mọi hàm hoặc thông tin tham chiếu đến các hàm được truyền đến API sẽ được lưu trữ dưới dạng null.

Cú pháp

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

Ví dụ

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

Các quyền liên quan

access_template_storage

testRegex

Kiểm thử một chuỗi dựa trên biểu thức chính quy được tạo thông qua API createRegex. Trả về true nếu biểu thức chính quy khớp. Nếu không, hàm này sẽ trả về false.

Biểu thức chính quy được tạo bằng cờ toàn cầu là biểu thức có trạng thái. Hãy xem tài liệu về RegExp để biết thông tin chi tiết.

Ví dụ

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

Cú pháp

testRegex(regex, string);

Tham số

Tham số Loại Mô tả
regex Đối tượng Biểu thức chính quy để kiểm thử, được trả về từ API createRegex.
string string Chuỗi kiểm thử để kiểm thử.

Các quyền liên quan

Không có.

toBase64

Mã hoá một chuỗi dưới dạng base64 hoặc base64url. Mã hoá base64 theo mặc định.

Cú pháp

toBase64(input, options);

Tham số

Tham số Loại Mô tả
input string Chuỗi cần mã hoá.
options object Cấu hình API không bắt buộc. (Xem phần Tuỳ chọn bên dưới.)

Lựa chọn

Phương thức Loại Mô tả Phiên bản tối thiểu
urlEncoding boolean Nếu đúng, kết quả sẽ được mã hoá bằng định dạng base64url. 1.0.0

Ví dụ

const toBase64 = require('toBase64');

const base64Hello = toBase64('hello');
const base64UrlHello = toBase64('hello', {urlEncoding: true});

Các quyền liên quan

Không có.

BigQuery

Trả về một đối tượng cung cấp các hàm BigQuery.

Hàm BigQuery.insert cho phép ghi dữ liệu vào một bảng BigQuery. Phương thức này trả về một promise sẽ phân giải khi chèn thành công hoặc từ chối khi gặp lỗi.

Khi quá trình chèn thành công, lời hứa sẽ được thực hiện mà không có đối số.

Khi quá trình chèn không thành công, lệnh hứa sẽ từ chối bằng một danh sách các đối tượng chứa lý do gây ra lỗi và có thể là một đối tượng hàng nếu xảy ra lỗi. Có thể một phần của yêu cầu được hoàn tất thành công, trong khi các phần khác thì không. Trong trường hợp này, lời hứa sẽ bị từ chối kèm theo danh sách lỗi cho từng hàng có đối tượng hàng để giúp phân biệt những hàng nào đã được chèn (Xem Ví dụ về lỗi bên dưới). Hãy xem tài liệu của BigQuery về thông báo lỗi để biết thêm thông tin.

Cú pháp

BigQuery.insert(connectionInfo, rows[, options]);

Tham số

Tham số Loại Mô tả
connectionInfo object Xác định thông tin cần thiết để kết nối với một bảng BigQuery. Có một tham số không bắt buộc và hai tham số bắt buộc:
  • projectId – Không bắt buộc Mã dự án trên Google Cloud Platform. Nếu bạn bỏ qua, projectId sẽ được truy xuất từ biến môi trường GOOGLE_CLOUD_PROJECT miễn là bạn đặt chế độ cài đặt quyền access_bigquery cho mã dự án thành * hoặc GOOGLE_CLOUD_PROJECT. Nếu vùng chứa máy chủ đang chạy trên Google Cloud, thì GOOGLE_CLOUD_PROJECT sẽ được đặt thành mã dự án của Google Cloud.
  • datasetId – Mã tập dữ liệu BigQuery.
  • tableId – Mã bảng BigQuery.
rows Mảng Các hàng cần chèn vào bảng.
options object Các lựa chọn yêu cầu không bắt buộc. Các lựa chọn được hỗ trợ là: ignoreUnknownValues và skipInvalidRows. Hệ thống sẽ bỏ qua các khoá tuỳ chọn không xác định. (Xem phần Lựa chọn bên dưới.)

Lựa chọn

Tham số Loại Mô tả
ignoreUnknownValues boolean Nếu bạn đặt thành true, thì hãy chấp nhận những hàng chứa các giá trị không khớp với giản đồ. Các giá trị không xác định sẽ bị bỏ qua. Giá trị mặc định là false.
skipInvalidRows boolean Nếu bạn đặt thành true, thì hãy chèn tất cả các hàng hợp lệ của một yêu cầu, ngay cả khi có các hàng không hợp lệ. Giá trị mặc định là false.

Ví dụ về lỗi

Lỗi không tìm thấy mô-đun có nghĩa là vùng chứa máy chủ của bạn có thể đang chạy một phiên bản cũ hơn của hình ảnh mà chưa bao gồm mô-đun BigQuery. Vui lòng triển khai lại vùng chứa máy chủ bằng cùng chế độ cài đặt thông qua tập lệnh triển khai của chúng tôi. Mô-đun này sẽ tự động được đưa vào sau khi thao tác hoàn tất.

Lỗi không chèn thường có một đối tượng lỗi có khoá reason:

[{reason: 'invalid'}]

Lỗi chèn có thể chứa nhiều đối tượng lỗi với một mảng errors và một đối tượng row. Sau đây là ví dụ về phản hồi lỗi khi chèn 2 hàng nhưng chỉ có 1 hàng bị lỗi:

[
  {
    "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
    }
  }
]

Ví dụ

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

Các quyền liên quan

access_bigquery

Firestore

Trả về một đối tượng cung cấp các hàm Firestore.

API này chỉ hỗ trợ Firestore ở chế độ Gốc, chứ không hỗ trợ Firestore ở chế độ Datastore. Ngoài ra, API này chỉ hỗ trợ việc sử dụng cơ sở dữ liệu mặc định.

Firestore.read

Hàm Firestore.read đọc dữ liệu từ một tài liệu Firestore và trả về một promise phân giải thành một đối tượng chứa 2 khoá: id và data. Nếu tài liệu không tồn tại, thì lời hứa sẽ từ chối bằng một đối tượng chứa khoá reason bằng not_found.

Cú pháp

Firestore.read(path[, options]);

Tham số

Tham số Loại Mô tả
path string Đường dẫn đến tài liệu hoặc bộ sưu tập. Không được bắt đầu hoặc kết thúc bằng dấu "/".
options object Không bắt buộc đối với các lựa chọn yêu cầu. Các lựa chọn được hỗ trợ là: projectId, disableCache và transaction. Các khoá tuỳ chọn không xác định sẽ bị bỏ qua. (Xem phần Lựa chọn bên dưới.)

Lựa chọn

Tham số Loại Mô tả
projectId string Không bắt buộc. Mã dự án trên Google Cloud Platform. Nếu bạn bỏ qua, projectId sẽ được truy xuất từ biến môi trường GOOGLE_CLOUD_PROJECT miễn là bạn đặt chế độ cài đặt quyền access_firestore cho mã dự án thành * hoặc GOOGLE_CLOUD_PROJECT. Nếu vùng chứa máy chủ đang chạy trên Google Cloud, thì GOOGLE_CLOUD_PROJECT sẽ được đặt thành mã dự án của Google Cloud.
disableCache boolean Không bắt buộc. Xác định xem có tắt bộ nhớ đệm hay không. Bộ nhớ đệm được bật theo mặc định, bộ nhớ này sẽ lưu kết quả vào bộ nhớ đệm trong thời gian của yêu cầu.
transaction string Không bắt buộc. Giá trị được truy xuất từ Firestore.runTransaction(). Đánh dấu thao tác sẽ được dùng trong một giao dịch.

Ví dụ

const Firestore = require('Firestore');

return Firestore.read('collection/document', {
  projectId: 'gcp-cloud-project-id',
}).then((result) => result.data.key, () => undefined);

Firestore.write

Hàm Firestore.write ghi dữ liệu vào một tài liệu hoặc tập hợp Firestore. Nếu đường dẫn đưa đến một bộ sưu tập, thì một tài liệu sẽ được tạo bằng mã nhận dạng được tạo ngẫu nhiên. Nếu đường dẫn dẫn đến một tài liệu và tài liệu đó không tồn tại, thì tài liệu đó sẽ được tạo. API này trả về một lời hứa phân giải thành mã nhận dạng của tài liệu đã thêm hoặc sửa đổi. Nếu bạn sử dụng lựa chọn giao dịch, API vẫn trả về một lời hứa, nhưng sẽ không chứa mã nhận dạng vì các thao tác ghi được thực hiện theo lô.

Cú pháp

Firestore.write(path, input[, options]);

Tham số

Tham số Loại Mô tả
path string Đường dẫn đến tài liệu hoặc bộ sưu tập. Không được bắt đầu hoặc kết thúc bằng dấu "/".
input object Giá trị cần ghi vào tài liệu. Nếu bạn đặt lựa chọn hợp nhất, API sẽ hợp nhất các khoá từ dữ liệu đầu vào vào tài liệu.
options object Không bắt buộc đối với các lựa chọn yêu cầu. Các lựa chọn được hỗ trợ là: projectId, merge và transaction. Hệ thống sẽ bỏ qua các khoá tuỳ chọn không xác định. (Xem phần Lựa chọn bên dưới.)

Lựa chọn

Tham số Loại Mô tả
projectId string Không bắt buộc. Mã dự án trên Google Cloud Platform. Nếu bạn bỏ qua, projectId sẽ được truy xuất từ biến môi trường GOOGLE_CLOUD_PROJECT miễn là bạn đặt chế độ cài đặt quyền access_firestore cho mã dự án thành * hoặc GOOGLE_CLOUD_PROJECT. Nếu vùng chứa máy chủ đang chạy trên Google Cloud, thì GOOGLE_CLOUD_PROJECT sẽ được đặt thành mã dự án của Google Cloud.
merge boolean Không bắt buộc. Nếu được đặt thành true, thì hợp nhất các khoá từ dữ liệu đầu vào vào tài liệu, nếu không, phương thức này sẽ ghi đè toàn bộ tài liệu. Giá trị mặc định là false.
transaction string Không bắt buộc. Giá trị được truy xuất từ Firestore.runTransaction(). Đánh dấu thao tác sẽ được dùng trong một giao dịch.

Ví dụ

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

Hàm Firestore.query truy vấn tập hợp đã cho và trả về một lời hứa phân giải thành một mảng gồm các tài liệu Firestore khớp với các điều kiện truy vấn. Đối tượng tài liệu Firestore giống như đối tượng được liệt kê ở trên trong Firestore.read. Nếu không có tài liệu nào khớp với các điều kiện truy vấn, thì lời hứa được trả về sẽ phân giải thành một mảng trống.

Cú pháp

Firestore.query(collection, queryConditions[, options]);

Tham số

Tham số Loại Mô tả
collection string Đường dẫn đến bộ sưu tập. Không được bắt đầu hoặc kết thúc bằng dấu "/".
queryConditions Mảng Một mảng các điều kiện truy vấn. Mỗi truy vấn đều có dạng một mảng gồm 3 giá trị: key, operator và expectedValue. Ví dụ: [[‘id’, ‘<’, ‘5’], [‘state’, ‘==’, ‘CA’]].

Các điều kiện được kết hợp với nhau bằng toán tử AND để tạo kết quả truy vấn. Vui lòng tham khảo các toán tử truy vấn của Firestore để xem danh sách các toán tử truy vấn tương thích.
options object Không bắt buộc đối với các lựa chọn yêu cầu. Các lựa chọn được hỗ trợ là: projectId, disableCache, limit và transaction. Các khoá tuỳ chọn không xác định sẽ bị bỏ qua. (Xem phần Lựa chọn bên dưới.)

Lựa chọn

Tham số Loại Mô tả
projectId string Không bắt buộc. Mã dự án trên Google Cloud Platform. Nếu bạn bỏ qua, projectId sẽ được truy xuất từ biến môi trường GOOGLE_CLOUD_PROJECT miễn là bạn đặt chế độ cài đặt quyền access_firestore cho mã dự án thành * hoặc GOOGLE_CLOUD_PROJECT. Nếu vùng chứa máy chủ đang chạy trên Google Cloud, thì GOOGLE_CLOUD_PROJECT sẽ được đặt thành mã dự án của Google Cloud.
disableCache boolean Không bắt buộc. Xác định xem có tắt bộ nhớ đệm hay không. Bộ nhớ đệm được bật theo mặc định, bộ nhớ này sẽ lưu kết quả vào bộ nhớ đệm trong thời gian của yêu cầu.
limit number Không bắt buộc. Thay đổi số lượng kết quả tối đa mà truy vấn trả về, mặc định là 5.
transaction string Không bắt buộc. Giá trị được truy xuất từ Firestore.runTransaction(). Đánh dấu thao tác sẽ được dùng trong một giao dịch.

Ví dụ

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

Hàm Firestore.runTransaction cho phép người dùng đọc và ghi dữ liệu từ Firestore một cách nguyên tử. Nếu xảy ra xung đột ghi đồng thời hoặc xung đột giao dịch khác, giao dịch sẽ được thử lại tối đa 2 lần. Nếu không thành công sau tổng cộng 3 lần thử, API sẽ từ chối và trả về lỗi. API này trả về một lời hứa phân giải thành một mảng gồm các mã nhận dạng tài liệu, cho mỗi thao tác ghi, nếu giao dịch thành công và sẽ từ chối kèm theo lỗi nếu giao dịch không thành công.

Cú pháp

Firestore.runTransaction(callback[, options]);

Tham số

Tham số Loại Mô tả
callback hàm Một lệnh gọi lại được gọi bằng mã giao dịch chuỗi. Bạn có thể truyền mã giao dịch vào các lệnh gọi API đọc/ghi/truy vấn. Hàm gọi lại này phải trả về một promise. Lệnh gọi lại có thể chạy tối đa 3 lần trước khi không thành công.
options object Không bắt buộc đối với các lựa chọn yêu cầu. Lựa chọn duy nhất được hỗ trợ là projectId. Hệ thống sẽ bỏ qua các khoá tuỳ chọn không xác định. (Xem phần Lựa chọn bên dưới.)

Lựa chọn

Tham số Loại Mô tả
projectId string Không bắt buộc. Mã dự án trên Google Cloud Platform. Nếu bạn bỏ qua, projectId sẽ được truy xuất từ biến môi trường GOOGLE_CLOUD_PROJECT miễn là bạn đặt chế độ cài đặt quyền access_firestore cho mã dự án thành * hoặc GOOGLE_CLOUD_PROJECT. Nếu vùng chứa máy chủ đang chạy trên Google Cloud, thì GOOGLE_CLOUD_PROJECT sẽ được đặt thành mã dự án của Google Cloud.

Ví dụ

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

Ví dụ về lỗi

Các lỗi có trong mỗi hàm Firestore sẽ bị từ chối bằng một đối tượng chứa khoá reason:

Firestore.read(...).then(onSuccess, (error) => {
  if (error.reason === 'unknown') {
    // Handle the unknown error here.
  }
});

Lý do gây ra lỗi có thể bao gồm nhưng không giới hạn ở Mã lỗi của REST API Firestore.

Các quyền liên quan

access_firestore

JSON

Trả về một đối tượng cung cấp các hàm JSON.

Hàm parse() phân tích cú pháp một chuỗi JSON để tạo giá trị hoặc đối tượng được mô tả bằng chuỗi đó. Nếu không phân tích cú pháp được giá trị (ví dụ: JSON bị lỗi), hàm sẽ trả về undefined. Nếu giá trị đầu vào không phải là một chuỗi, thì đầu vào sẽ được chuyển đổi thành một chuỗi.

Hàm stringify() chuyển đổi dữ liệu đầu vào thành một chuỗi JSON. Nếu không phân tích cú pháp được giá trị (ví dụ: đối tượng có một chu kỳ), phương thức sẽ trả về undefined.

Ví dụ

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

Cú pháp

JSON.parse(stringInput);
JSON.stringify(value);

Các quyền liên quan

Không có.

Math

Một đối tượng cung cấp các hàm Math.

Cú pháp

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

Tham số

Các tham số của hàm toán học được chuyển đổi thành số.

Các quyền liên quan

Không có.

Messages

Các API sau đây hoạt động cùng nhau để cho phép truyền thông báo giữa các phần khác nhau của một vùng chứa.

addMessageListener

Thêm một hàm để theo dõi thông báo thuộc một loại cụ thể. Khi một thông báo thuộc loại đó được gửi bằng API sendMessage (thường là bằng một thẻ), lệnh gọi lại sẽ chạy đồng bộ. Lệnh gọi lại được chạy với 2 tham số:

  1. messageType:string
  2. message:Object

Nếu lệnh gọi lại được thêm vào một ứng dụng, thì lệnh gọi lại sẽ nhận được thông báo trên tất cả các sự kiện mà ứng dụng đó tạo. Nếu lệnh gọi lại chỉ nhận thông báo từ một sự kiện nhất định, hãy liên kết API này với sự kiện đó bằng cách sử dụng bindToEvent trong hàm onStart của API runContainer. Hãy xem ví dụ.

Cú pháp

const addMessageListener = require('addMessageListener');

addMessageListener('send_pixel', (messageType, message) => {
  // This will be run whenever something sends a 'send_pixel' message.
});

Tham số

Tham số Loại Mô tả
messageType string Loại thông báo cần lắng nghe. Nếu giá trị không phải là một chuỗi, thì giá trị đó sẽ được chuyển đổi thành một chuỗi.
callback hàm Lệnh gọi lại sẽ chạy khi một thông báo thuộc loại thông báo có thể áp dụng được gửi. Nếu lệnh gọi lại không phải là một hàm, API sẽ không làm gì cả.

Ví dụ

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

Các quyền liên quan

Cần có quyền use_message. Bạn phải định cấu hình quyền để cho phép ít nhất:

  • Một loại thông báo có Usage là listen hoặc listen_and_send.

hasMessageListener

Trả về true nếu bạn đã thêm một trình nghe thông báo cho loại thông báo đã cho. Nếu không, hàm này sẽ trả về giá trị false.

Cú pháp

const hasMessageListener = require('hasMessageListener');

hasMessageListener('send_pixel');

Các quyền liên quan

Không có.

sendMessage

Gửi một thông báo thuộc loại đã chỉ định đến một trình nghe đã đăng ký. Bạn có thể dùng phương thức này để gửi thông báo từ thẻ trở lại máy khách đã chạy vùng chứa.

Cú pháp

const sendMessage = require('sendMessage');

sendMessage('send_pixel', {url: 'https://analytics.example.com/collect'});

Tham số

Tham số Loại Mô tả
messageType string Loại tin nhắn cần gửi. Nếu giá trị không phải là một chuỗi, thì giá trị đó sẽ được chuyển đổi thành một chuỗi.
message object Tin nhắn cần gửi. Nếu thông báo không phải là một đối tượng, thì API sẽ không làm gì cả.

Các quyền liên quan

Cần có quyền use_message. Bạn phải định cấu hình quyền để cho phép ít nhất:

  • Một loại thông báo có Usage là listen_and_send hoặc send.

Object

Trả về một đối tượng cung cấp các phương thức Object.

Phương thức keys() cung cấp hành vi Object.keys() của Thư viện chuẩn. Hàm này trả về một mảng gồm các tên thuộc tính có thể liệt kê của một đối tượng nhất định theo cùng thứ tự mà vòng lặp for...in... sẽ trả về. Nếu giá trị đầu vào không phải là một đối tượng, thì giá trị đó sẽ bị ép buộc thành một đối tượng.

Phương thức values() cung cấp hành vi Object.values() của Thư viện chuẩn. Hàm này trả về một mảng gồm các giá trị thuộc tính có thể liệt kê của một đối tượng nhất định theo cùng thứ tự mà vòng lặp for...in... sẽ trả về. Nếu giá trị đầu vào không phải là một đối tượng, thì giá trị đó sẽ bị ép buộc thành một đối tượng.

Phương thức entries() cung cấp hành vi Object.entries() của Thư viện chuẩn. Hàm này trả về một mảng gồm các cặp thuộc tính có thể liệt kê của một đối tượng nhất định theo cùng thứ tự mà vòng lặp for...in... sẽ trả về.[key, value] Nếu giá trị đầu vào không phải là một đối tượng, thì giá trị đó sẽ bị ép buộc thành một đối tượng.

Phương thức freeze() cung cấp hành vi Object.freeze() của Thư viện chuẩn. Bạn không thể thay đổi một đối tượng cố định nữa; việc cố định một đối tượng sẽ ngăn các thuộc tính mới được thêm vào đối tượng đó, các thuộc tính hiện có bị xoá và các giá trị của các thuộc tính hiện có bị thay đổi. freeze() trả về cùng một đối tượng đã được truyền vào. Đối số nguyên thuỷ hoặc đối số rỗng sẽ được coi như thể đó là một đối tượng cố định và sẽ được trả về.

Phương thức delete() cung cấp hành vi toán tử xoá Thư viện chuẩn. Thao tác này sẽ xoá khoá đã cho khỏi đối tượng, trừ phi đối tượng đó bị đóng băng. Giống như toán tử xoá Thư viện chuẩn, toán tử này trả về true nếu giá trị đầu vào đầu tiên (objectInput) là một đối tượng không bị đóng băng ngay cả khi giá trị đầu vào thứ hai (keyToDelete) chỉ định một khoá không tồn tại. Hàm này trả về false trong tất cả các trường hợp khác. Tuy nhiên, toán tử này khác với toán tử xoá Thư viện chuẩn ở những điểm sau:

  • keyToDelete không thể là một chuỗi phân cách bằng dấu chấm chỉ định một khoá lồng nhau.
  • Bạn không thể dùng delete() để xoá các phần tử khỏi một mảng.
  • Bạn không thể dùng delete() để xoá bất kỳ thuộc tính nào khỏi phạm vi chung.

Cú pháp

Object.keys(objectInput)
Object.values(objectInput)
Object.entries(objectInput)
Object.freeze(objectInput)
Object.delete(objectInput, keyToDelete)

Tham số

Object.keys

Tham số Loại Mô tả
objectInput any Đối tượng có các khoá cần liệt kê. Nếu đầu vào không phải là một đối tượng, thì đầu vào đó sẽ được chuyển đổi thành một đối tượng.

Object.values

Tham số Loại Mô tả
objectInput any Đối tượng có các giá trị cần liệt kê. Nếu đầu vào không phải là một đối tượng, thì đầu vào đó sẽ được chuyển đổi thành một đối tượng.

Object.entries

Tham số Loại Mô tả
objectInput any Đối tượng có các cặp khoá/giá trị cần liệt kê. Nếu đầu vào không phải là một đối tượng, thì đầu vào đó sẽ được chuyển đổi thành một đối tượng.

Object.freeze

Tham số Loại Mô tả
objectInput any Đối tượng cần cố định. Nếu đầu vào không phải là một đối tượng, thì đầu vào đó sẽ được coi là một đối tượng cố định.

Object.delete

Tham số Loại Mô tả
objectInput any Đối tượng có khoá cần xoá.
keyToDelete string Khoá cấp cao nhất cần xoá.

Ví dụ

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

Trả về một đối tượng cung cấp các phương thức để tương tác với các promise.

Các đối tượng Promise có chức năng tương đương với các đối tượng Promise trong JavaScript. Mỗi phiên bản có 3 phương thức trả về một Promise, cho phép thực hiện thêm hành động khi một promise được giải quyết:

  • .then() – Xử lý cả trường hợp đã giải quyết và bị từ chối. Hàm này lấy hai lệnh gọi lại làm tham số: một cho trường hợp thành công và một cho trường hợp thất bại.
  • .catch() – Chỉ xử lý các trường hợp bị từ chối. Lấy một lệnh gọi lại làm tham số.
  • .finally() – Cung cấp một cách để chạy mã cho dù lời hứa đã được giải quyết hay bị từ chối. Lấy một lệnh gọi lại làm tham số được gọi mà không có đối số.

Một biến trả về một promise bằng giá trị đã phân giải của promise đó hoặc false nếu promise đó từ chối.

Ví dụ

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

Trả về một lời hứa có thể:

  • giải quyết khi tất cả các đầu vào đã được giải quyết, hoặc
  • từ chối khi bất kỳ dữ liệu đầu vào nào từ chối

Cú pháp

Promise.all(inputs);

Tham số

Tham số Loại Mô tả
inputs Mảng Một mảng các giá trị hoặc promise. Nếu một đầu vào không phải là một lời hứa, thì đầu vào đó sẽ được truyền qua như thể đó là giá trị đã phân giải của một lời hứa. Báo lỗi nếu đầu vào không phải là một mảng.

Ví dụ

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: ''}]
  });

Các quyền liên quan

Không có.

Promise.create

Tạo một lời hứa có chức năng tương đương với lời hứa JavaScript.

Cú pháp

Promise.create(resolver);

Tham số

Tham số Loại Mô tả
resolver hàm Một hàm được gọi bằng hai hàm: resolve và reject. Lời hứa được trả về sẽ phân giải hoặc từ chối khi tham số tương ứng được gọi. Trả về lỗi nếu trình phân giải không phải là một hàm.

Ví dụ

const Promise = require('Promise');

return Promise.create((resolve, reject) => {
  // Do asynchronous work that eventually calls resolve() or reject()
});

Các quyền liên quan

Không có.

API kiểm thử

Các API này hoạt động với các thử nghiệm JavaScript trong hộp cát để tạo các thử nghiệm cho mẫu tuỳ chỉnh trong Trình quản lý thẻ của Google. Các API kiểm thử này không cần câu lệnh require(). [Tìm hiểu thêm về kiểm thử mẫu tuỳ chỉnh].

assertApi

Trả về một đối tượng so khớp có thể dùng để đưa ra các khẳng định một cách trôi chảy về API đã cho.

Cú pháp

assertApi(apiName)

Tham số

Tham số Loại Mô tả
apiName string Tên của API cần kiểm tra; chuỗi giống như chuỗi được truyền đến require().

Matchers

  • Subject.wasCalled()
  • Subject.wasNotCalled()
  • Subject.wasCalledWith(...expected)
  • Subject.wasNotCalledWith(...expected)

Ví dụ

assertApi('sendPixel').wasCalled();
assertApi('getUrl').wasNotCalled();
assertApi('makeNumber').wasCalledWith('8');
assertApi('setInWindow').wasNotCalledWith('myVar', 'theWrongValue');

assertThat

API assertThat được mô hình hoá theo thư viện [Truth] của Google. Hàm này trả về một đối tượng có thể dùng để đưa ra các câu lệnh một cách trôi chảy về giá trị của một đối tượng. Lỗi xác nhận sẽ ngay lập tức dừng kiểm thử và đánh dấu là không thành công. Tuy nhiên, lỗi trong một kiểm thử sẽ không ảnh hưởng đến các trường hợp kiểm thử khác.

Cú pháp

assertThat(actual, opt_message)

Tham số

Tham số Loại Mô tả
actual any Giá trị cần dùng trong các quy trình kiểm tra linh hoạt.
opt_message string Thông báo không bắt buộc để in nếu câu khẳng định không thành công.

Matchers

Trình so khớp Mô tả
isUndefined() Xác nhận rằng chủ đề là undefined.
isDefined() Xác nhận rằng đối tượng không phải là undefined.
isNull() Xác nhận rằng chủ đề là null.
isNotNull() Xác nhận rằng đối tượng không phải là null.
isFalse() Xác nhận rằng chủ đề là false.
isTrue() Xác nhận rằng chủ đề là true.
isFalsy() Xác nhận rằng chủ đề là sai. Các giá trị sai là undefined, null, false, NaN, 0 và "" (chuỗi trống).
isTruthy() Xác nhận rằng chủ đề là đúng. Các giá trị sai là undefined, null, false, NaN, 0 và "" (chuỗi trống).
isNaN() Xác nhận rằng đối tượng là giá trị NaN.
isNotNaN() Xác nhận rằng đối tượng là bất kỳ giá trị nào ngoài NaN.
isInfinity() Xác nhận rằng đối tượng là vô cực dương hoặc vô cực âm.
isNotInfinity() Xác nhận rằng đối tượng là bất kỳ giá trị nào ngoài vô cực dương hoặc âm.
isEqualTo(expected) Xác nhận rằng đối tượng bằng với giá trị đã cho. Đây là một phép so sánh giá trị chứ không phải phép so sánh tham chiếu. Nội dung của các đối tượng và mảng được so sánh một cách đệ quy.
isNotEqualTo(expected) Xác nhận rằng đối tượng không bằng giá trị đã cho. Đây là một phép so sánh giá trị chứ không phải phép so sánh tham chiếu. Nội dung của các đối tượng và mảng được so sánh một cách đệ quy.
isAnyOf(...expected) Xác nhận rằng đối tượng bằng một trong các giá trị đã cho. Đây là một phép so sánh giá trị chứ không phải phép so sánh tham chiếu. Nội dung của các đối tượng và mảng được so sánh một cách đệ quy.
isNoneOf(...expected) Xác nhận rằng đối tượng không bằng bất kỳ giá trị nào đã cho. Đây là một phép so sánh giá trị chứ không phải phép so sánh tham chiếu. Nội dung của các đối tượng và mảng được so sánh một cách đệ quy.
isStrictlyEqualTo(expected) Xác nhận rằng đối tượng hoàn toàn bằng (===) giá trị đã cho.
isNotStrictlyEqualTo(expected) Xác nhận rằng đối tượng không hoàn toàn bằng (!==) giá trị đã cho.
isGreaterThan(expected) Xác nhận rằng đối tượng lớn hơn (>) giá trị đã cho trong một phép so sánh có thứ tự.
isGreaterThanOrEqualTo(expected) Xác nhận rằng đối tượng lớn hơn hoặc bằng (>=) giá trị đã cho trong một phép so sánh có thứ tự.
isLessThan(expected) Xác nhận rằng đối tượng nhỏ hơn (<) giá trị đã cho trong một phép so sánh có thứ tự.
isLessThanOrEqualTo(expected) Xác nhận rằng đối tượng nhỏ hơn hoặc bằng (<=) giá trị đã cho trong một phép so sánh có thứ tự.
contains(...expected) Khẳng định rằng đối tượng là một mảng hoặc chuỗi chứa tất cả các giá trị đã cho theo bất kỳ thứ tự nào. Đây là một phép so sánh giá trị, không phải phép so sánh tham chiếu. Nội dung của các đối tượng và mảng được so sánh một cách đệ quy.
doesNotContain(...expected) Xác nhận rằng đối tượng là một mảng hoặc chuỗi không chứa giá trị nào trong số các giá trị đã cho. Đây là so sánh giá trị chứ không phải so sánh tham chiếu. Nội dung của các đối tượng và mảng được so sánh một cách đệ quy.
containsExactly(...expected) Xác nhận rằng đối tượng là một mảng chứa tất cả các giá trị đã cho theo bất kỳ thứ tự nào và không có giá trị nào khác. Đây là một phép so sánh giá trị chứ không phải phép so sánh tham chiếu. Nội dung của các đối tượng và mảng được so sánh một cách đệ quy.
doesNotContainExactly(...expected) Xác nhận rằng đối tượng là một mảng chứa một tập hợp các giá trị khác với các giá trị đã cho theo bất kỳ thứ tự nào. Đây là một phép so sánh giá trị chứ không phải phép so sánh tham chiếu. Nội dung của các đối tượng và mảng được so sánh một cách đệ quy.
hasLength(expected) Xác nhận rằng đối tượng là một mảng hoặc chuỗi có độ dài nhất định. Câu khẳng định luôn thất bại nếu giá trị không phải là một mảng hoặc chuỗi.
isEmpty() Xác nhận rằng đối tượng là một mảng hoặc chuỗi trống (độ dài = 0). Câu khẳng định luôn thất bại nếu giá trị không phải là một mảng hoặc chuỗi.
isNotEmpty() Xác nhận rằng đối tượng là một mảng hoặc chuỗi không trống (độ dài > 0). Câu khẳng định luôn thất bại nếu giá trị không phải là một mảng hoặc chuỗi.
isArray() Xác nhận rằng loại của đối tượng là một mảng.
isBoolean() Xác nhận rằng loại chủ đề là boolean.
isFunction() Xác nhận rằng kiểu của đối tượng là một hàm.
isNumber() Xác nhận rằng loại của chủ đề là một số.
isObject() Xác nhận rằng loại của đối tượng là một đối tượng.
isString() Xác nhận rằng loại chủ đề là một chuỗi.

Ví dụ

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

Ngay lập tức khiến bài kiểm thử hiện tại không thành công và in thông báo đã cho (nếu có).

Cú pháp

fail(opt_message);

Tham số

Tham số Loại Mô tả
opt_message string Văn bản thông báo lỗi không bắt buộc.

Ví dụ

fail('This test has failed.');

mock

API mock cho phép bạn ghi đè hành vi của các API trong hộp cát. Bạn có thể sử dụng API mô phỏng trong mã mẫu, nhưng API này chỉ hoạt động ở chế độ thử nghiệm. Các đối tượng mô phỏng sẽ được đặt lại trước khi mỗi lượt kiểm thử được chạy.

Cú pháp

mock(apiName, returnValue);

Tham số

Tham số Loại Mô tả
apiName string Tên của API cần mô phỏng; cùng một chuỗi như được truyền đến require()
returnValue any Giá trị cần trả về cho API hoặc một hàm được gọi thay cho API. Nếu returnValue là một hàm, thì hàm đó sẽ được gọi thay cho Sandboxed API; nếu returnValue không phải là một hàm, thì giá trị đó sẽ được trả về thay cho Sandboxed API.

Ví dụ

mock('encodeUri', "https://endpoint.example.com/?account=12345");
mock('sendPixel', function(url, onSuccess, onFailure) {
    onSuccess();
});

mockObject

API mockObject cho phép bạn ghi đè hành vi của các API trong hộp cát trả về một đối tượng. Bạn có thể sử dụng API này trong mã mẫu, nhưng API này chỉ hoạt động ở chế độ kiểm thử. Các đối tượng mô phỏng sẽ được đặt lại trước khi mỗi lượt kiểm thử được chạy.

Cú pháp

mockObject(apiName, objectMock);

Tham số

Tham số Loại Mô tả
apiName string Tên của API cần mô phỏng; cùng một chuỗi như được truyền đến require()
objectMock object Giá trị cần trả về cho API hoặc một hàm được gọi thay cho API. Phải là một đối tượng.

Ví dụ

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

Chạy mã cho mẫu, tức là nội dung của thẻ Code (Mã), trong môi trường kiểm thử hiện tại với một đối tượng dữ liệu đầu vào nhất định.

Cú pháp

runCode(data)

Tham số

Tham số Loại Mô tả
data object Đối tượng dữ liệu sẽ được dùng trong kiểm thử.

Giá trị trả về

Trả về giá trị của một biến cho các mẫu biến; trả về undefined cho tất cả các loại mẫu khác.

Ví dụ

runCode({field1: 123, field2: 'value'});