API การติดแท็กฝั่งเซิร์ฟเวอร์

เอกสารนี้ระบุ API สําหรับการติดแท็กฝั่งเซิร์ฟเวอร์

addEventCallback

ลงทะเบียนฟังก์ชัน Callback ที่จะเรียกใช้เมื่อสิ้นสุดเหตุการณ์ ระบบจะเรียกใช้ callback เมื่อแท็กทั้งหมดสําหรับเหตุการณ์ทํางานแล้ว ระบบจะส่งค่า 2 ค่าไปยังการเรียกคืน ได้แก่ รหัสของคอนเทนเนอร์ที่เรียกใช้ฟังก์ชัน และออบเจ็กต์ที่มีข้อมูลเกี่ยวกับเหตุการณ์

เมื่อใช้ API นี้ในแท็ก ระบบจะเชื่อมโยงกับเหตุการณ์ปัจจุบัน เมื่อใช้ API นี้ในไคลเอ็นต์ จะต้องเชื่อมโยงกับเหตุการณ์ที่เฉพาะเจาะจงโดยใช้ฟังก์ชัน bindToEvent ของ runContainer API ดูรายละเอียดเพิ่มเติมได้ในตัวอย่าง

ไวยากรณ์

const addEventCallback = require('addEventCallback');

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

พารามิเตอร์

พารามิเตอร์ ประเภท คำอธิบาย
callback function ฟังก์ชันที่จะเรียกใช้เมื่อสิ้นสุดเหตุการณ์

ออบเจ็กต์ eventData มีข้อมูลต่อไปนี้

ชื่อคีย์ ประเภท คำอธิบาย
tags อาร์เรย์ อาร์เรย์ของออบเจ็กต์ข้อมูลแท็ก แท็กทุกรายการที่เริ่มทํางานระหว่างเหตุการณ์จะมีรายการในอาร์เรย์นี้ ออบเจ็กต์ข้อมูลแท็กประกอบด้วยรหัสของแท็ก (id) สถานะการเรียกใช้ (status) และเวลาเรียกใช้ (executionTime) นอกจากนี้ ข้อมูลแท็กจะมีข้อมูลเมตาแท็กเพิ่มเติมที่กำหนดค่าไว้ในแท็กด้วย

ตัวอย่าง

ในไคลเอ็นต์

const addEventCallback = require('addEventCallback');
const claimRequest = require('claimRequest');
const extractEventsFromMpv1 = require('extractEventsFromMpv1');
const logToConsole = require('logToConsole');
const returnResponse = require('returnResponse');
const runContainer = require('runContainer');

claimRequest();

const events = extractEventsFromMpv1();
let eventsCompleted = 0;
events.forEach((evt, i) => {
  runContainer(evt, /* onComplete= */ (bindToEvent) => {
    bindToEvent(addEventCallback)((containerId, eventData) => {
      logToConsole('Event Number: ' + i);
      eventData.tags.forEach((tag) => {
        logToConsole('Tag ID: ' + tag.id);
        logToConsole('Tag Status: ' + tag.status);
        logToConsole('Tag Execution Time: ' + tag.executionTime);
      });
    });
    if (events.length === ++eventsCompleted) {
      returnResponse();
    }
  });
});

ในแท็ก

const addEventCallback = require('addEventCallback');

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

สิทธิ์ที่เชื่อมโยง

read_event_metadata

callLater

กําหนดเวลาการเรียกใช้ฟังก์ชันให้เกิดขึ้นแบบไม่พร้อมกัน ระบบจะเรียกใช้ฟังก์ชันนี้หลังจากที่โค้ดปัจจุบันแสดงผล ซึ่งเทียบเท่ากับ setTimeout(<function>, 0)

ตัวอย่าง

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

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

ไวยากรณ์

callLater(function)

พารามิเตอร์

พารามิเตอร์ ประเภท คำอธิบาย
function function ฟังก์ชันที่จะเรียกใช้

สิทธิ์ที่เชื่อมโยง

ไม่มี

claimRequest

ใช้ API นี้ในไคลเอ็นต์เพื่ออ้างสิทธิ์ในคำขอ เมื่ออ้างสิทธิ์ในคำขอแล้ว คอนเทนเนอร์จะไม่เรียกใช้ไคลเอ็นต์เพิ่มเติม

API นี้จะแสดงข้อยกเว้นหากเรียกใช้ในแท็กหรือตัวแปร API นี้จะแสดงข้อยกเว้นหากเรียกใช้หลังจากที่ไคลเอ็นต์แสดงผลแล้ว (เช่น หากเรียกใช้ใน Callback แบบแอ็กซิงโครน เช่น ใน callLater หรือฟังก์ชัน runContainer onComplete)

ไคลเอ็นต์ควรอ้างสิทธิ์คำขอโดยใช้ API นี้ก่อนที่จะเรียกใช้ runContainer API

ตัวอย่าง

const claimRequest = require('claimRequest');

claimRequest();

ไวยากรณ์

claimRequest();

สิทธิ์ที่เชื่อมโยง

ไม่มี

computeEffectiveTldPlusOne

แสดงผลโดเมนระดับบนสุด + 1 (eTLD+1) ที่มีประสิทธิภาพของโดเมนหรือ URL ที่ระบุ ระบบจะคํานวณ eTLD+1 โดยประเมินโดเมนเทียบกับกฎในรายการคําต่อท้ายสาธารณะ โดยปกติแล้ว eTLD+1 คือโดเมนระดับสูงสุดที่คุณตั้งค่าคุกกี้ได้

หากอาร์กิวเมนต์เป็น Null หรือไม่มีการกำหนด ค่าอาร์กิวเมนต์จะแสดงผลโดยไม่มีการแก้ไข มิเช่นนั้น ระบบจะบังคับให้อาร์กิวเมนต์เป็นสตริง หากอาร์กิวเมนต์ไม่ใช่โดเมนหรือ URL ที่ถูกต้อง ระบบจะแสดงผลสตริงว่าง หากเซิร์ฟเวอร์ดึงข้อมูลรายการนามสกุลสาธารณะไม่ได้ ระบบจะแสดงผลค่าอาร์กิวเมนต์โดยไม่มีการแก้ไข

ตัวอย่าง

const computeEffectiveTldPlusOne = require('computeEffectiveTldPlusOne');

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

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

ไวยากรณ์

computeEffectiveTldPlusOne(domainOrUrl);

พารามิเตอร์

พารามิเตอร์ ประเภท คำอธิบาย
domainOrUrl สตริง โดเมนหรือ URL ที่จะคํานวณ eTLD+1

สิทธิ์ที่เชื่อมโยง

ไม่มี

createRegex

สร้างอินสแตนซ์นิพจน์ทั่วไปใหม่และแสดงผลโดยรวมไว้ในออบเจ็กต์ คุณไม่สามารถเข้าถึงนิพจน์ทั่วไปโดยตรง แต่คุณสามารถส่งค่านี้ไปยัง testRegex API, String.replace(), String.match() และ String.search() ได้

แสดงผล null หากนิพจน์ทั่วไปไม่ถูกต้องหรือ Re2 ไม่พร้อมใช้งานบนเซิร์ฟเวอร์

API นี้ใช้การใช้งาน Re2 รูปภาพ Docker ของเซิร์ฟเวอร์ต้องเป็นเวอร์ชัน 2.0.0 ขึ้นไป

ตัวอย่าง

const createRegex = require('createRegex');

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

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

ไวยากรณ์

createRegex(pattern, flags);

พารามิเตอร์

พารามิเตอร์ ประเภท คำอธิบาย
pattern สตริง ข้อความของนิพจน์ทั่วไป
flags สตริง สตริงที่ไม่บังคับซึ่งมี Flag สําหรับนิพจน์ทั่วไปที่สร้าง ระบบรองรับ `g` (ส่วนกลาง) และ `i` (ไม่คำนึงถึงตัวพิมพ์ใหญ่/เล็ก) ระบบจะไม่สนใจอักขระอื่นๆ ทั้งหมด

สิทธิ์ที่เชื่อมโยง

ไม่มี

เวอร์ชันรูปภาพขั้นต่ำ

2.0.0

decodeUri

ถอดรหัสอักขระที่เข้ารหัสใน URI ที่ระบุ แสดงผลสตริงที่แสดง URI ที่ถอดรหัสแล้ว แสดงผล undefined เมื่อป้อนข้อมูลที่ไม่ถูกต้อง

ตัวอย่าง

const decodeUri = require('decodeUri');

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

ไวยากรณ์

decodeUri(encoded_uri);

พารามิเตอร์

พารามิเตอร์ ประเภท คำอธิบาย
encoded_uri สตริง URI ที่เข้ารหัสโดย encodeUri() หรือวิธีอื่นๆ

สิทธิ์ที่เชื่อมโยง

ไม่มี

decodeUriComponent

ถอดรหัสอักขระที่เข้ารหัสในคอมโพเนนต์ URI ที่ระบุ แสดงผลสตริงที่แสดงถึงคอมโพเนนต์ URI ที่ถอดรหัสแล้ว แสดงผล undefined เมื่อได้รับอินพุตที่ไม่ถูกต้อง

ตัวอย่าง

const decodeUriComponent = require('decodeUriComponent');

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

ไวยากรณ์

decodeUriComponent(encoded_uri_component);

พารามิเตอร์

พารามิเตอร์ ประเภท คำอธิบาย
encoded_uri_component สตริง คอมโพเนนต์ URI ที่เข้ารหัสโดย encodeUriComponent() หรือด้วยวิธีอื่นๆ

สิทธิ์ที่เชื่อมโยง

ไม่มี

encodeUri

แสดงผล Uniform Resource Identifier (URI) ที่เข้ารหัสโดยการหลีกหนีอักขระพิเศษ ส่งคืนสตริงที่แสดงสตริงที่ระบุซึ่งเข้ารหัสเป็น URI

ตัวอย่าง

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

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

ไวยากรณ์

encodeUri(uri);

พารามิเตอร์

พารามิเตอร์ ประเภท คำอธิบาย
uri สตริง URI ที่สมบูรณ์

สิทธิ์ที่เชื่อมโยง

ไม่มี

encodeUriComponent

แสดงผล Uniform Resource Identifier (URI) ที่เข้ารหัสโดยการหลีกหนีอักขระพิเศษ แสดงผลสตริงที่แสดงสตริงที่ระบุซึ่งเข้ารหัสเป็น URI

ตัวอย่าง

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

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

ไวยากรณ์

encodeUriComponent(str);

พารามิเตอร์

พารามิเตอร์ ประเภท คำอธิบาย
str สตริง คอมโพเนนต์ของ URI

สิทธิ์ที่เชื่อมโยง

ไม่มี

extractEventsFromMpv1

แปลคําขอ Measurement Protocol V1 ที่เข้ามาเป็นรายการเหตุการณ์ในรูปแบบสคีมาแบบรวม แสดงรายการเหตุการณ์ที่ดึงข้อมูล แสดงข้อผิดพลาดหากคําขอมีรูปแบบไม่ถูกต้อง

ตัวอย่าง

const extractEventsFromMpv1 = require('extractEventsFromMpv1');
const isRequestMpv1 = require('isRequestMpv1');

if (isRequestMpv1()) {
  const events = extractEventsFromMpv1();
  for (let i = 0; i < events.length; ++i) {
    const event = events[i];
    // Process event.
  }
}

ไวยากรณ์

extractEventsFromMpv1();

สิทธิ์ที่เชื่อมโยง

ต้องมีสิทธิ์ read_request คุณต้องกำหนดค่าสิทธิ์ให้อนุญาตการเข้าถึงอย่างน้อยสิ่งต่อไปนี้

  • body
  • query parameters

extractEventsFromMpv2

แปลคําขอ Measurement Protocol V2 ที่เข้ามาเป็นรายการเหตุการณ์ในรูปแบบสคีมาแบบรวม แสดงรายการเหตุการณ์ที่ดึงข้อมูล แสดงข้อผิดพลาดหากคําขอมีรูปแบบไม่ถูกต้อง

ตัวอย่าง

const extractEventsFromMpv2 = require('extractEventsFromMpv2');
const isRequestMpv2 = require('isRequestMpv2');

if (isRequestMpv2()) {
  const events = extractEventsFromMpv2();
  for (let i = 0; i < events.length; ++i) {
    const event = events[i];
    // Process event.
  }
}

ไวยากรณ์

extractEventsFromMpv2();

สิทธิ์ที่เชื่อมโยง

ต้องมีสิทธิ์ read_request คุณต้องกำหนดค่าสิทธิ์ให้อนุญาตการเข้าถึงอย่างน้อยสิ่งต่อไปนี้

  • body
  • query parameters

fromBase64

ถอดรหัสสตริงที่เข้ารหัสฐาน 64 แสดงค่า undefined หากอินพุตไม่ถูกต้อง

ไวยากรณ์

fromBase64(base64EncodedString);

พารามิเตอร์

พารามิเตอร์ ประเภท คำอธิบาย
base64EncodedString สตริง สตริงที่เข้ารหัส Base64

ตัวอย่าง

const fromBase64 = require('fromBase64');

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

สิทธิ์ที่เชื่อมโยง

ไม่มี

generateRandom

แสดงผลตัวเลข (จำนวนเต็ม) แบบสุ่มภายในช่วงที่กำหนด

ตัวอย่าง

const generateRandom = require('generateRandom');

const randomValue = generateRandom(0, 10000000);

ไวยากรณ์

generateRandom(min, max);

พารามิเตอร์

พารามิเตอร์ ประเภท คำอธิบาย
min number ค่าที่เป็นไปได้ต่ำสุดของจำนวนเต็มที่แสดงผล (รวม)
max number ค่าสูงสุดที่เป็นไปได้ของจำนวนเต็มที่แสดงผล (รวม)

สิทธิ์ที่เชื่อมโยง

ไม่มี

getAllEventData

แสดงผลสําเนาของข้อมูลเหตุการณ์

ไวยากรณ์

getAllEventData();

สิทธิ์ที่เชื่อมโยง

read_event_data

getClientName

แสดงผลสตริงที่มีชื่อของไคลเอ็นต์ปัจจุบัน

ไวยากรณ์

getClientName();

สิทธิ์ที่เชื่อมโยง

read_container_data

getContainerVersion

แสดงผลออบเจ็กต์ที่มีข้อมูลเกี่ยวกับคอนเทนเนอร์ปัจจุบัน ออบเจ็กต์ที่แสดงผลจะมีฟิลด์ต่อไปนี้

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

ตัวอย่าง

const getContainerVersion = require('getContainerVersion');

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

ไวยากรณ์

getContainerVersion();

สิทธิ์ที่เชื่อมโยง

read_container_data

getCookieValues

แสดงผลอาร์เรย์ที่มีค่าของคุกกี้ทั้งหมดที่มีชื่อที่ระบุ

ตัวอย่าง

const getCookieValues = require('getCookieValues');

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

ไวยากรณ์

getCookieValues(name[, noDecode]);

พารามิเตอร์

พารามิเตอร์ ประเภท คำอธิบาย
name สตริง ชื่อของคุกกี้
noDecode บูลีน หากเป็น true ระบบจะไม่ถอดรหัสค่าคุกกี้ก่อนแสดงผล ค่าเริ่มต้นคือ false

สิทธิ์ที่เชื่อมโยง

get_cookies

getEventData

แสดงผลสําเนาของค่าในเส้นทางที่ระบุในข้อมูลเหตุการณ์ แสดงผล undefined หากไม่มีข้อมูลเหตุการณ์หรือไม่มีค่าในเส้นทางที่ระบุ

ตัวอย่าง

const getEventData = require('getEventData');

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

พารามิเตอร์

พารามิเตอร์ ประเภท คำอธิบาย
keyPath any เส้นทางของคีย์จะมีจุดคั่นระหว่างคอมโพเนนต์เส้นทาง ซึ่งอาจเป็นคีย์ในออบเจ็กต์หรือดัชนีในอาร์เรย์ก็ได้ หาก keyPath ไม่ใช่สตริง ระบบจะบังคับให้กลายเป็นสตริง

ไวยากรณ์

getEventData(keyPath);

สิทธิ์ที่เชื่อมโยง

read_event_data

getGoogleAuth

แสดงผลออบเจ็กต์การให้สิทธิ์ซึ่งเมื่อใช้กับ sendHttpGet หรือ sendHttpRequest จะมีส่วนหัวการให้สิทธิ์สําหรับ Google Cloud API API นี้ใช้ข้อมูลเข้าสู่ระบบเริ่มต้นของแอปพลิเคชันเพื่อค้นหาข้อมูลเข้าสู่ระบบจากสภาพแวดล้อมเซิร์ฟเวอร์โดยอัตโนมัติ

ตัวอย่าง

const getGoogleAuth = require('getGoogleAuth');
const logToConsole = require('logToConsole');
const sendHttpGet = require('sendHttpGet');

const auth = getGoogleAuth({
  scopes: ['https://www.googleapis.com/auth/datastore']
});

sendHttpGet(
  'https://firestore.googleapis.com/v1/projects/my-project/databases/(default)/documents/collection/document',
  {authorization: auth}
).then((result) => {
  if (result.statusCode >= 200 && result.statusCode < 300) {
    logToConsole('Result: ' + result.body);
    data.gtmOnSuccess();
  } else {
    data.gtmOnFailure();
  }
});

ไวยากรณ์

getGoogleAuth(scopes);

พารามิเตอร์

พารามิเตอร์ ประเภท คำอธิบาย
scopes อาร์เรย์ อาร์เรย์ของขอบเขต OAuth 2.0 ของ Google API เพื่อขอสิทธิ์เข้าถึง

สิทธิ์ที่เชื่อมโยง

ต้องมีสิทธิ์ use_google_credentials สิทธิ์ต้องได้รับการกำหนดค่าด้วยขอบเขตที่อนุญาตอย่างน้อย 1 รายการ

getGoogleScript

ดึงข้อมูลทรัพยากรจากชุดสคริปต์ Google ที่กำหนดไว้ล่วงหน้า และแสดงผลสัญญาที่มีสคริปต์และข้อมูลเมตาการแคชที่เกี่ยวข้อง

พรอมต์จะแสดงผลเป็นออบเจ็กต์ที่มีคีย์ 2 คีย์ ได้แก่ script และ metadata หากคำขอไม่สำเร็จ Promise จะปฏิเสธด้วยคีย์ reason

ออบเจ็กต์ metadata จะมีข้อมูลเมตาการแคชต่อไปนี้ตามส่วนหัวการตอบกลับของทรัพยากร โดยแต่ละช่องจะมีอยู่ก็ต่อเมื่อมีส่วนหัวที่เกี่ยวข้องในการตอบกลับของทรัพยากร

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

ตัวอย่าง

const getGoogleScript = require('getGoogleScript');

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

ไวยากรณ์

getGoogleScript(script[, options]);

พารามิเตอร์

พารามิเตอร์ ประเภท คำอธิบาย
script สตริง ชื่อสคริปต์ สคริปต์ที่รองรับ ได้แก่ 'ANALYTICS', 'GTAG' และ 'GTM'

ตัวเลือก 'ANALYTICS' จะดึงข้อมูลสคริปต์ Google Analytics จาก https://www.google-analytics.com/analytics.js

ตัวเลือก 'GTAG' จะดึงข้อมูลสคริปต์แท็กที่ติดทั่วเว็บไซต์ (gtag.js) จาก https://www.googletagmanager.com/gtag/js

ตัวเลือก 'GTM' จะดึงข้อมูลสคริปต์ Google Tag Manager จาก https://www.googletagmanager.com/gtm.js
options object ตัวเลือกคำขอที่ไม่บังคับ โปรดดูตัวเลือกที่รองรับด้านล่าง

ตัวเลือก

ตัวเลือก ประเภท คำอธิบาย
id สตริง ใช้ได้กับ 'GTAG' ที่มีรหัสการวัด gtag และ 'GTM' ที่มีรหัสคอนเทนเนอร์เว็บ (เช่น GTM-XXXX)
debug any หากเป็นจริง ระบบจะขอและแสดงผลสคริปต์การวัดเวอร์ชันแก้ไขข้อบกพร่อง
timeout number การหมดเวลาของคําขอเป็นมิลลิวินาที ระบบจะไม่สนใจค่าที่ไม่ใช่ค่าบวก หากคําขอหมดเวลา ระบบจะเรียกใช้การเรียกกลับด้วย undefined สําหรับค่าสคริปต์และ {} สําหรับออบเจ็กต์ข้อมูลเมตา

ระบบจะไม่สนใจคีย์ตัวเลือกที่ไม่รู้จัก

สิทธิ์ที่เชื่อมโยง

ต้องมีสิทธิ์ send_http สิทธิ์ต้องได้รับการกําหนดค่าให้อนุญาตการเข้าถึงอย่างน้อย

  • อนุญาต Google Domains

getRemoteAddress

แสดงผลสตริงของที่อยู่ IP ที่เป็นต้นทางของคําขอ เช่น 12.345.67.890 สําหรับ IPv4 หรือ 2001:0db8:85a3:0:0:8a2e:0370:7334 สําหรับ IPv6 โดยอ่านส่วนหัวของคําขอ เช่น Forwarded และ X-Forwarded-For หมายเหตุ: API นี้จะพยายามค้นหา IP ต้นทางอย่างสุดความสามารถ แต่ไม่สามารถรับประกันว่าผลลัพธ์จะถูกต้อง

ไวยากรณ์

getRemoteAddress();

สิทธิ์ที่เชื่อมโยง

ต้องมีสิทธิ์ read_request คุณต้องกำหนดค่าสิทธิ์ให้อนุญาตการเข้าถึงอย่างน้อยสิ่งต่อไปนี้

  • ส่วนหัว Forwarded และ X-Forwarded-For
  • ที่อยู่ IP ระยะไกล

getRequestBody

แสดงผลเนื้อหาคําขอเป็นสตริง หากมี หรือ undefined หากไม่มี

ไวยากรณ์

getRequestBody();

สิทธิ์ที่เชื่อมโยง

read_request

getRequestHeader

แสดงผลค่าของส่วนหัวคำขอที่มีชื่อเป็นสตริง หากมี หรือ undefined ในกรณีอื่นๆ หากส่วนหัวซ้ำกัน ระบบจะรวมค่าที่แสดงผลไว้ด้วยกันด้วย ', '

ตัวอย่าง

const getRequestHeader = require('getRequestHeader');

const host = getRequestHeader('host');

ไวยากรณ์

getRequestHeader(headerName);

พารามิเตอร์

พารามิเตอร์ ประเภท คำอธิบาย
headerName สตริง ชื่อส่วนหัว ค่านี้ไม่คำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่

สิทธิ์ที่เชื่อมโยง

read_request

getRequestMethod

แสดงผลวิธีการส่งคำขอ เช่น 'GET' หรือ 'POST' เป็นสตริง

ตัวอย่าง

const getRequestMethod = require('getRequestMethod');

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

ไวยากรณ์

getRequestMethod();

สิทธิ์ที่เชื่อมโยง

ไม่มี

getRequestPath

แสดงผลเส้นทางคำขอโดยไม่มีสตริงการค้นหา เช่น หาก URL คือ '/foo?id=123' ผลลัพธ์ที่ได้คือ '/foo' นำคำนำหน้า URL ของคอนเทนเนอร์เซิร์ฟเวอร์ออกจากเส้นทางโดยอัตโนมัติ เช่น หาก URL ของคอนเทนเนอร์เซิร์ฟเวอร์คือ https://example.com/analytics และเส้นทางคำขอคือ '/analytics/foo' ผลลัพธ์ที่ได้คือ '/foo'

ตัวอย่าง

const getRequestPath = require('getRequestPath');

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

ไวยากรณ์

getRequestPath();

สิทธิ์ที่เชื่อมโยง

read_request

getRequestQueryParameter

แสดงผลค่าที่ถอดรหัสแล้วของพารามิเตอร์สตริงการค้นหาที่มีชื่อเป็นสตริง หรือ undefined หากไม่มีพารามิเตอร์ หากพารามิเตอร์ซ้ำกันในสตริงการค้นหา ระบบจะแสดงผลค่าแรกที่ปรากฏในสตริงการค้นหา

ตัวอย่าง

const getRequestQueryParameter = require('getRequestQueryParameter');

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

ไวยากรณ์

getRequestQueryParameter(name);

พารามิเตอร์

พารามิเตอร์ ประเภท คำอธิบาย
name สตริง ชื่อพารามิเตอร์การค้นหา

สิทธิ์ที่เชื่อมโยง

read_request

getRequestQueryParameters

แสดงผลพารามิเตอร์การค้นหาของคําขอ HTTP ที่เข้ามาในรูปแบบออบเจ็กต์ที่แมปชื่อพารามิเตอร์การค้นหากับค่าที่เกี่ยวข้อง ระบบจะถอดรหัสชื่อและค่าของพารามิเตอร์

ตัวอย่าง

const getRequestQueryParameters = require('getRequestQueryParameters');

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

ไวยากรณ์

getRequestQueryParameters();

สิทธิ์ที่เชื่อมโยง

read_request

getRequestQueryString

แสดงผลคำค้นหาของคำขอเป็นสตริงโดยไม่มีเครื่องหมายคําถามนำหน้า หรือแสดงผลสตริงว่างหาก URL คำขอไม่มีสตริงการค้นหา

ตัวอย่าง

const getRequestQueryString = require('getRequestQueryString');

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

ไวยากรณ์

getRequestQueryString();

สิทธิ์ที่เชื่อมโยง

read_request

getTimestamp

เลิกใช้งานแล้ว โปรดใช้ getTimestampMillis

แสดงผลตัวเลขที่แสดงเวลาปัจจุบันเป็นมิลลิวินาทีนับจาก Unix Epoch ตามที่ Date.now() แสดง

ไวยากรณ์

getTimestamp();

สิทธิ์ที่เชื่อมโยง

ไม่มี

getTimestampMillis

แสดงผลตัวเลขที่แสดงเวลาปัจจุบันเป็นมิลลิวินาทีนับจาก Unix Epoch ตามที่ Date.now() แสดง

ไวยากรณ์

getTimestampMillis();

สิทธิ์ที่เชื่อมโยง

ไม่มี

getType

แสดงผลสตริงที่อธิบายประเภทของค่าที่ระบุ

ประเภทอินพุต ค่าที่แสดง
สตริง 'string'
number 'number'
บูลีน 'boolean'
null 'null'
undefined 'undefined'
อาร์เรย์ 'array'
ออบเจ็กต์ 'object'
การทำงาน 'function'

ตัวอย่าง

const getType = require('getType');

const type = getType(value);
if (type === 'string') {
  // Handle string input.
} else if (type === 'number') {
  // Handle numeric input.
} else {
  logToConsole('Unsupported input type: ', type);
}

ไวยากรณ์

getType(value);

พารามิเตอร์

พารามิเตอร์ ประเภท คำอธิบาย
value any ป้อนค่า

สิทธิ์ที่เชื่อมโยง

ไม่มี

hmacSha256

คํานวณลายเซ็นที่เข้ารหัสโดยใช้รหัสการตรวจสอบสิทธิ์ข้อความที่อิงตามแฮช (HMAC) ด้วย SHA-256 ค่าเริ่มต้นคือการเข้ารหัส base64url

หากต้องการใช้ API นี้ ให้ตั้งค่าตัวแปรสภาพแวดล้อม SGTM_CREDENTIALS ในเซิร์ฟเวอร์เป็นเส้นทางของไฟล์คีย์ JSON ที่เข้ารหัส UTF-8 ซึ่งมีรูปแบบดังนี้

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

ค่าคือคีย์ HMAC ที่เข้ารหัส Base64 ข้อความ JSON ต้องไม่ขึ้นต้นด้วยเครื่องหมายลำดับไบต์

ตัวอย่าง

const hmacSha256 = require('hmacSha256');
const toBase64 = require('toBase64');

const header = toBase64('{"alg":"HS256","typ":"JWT"}', {urlEncoding: true});
const claim = toBase64('{"sub":"1234567890","iat":1698164946}', {urlEncoding: true});
const signature = hmacSha256(header + '.' + claim, 'key1');

const jwt = header + "." + claim + '.' + signature;

ไวยากรณ์

hmacSha256(data, keyId, options)

พารามิเตอร์

พารามิเตอร์ ประเภท คำอธิบาย
data สตริง ข้อมูลสําหรับคํานวณค่า HMAC
keyId สตริง รหัสคีย์จากไฟล์คีย์ JSON ที่อ้างอิงคีย์ที่จะใช้
options object การกําหนดค่า API ไม่บังคับ (ดูตัวเลือกด้านล่าง)

ตัวเลือก

ตัวเลือก ประเภท คำอธิบาย
outputEncoding สตริง ระบุรูปแบบการเข้ารหัสสำหรับค่าที่แสดงผล รูปแบบที่รองรับ ได้แก่ hex, base64 หรือ base64url ค่าเริ่มต้นจะเป็น base64url หากไม่ได้ระบุไว้

สิทธิ์ที่เชื่อมโยง

use_custom_private_keys

เวอร์ชันรูปภาพขั้นต่ำ

1.0.0

isRequestMpv1

แสดงผล true หากคําขอขาเข้าเป็นคําขอ Measurement Protocol V1 หรือแสดงผล false ในกรณีอื่นๆ

ตัวอย่าง

const isRequestMpv1 = require('isRequestMpv1');

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

ไวยากรณ์

isRequestMpv1();

สิทธิ์ที่เชื่อมโยง

ไม่มี

isRequestMpv2

แสดงผล true หากคําขอขาเข้าเป็นคําขอ Measurement Protocol V2 หรือแสดงผล false ในกรณีอื่นๆ

ตัวอย่าง

const isRequestMpv2 = require('isRequestMpv2');

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

ไวยากรณ์

isRequestMpv2();

สิทธิ์ที่เชื่อมโยง

ไม่มี

logToConsole

บันทึกอาร์กิวเมนต์ไปยังคอนโซล

บันทึกเหล่านี้จะปรากฏใน Logs Explorer ในคอนโซล Google Cloud จากเครื่องมือสำรวจบันทึก ให้เรียกใช้การค้นหา logName =~ "stdout" เพื่อดูรายการบันทึกที่ API นี้สร้างขึ้น

ตัวอย่าง

const logToConsole = require('logToConsole');

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

ไวยากรณ์

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

พารามิเตอร์

API จะรับอาร์กิวเมนต์อย่างน้อย 1 รายการ โดยระบบจะแปลงอาร์กิวเมนต์แต่ละรายการเป็นสตริง (หากจําเป็น) และบันทึกลงในคอนโซล

สิทธิ์ที่เชื่อมโยง

logging

makeInteger

แปลงค่าที่ระบุเป็นตัวเลข (จำนวนเต็ม)

ไวยากรณ์

makeInteger(value);

พารามิเตอร์

พารามิเตอร์ ประเภท คำอธิบาย
value ประเภทใดก็ได้ ค่าที่จะแปลง

สิทธิ์ที่เชื่อมโยง

ไม่มี

makeNumber

แปลงค่าที่ระบุเป็นตัวเลข

ไวยากรณ์

makeNumber(value);

พารามิเตอร์

พารามิเตอร์ ประเภท คำอธิบาย
value ประเภทใดก็ได้ ค่าที่จะแปลง

สิทธิ์ที่เชื่อมโยง

ไม่มี

makeString

แสดงผลค่าที่ระบุเป็นสตริง

ไวยากรณ์

makeString(value);

พารามิเตอร์

พารามิเตอร์ ประเภท คำอธิบาย
value ประเภทใดก็ได้ ค่าที่จะแปลง

สิทธิ์ที่เชื่อมโยง

ไม่มี

makeTableMap

แปลงออบเจ็กต์ตารางแบบง่ายที่มี 2 คอลัมน์เป็น Map ซึ่งใช้เพื่อเปลี่ยนSIMPLE_TABLEฟิลด์เทมเพลตที่มี 2 คอลัมน์ให้เป็นรูปแบบที่จัดการได้ง่ายขึ้น

เช่น ฟังก์ชันนี้อาจแปลงออบเจ็กต์ตาราง

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

ลงในแผนที่

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

แสดงผลออบเจ็กต์: ระบบได้เพิ่มคู่คีย์-ค่า Map ที่แปลงแล้วลงในออบเจ็กต์ หรือ null ในกรณีอื่นๆ

ไวยากรณ์

makeTableMap(tableObj, keyColumnName, valueColumnName);

พารามิเตอร์

พารามิเตอร์ ประเภท คำอธิบาย
tableObj List ออบเจ็กต์ตารางที่จะแปลง นั่นคือรายการแผนที่ที่แต่ละMapแสดงถึงแถวในตาราง ชื่อพร็อพเพอร์ตี้แต่ละรายการในออบเจ็กต์แถวคือชื่อคอลัมน์ และค่าพร็อพเพอร์ตี้คือค่าคอลัมน์ในแถว
keyColumnName สตริง ชื่อคอลัมน์ที่ค่าจะกลายเป็นคีย์ในMapที่แปลงแล้ว
valueColumnName สตริง ชื่อคอลัมน์ที่ค่าจะกลายเป็นค่าในMapที่แปลงแล้ว

สิทธิ์ที่เชื่อมโยง

ไม่มี

parseUrl

แสดงผลออบเจ็กต์ที่มีองค์ประกอบทั้งหมดของ URL ที่ระบุ ซึ่งคล้ายกับออบเจ็กต์ URL

API นี้จะแสดงผล undefined สำหรับ URL ที่มีรูปแบบไม่ถูกต้อง สำหรับ URL ที่มีรูปแบบถูกต้อง ฟิลด์ที่ไม่มีอยู่ในสตริง URL จะมีค่าเป็นสตริงว่าง หรือในกรณีของ searchParams จะเป็นออบเจ็กต์ว่าง

ออบเจ็กต์ที่แสดงผลจะมีฟิลด์ต่อไปนี้

{
  href: string,
  origin: string,
  protocol: string,
  username: string,
  password: string,
  host: string,
  hostname: string,
  port: string,
  pathname: string,
  search: string,
  searchParams: Object<string, (string|Array)>,
  hash: string,
}

ตัวอย่าง

const parseUrl = require('parseUrl');

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

ไวยากรณ์

parseUrl(url);

พารามิเตอร์

พารามิเตอร์ ประเภท คำอธิบาย
url สตริง URL แบบเต็มที่จะแยกวิเคราะห์

สิทธิ์ที่เชื่อมโยง

ไม่มี

returnResponse

ล้างการตอบกลับที่ตั้งค่าไว้ก่อนหน้านี้โดยเทมเพลตอื่นๆ โดยใช้ API ที่แก้ไขการตอบกลับ ซึ่งรวมถึง setCookie, setPixelResponse, setResponseBody, setResponseHeader และ setResponseStatus ค่าเริ่มต้นคือรหัสสถานะ HTTP 200, เนื้อความว่างเปล่า และไม่มีส่วนหัว

ขอแนะนําให้ใช้ API นี้จากเทมเพลตไคลเอ็นต์

ไวยากรณ์

returnResponse();

ตัวอย่าง

ดูตัวอย่าง runContainer

สิทธิ์ที่เชื่อมโยง

return_response

runContainer

เรียกใช้ตรรกะคอนเทนเนอร์ (ตัวแปร ทริกเกอร์ แท็ก) ในขอบเขตของเหตุการณ์ หากมีการเรียก API นี้ระหว่างที่คอนเทนเนอร์ทำงาน ระบบจะเรียกใช้คอนเทนเนอร์อีกครั้ง

ฟังก์ชัน Callback ของ onComplete และ onStart จะได้รับฟังก์ชันที่ชื่อ bindToEvent ใช้ bindToEvent เพื่อเรียกใช้ API ในบริบทของเหตุการณ์ ดูรายละเอียดเพิ่มเติมได้ที่ตัวอย่าง addEventCallback

ขอแนะนําให้ใช้ API นี้จากเทมเพลตไคลเอ็นต์

ตัวอย่าง

const returnResponse = require('returnResponse');
const runContainer = require('runContainer');

// Runs the container with a simple pageview event and then returns a response.
runContainer({'event_name': 'pageview'}, () => returnResponse());

ไวยากรณ์

runContainer(event, onComplete, onStart);

พารามิเตอร์

พารามิเตอร์ ประเภท คำอธิบาย
event object พารามิเตอร์เหตุการณ์
onComplete function ฟังก์ชันการเรียกกลับที่เรียกใช้หลังจากแท็กทั้งหมดเริ่มทํางานเสร็จแล้ว
onStart function การเรียกกลับที่เรียกใช้ทันทีก่อนที่แท็กจะเริ่มทํางาน

สิทธิ์ที่เชื่อมโยง

run_container

sendEventToGoogleAnalytics

ส่งเหตุการณ์เดียวโดยใช้ Common Event Data ไปยัง Google Analytics และแสดงผลสัญญาที่แก้ไขเป็นออบเจ็กต์ที่มีคีย์ location หรือปฏิเสธเป็นออบเจ็กต์ที่มีคีย์ reason ปลายทางซึ่งเป็น Google Analytics 4 จะอิงตามรหัสการวัดในข้อมูลเหตุการณ์

ช่อง location มีการตั้งค่าเป็นส่วนหัว location หากมี

ตัวอย่าง

const logToConsole = require('logToConsole');
const sendEventToGoogleAnalytics = require('sendEventToGoogleAnalytics');
const setResponseHeader = require('setResponseHeader');
const setResponseStatus = require('setResponseStatus');

// Sends an event to Google Analytics and returns failure if the request did not
// succeed. Additionally, if the request resulted in a redirect request, the
// code nominates a redirect response to be returned.
sendEventToGoogleAnalytics(event).then((response) => {
  if (response.location) {
    setResponseHeader('location', response.location);
    setResponseStatus(302);
  } else {
    setResponseStatus(200);
  }
  data.gtmOnSuccess();
}).catch((error) => {
  logToConsole(error.reason);
  setResponseStatus(500);
  data.gtmOnFailure();
});

ไวยากรณ์

sendEventToGoogleAnalytics(event);

พารามิเตอร์

พารามิเตอร์ ประเภท คำอธิบาย
event object เหตุการณ์ในรูปแบบสคีมาแบบรวม

สิทธิ์ที่เชื่อมโยง

ต้องมีสิทธิ์ send_http สิทธิ์ต้องได้รับการกําหนดค่าให้อนุญาตการเข้าถึงอย่างน้อย

  • อนุญาต Google Domains

sendHttpGet

ส่งคำขอ HTTP GET ไปยัง URL ที่ระบุ และแสดงผลสัญญาที่แสดงผลลัพธ์เมื่อคำขอเสร็จสมบูรณ์หรือหมดเวลา

ผลลัพธ์ที่แก้ไขแล้วคือออบเจ็กต์ที่มีคีย์ 3 คีย์ ได้แก่ statusCode, headers และ body หากคําขอไม่สําเร็จ (เช่น URL ไม่ถูกต้อง ไม่มีเส้นทางไปยังโฮสต์ การเจรจา SSL ไม่สําเร็จ ฯลฯ) ระบบจะปฏิเสธ Promise ด้วย {reason: 'failed'} หากตั้งค่าตัวเลือก timeout และคำขอหมดเวลา ระบบจะปฏิเสธ Promise ด้วย {reason: 'timed_out'}

ตัวอย่าง

const sendHttpGet = require('sendHttpGet');

// Returns the response body as the value for a variable.
return sendHttpGet('https://example.com/item/' + data.itemId, {
  headers: {key: 'value'},
  timeout: 500,
}).then((result) => result.body, () => undefined);

ไวยากรณ์

sendHttpGet(url[, options]);

พารามิเตอร์

พารามิเตอร์ ประเภท คำอธิบาย
url สตริง URL ที่ขอ
options object ตัวเลือกคำขอไม่บังคับ (ดูตัวเลือกด้านล่าง)

ตัวเลือก

ตัวเลือก ประเภท คำอธิบาย
headers สตริง ส่วนหัวคำขอเพิ่มเติม
timeout number ระยะหมดเวลาเป็นมิลลิวินาทีก่อนที่ระบบจะยกเลิกคำขอ ค่าเริ่มต้นคือ 15000
authorization object ออบเจ็กต์การให้สิทธิ์ไม่บังคับจากการเรียกใช้ getGoogleAuth เพื่อรวมส่วนหัวการให้สิทธิ์เมื่อส่งคำขอไปยัง googleapis.com

สิทธิ์ที่เชื่อมโยง

send_http

sendHttpRequest

ส่งคําขอ HTTP ไปยัง URL ที่ระบุ และแสดงผลสัญญาที่แก้ไขด้วยการตอบกลับเมื่อคําขอเสร็จสมบูรณ์หรือหมดเวลา

ผลลัพธ์ที่แก้ไขแล้วคือออบเจ็กต์ที่มีคีย์ 3 คีย์ ได้แก่ statusCode, headers และ body หากคําขอไม่สําเร็จ (เช่น URL ไม่ถูกต้อง ไม่มีเส้นทางไปยังโฮสต์ การเจรจา SSL ไม่สําเร็จ ฯลฯ) ระบบจะปฏิเสธ Promise ด้วย {reason: 'failed'} หากตั้งค่าตัวเลือก timeout และคำขอหมดเวลา ระบบจะปฏิเสธ Promise ด้วย {reason: 'timed_out'}

ตัวอย่าง

const sendHttpRequest = require('sendHttpRequest');
const setResponseBody = require('setResponseBody');
const setResponseHeader = require('setResponseHeader');
const setResponseStatus = require('setResponseStatus');

const postBody = 'interaction=click&campaign=promotion&medium=email';
// Sends a POST request and nominates response based on the response to the POST
// request.
sendHttpRequest('https://example.com/collect', {
  headers: {key: 'value'},
  method: 'POST',
  timeout: 500,
}, postBody).then((result) => {
  setResponseStatus(result.statusCode);
  setResponseBody(result.body);
  setResponseHeader('cache-control', result.headers['cache-control']);
});

ไวยากรณ์

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

พารามิเตอร์

พารามิเตอร์ ประเภท คำอธิบาย
url สตริง URL ที่ขอ
options object ตัวเลือกคำขอไม่บังคับ (ดูตัวเลือกด้านล่าง)
body สตริง เนื้อหาคําขอไม่บังคับ

ตัวเลือก

ตัวเลือก ประเภท คำอธิบาย
headers สตริง ส่วนหัวคำขอเพิ่มเติม
method object เมธอดคำขอ ค่าเริ่มต้นคือ GET
timeout number ระยะหมดเวลาเป็นมิลลิวินาทีก่อนที่ระบบจะยกเลิกคำขอ ค่าเริ่มต้นคือ 15000
authorization object ออบเจ็กต์การให้สิทธิ์ไม่บังคับจากการเรียกใช้ getGoogleAuth เพื่อรวมส่วนหัวการให้สิทธิ์เมื่อส่งคำขอไปยัง googleapis.com

สิทธิ์ที่เชื่อมโยง

send_http

sendPixelFromBrowser

ส่งคําสั่งไปยังเบราว์เซอร์ให้โหลด URL ที่ระบุเป็นแท็ก <img> โปรโตคอลคําสั่งนี้ใช้ได้ในแท็ก Google สําหรับ GA4 และแท็กเว็บ Google Analytics: เหตุการณ์ GA คุณต้องกำหนดค่า URL ของคอนเทนเนอร์เซิร์ฟเวอร์ ดูรายละเอียดเพิ่มเติมในวิธีการ

API นี้จะแสดงผล false หากคําขอขาเข้าไม่รองรับโปรโตคอลคําสั่ง หรือหากมีการล้างการตอบกลับแล้ว มิเช่นนั้น API นี้จะแสดงผลเป็น true

ตัวอย่างเช่น

const sendPixelFromBrowser = require('sendPixelFromBrowser');

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

ไวยากรณ์

sendPixelFromBrowser(url)

พารามิเตอร์

พารามิเตอร์ ประเภท คำอธิบาย
url สตริง URL ที่ส่งไปยังเบราว์เซอร์

สิทธิ์ที่เชื่อมโยง

send_pixel_from_browser

setCookie

ตั้งค่าหรือลบคุกกี้ด้วยตัวเลือกที่ระบุ

หากต้องการลบคุกกี้ คุณต้องตั้งค่าคุกกี้ที่มีเส้นทางและโดเมนเดียวกับที่ใช้สร้างคุกกี้ และกำหนดค่า "หมดอายุ" ให้เป็นค่าที่ผ่านมาแล้ว เช่น "Thu, 01 Jan 1970 00:00:00 GMT"

โปรดทราบว่าต้องเรียกใช้ returnResponse เพื่อให้ระบบส่งการตอบกลับกลับไปยังไคลเอ็นต์

ตัวอย่าง

const setCookie = require('setCookie');

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

ไวยากรณ์

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

พารามิเตอร์

พารามิเตอร์ ประเภท คำอธิบาย
name สตริง ชื่อคุกกี้ ชื่อจะไม่คำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่
value สตริง ค่าคุกกี้
options object แอตทริบิวต์คุกกี้ที่ไม่บังคับ ได้แก่ domain, expires, fallbackDomain, httpOnly, max-age, path, secure และ sameSite (ดูตัวเลือกด้านล่าง)
noEncode บูลีน หากเป็นจริง ระบบจะไม่เข้ารหัสค่าคุกกี้ ค่าเริ่มต้นคือ false

ตัวเลือก

  • domain: โฮสต์ที่จะส่งคุกกี้ไป หากกำหนดเป็นค่าพิเศษ 'อัตโนมัติ' แล้ว ระบบจะคำนวณโฮสต์โดยอัตโนมัติโดยใช้กลยุทธ์ต่อไปนี้

    • eTLD+1 ของส่วนหัว Forwarded (หากมี)
    • eTLD+1 ของส่วนหัว X-Forwarded-Host (หากมี)
    • eTLD+1 ของส่วนหัว Host

  • expires: อายุการใช้งานสูงสุดของคุกกี้ ต้องเป็นสตริงวันที่ในรูปแบบ UTC เช่น "Sat, 26 Oct 1985 08:21:00 GMT" หากตั้งค่าทั้ง expires และ max-age max-age จะมีลำดับความสำคัญเหนือกว่า

  • httpOnly: ห้ามไม่ให้ JavaScript เข้าถึงคุกกี้หาก true

  • max-age: จำนวนวินาทีก่อนที่คุกกี้จะหมดอายุ ตัวเลขที่เป็น 0 หรือติดลบจะทำให้คุกกี้หมดอายุทันที หากตั้งค่าทั้ง expires และ max-age max-age จะมีลำดับความสำคัญเหนือกว่า

  • path: เส้นทางที่ต้องอยู่ใน URL ที่ขอ มิเช่นนั้นเบราว์เซอร์จะไม่ส่งส่วนหัวคุกกี้

  • secure: หากตั้งค่าเป็น true ระบบจะส่งคุกกี้ไปยังเซิร์ฟเวอร์ก็ต่อเมื่อมีการส่งคําขอจากปลายทาง https: เท่านั้น

  • sameSite: ยืนยันว่าต้องไม่ส่งคุกกี้พร้อมกับคำขอข้ามแหล่งที่มา ต้องเท่ากับ 'strict', 'lax' หรือ 'none'

สิทธิ์ที่เชื่อมโยง

set_cookie

setPixelResponse

ตั้งค่าเนื้อหาการตอบกลับเป็น GIF ขนาด 1x1, ตั้งค่าส่วนหัว Content-Type เป็น "image/gif", ตั้งค่าส่วนหัวการแคชเพื่อให้ User Agent ไม่ได้แคชการตอบกลับ และตั้งค่าสถานะการตอบกลับเป็น 200

โปรดทราบว่าต้องเรียกใช้ returnResponse เพื่อให้ระบบส่งการตอบกลับกลับไปยังไคลเอ็นต์

ไวยากรณ์

setPixelResponse();

สิทธิ์ที่เชื่อมโยง

ต้องมีสิทธิ์ access_response คุณต้องกำหนดค่าสิทธิ์ให้อนุญาตการเข้าถึงอย่างน้อยสิ่งต่อไปนี้

  • headers - ต้องอนุญาตคีย์ต่อไปนี้
    • content-type
    • cache-control
    • expires
    • pragma
  • body
  • status

setResponseBody

ตั้งค่าเนื้อหาของคำตอบเป็นอาร์กิวเมนต์

โปรดทราบว่าต้องเรียกใช้ returnResponse เพื่อให้ระบบส่งการตอบกลับกลับไปยังไคลเอ็นต์

ไวยากรณ์

setResponseBody(body[, encoding]);

พารามิเตอร์

พารามิเตอร์ ประเภท คำอธิบาย
body สตริง ค่าที่จะตั้งเป็นเนื้อหาของคำตอบ
encoding สตริง การแปลงอักขระของเนื้อหาการตอบกลับ (ค่าเริ่มต้นคือ 'utf8') ค่าที่รองรับ ได้แก่ 'ascii', 'utf8', 'utf16le', 'ucs2', 'base64', 'latin1', 'binary' และ 'hex'

สิทธิ์ที่เชื่อมโยง

ต้องมีสิทธิ์ access_response คุณต้องกำหนดค่าสิทธิ์ให้อนุญาตการเข้าถึงอย่างน้อยสิ่งต่อไปนี้

  • body

setResponseHeader

ตั้งค่าส่วนหัวในการตอบกลับที่จะแสดง หาก API นี้เคยตั้งค่าส่วนหัวที่มีชื่อนี้ไว้ (ไม่คำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่) การเรียกใช้ครั้งหลังจะเขียนทับหรือล้างค่าที่ผู้เรียกใช้ก่อนหน้าตั้งไว้

โปรดทราบว่าต้องเรียกใช้ returnResponse เพื่อให้ระบบส่งการตอบกลับกลับไปยังไคลเอ็นต์

ไวยากรณ์

setResponseHeader(name, value);

พารามิเตอร์

พารามิเตอร์ ประเภท คำอธิบาย
name สตริง ชื่อส่วนหัว ชื่อส่วนหัว HTTP ไม่คำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่ ดังนั้นชื่อส่วนหัวจะเป็นตัวพิมพ์เล็ก
value string undefined ค่าของส่วนหัว หากเป็นค่า Null หรือไม่มีการกำหนดค่า ระบบจะล้างส่วนหัวที่มีชื่อออกจากการตอบกลับที่จะแสดง

สิทธิ์ที่เชื่อมโยง

ต้องมีสิทธิ์ access_response คุณต้องกำหนดค่าสิทธิ์ให้อนุญาตการเข้าถึงอย่างน้อยสิ่งต่อไปนี้

  • headers

setResponseStatus

ตั้งค่ารหัสสถานะ HTTP ของการตอบกลับที่จะแสดง

โปรดทราบว่าต้องเรียกใช้ returnResponse เพื่อให้ระบบส่งการตอบกลับกลับไปยังไคลเอ็นต์

ไวยากรณ์

setResponseStatus(statusCode);

พารามิเตอร์

พารามิเตอร์ ประเภท คำอธิบาย
statusCode number รหัสสถานะ HTTP ที่แสดง

สิทธิ์ที่เชื่อมโยง

ต้องมีสิทธิ์ access_response คุณต้องกำหนดค่าสิทธิ์ให้อนุญาตการเข้าถึงอย่างน้อยสิ่งต่อไปนี้

  • status

sha256

คํานวณข้อมูลสรุป SHA-256 ของอินพุตและเรียกใช้การเรียกกลับด้วยข้อมูลสรุปที่เข้ารหัสฐาน 64 เว้นแต่ออบเจ็กต์ options จะระบุการเข้ารหัสเอาต์พุตอื่น

ลายเซ็นและลักษณะการทํางานของ API นี้ตรงกับ sha256 API สําหรับคอนเทนเนอร์เว็บ แต่เทมเพลตที่กําหนดเองในคอนเทนเนอร์เซิร์ฟเวอร์ควรใช้ sha256Sync API เพื่อให้โค้ดเรียบง่ายขึ้น

ตัวอย่าง

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

sha256('inputString', (digest) => {
  sendHttpGet('https://example.com/collect?id=' + encodeUriComponent(digest));
});

sha256('inputString', (digest) => {
  sendHttpGet('https://example.com/collect?id=' + encodeUriComponent(digest));
}, {outputEncoding: 'hex'});

ไวยากรณ์

sha256(input, onSuccess, options = undefined);

พารามิเตอร์

พารามิเตอร์ ประเภท คำอธิบาย
input สตริง สตริงที่จะแฮช
onSuccess function เรียกใช้ด้วยข้อมูลสรุปที่ได้ซึ่งเข้ารหัสใน Base64 เว้นแต่ออบเจ็กต์ options จะระบุการเข้ารหัสเอาต์พุตอื่น
options object ออบเจ็กต์ตัวเลือกไม่บังคับสำหรับระบุการเข้ารหัสเอาต์พุต หากระบุ ออบเจ็กต์ควรมีคีย์ outputEncoding ที่มีค่าเป็น base64 หรือ hex

สิทธิ์ที่เชื่อมโยง

ไม่มี

sha256Sync

คํานวณและแสดงผลข้อมูลสรุป SHA-256 ของอินพุตที่เข้ารหัสฐาน 64 เว้นแต่ออบเจ็กต์ options จะระบุการเข้ารหัสเอาต์พุตอื่น

ตัวอย่าง

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

const digestBase64 = sha256Sync('inputString');
const digestHex = sha256Sync('inputString', {outputEncoding: 'hex'});
sendHttpGet('https://example.com/collect?id=' + encodeUriComponent(digestBase64));
sendHttpGet('https://example.com/collect?id=' + encodeUriComponent(digestHex));

ไวยากรณ์

sha256Sync(input, options = undefined);

พารามิเตอร์

พารามิเตอร์ ประเภท คำอธิบาย
input สตริง สตริงที่จะแฮช
options object ออบเจ็กต์ตัวเลือกไม่บังคับสำหรับระบุการเข้ารหัสเอาต์พุต หากระบุ ออบเจ็กต์ควรมีคีย์ outputEncoding ที่มีค่าเป็น base64 หรือ hex

สิทธิ์ที่เชื่อมโยง

ไม่มี

templateDataStorage

ส่งคืนออบเจ็กต์ที่มีเมธอดสําหรับการเข้าถึงพื้นที่เก็บข้อมูลเทมเพลต พื้นที่เก็บข้อมูลเทมเพลตช่วยให้แชร์ข้อมูลได้ระหว่างการเรียกใช้เทมเพลตเดียว ข้อมูลที่จัดเก็บไว้ในพื้นที่เก็บข้อมูลของเทมเพลตจะยังคงอยู่ในเซิร์ฟเวอร์ที่เรียกใช้คอนเทนเนอร์ ในกรณีส่วนใหญ่จะมีเซิร์ฟเวอร์หลายเครื่องที่เรียกใช้คอนเทนเนอร์ ดังนั้นการจัดเก็บข้อมูลในที่เก็บข้อมูลของเทมเพลตจึงไม่ได้รับประกันว่าคําขอที่ตามมาทุกรายการจะมีสิทธิ์เข้าถึงข้อมูล

"data" ในชื่อ "templateDataStorage" หมายถึงการจัดเก็บได้เฉพาะประเภทข้อมูลธรรมดาที่ไม่ใช่ฟังก์ชันโดยใช้ API นี้ ระบบจะจัดเก็บฟังก์ชันหรือการอ้างอิงฟังก์ชันที่ส่งไปยัง API เป็น null แทน

ไวยากรณ์

const templateDataStorage = require('templateDataStorage');

// Returns a copy of the value stored for the given key, or null if nothing
// is stored with that key.
templateDataStorage.getItemCopy(key);

// Stores a copy of the value for the given key (or removes the data stored
// for the given key if the input value is null).
templateDataStorage.setItemCopy(key, value);

// Removes the value stored for the given key, if present.
templateDataStorage.removeItem(key);

// Deletes all values stored for the current template.
templateDataStorage.clear();

ตัวอย่าง

const sendHttpGet = require('sendHttpGet');
const setResponseBody = require('setResponseBody');
const setResponseStatus = require('setResponseStatus');
const templateDataStorage = require('templateDataStorage');

// Check to see if the item is in the cache.
const cachedBody = templateDataStorage.getItemCopy(data.key);
if (cachedBody) {
  setResponseBody(cachedBody);
  data.gtmOnSuccess();
  return;
}

sendHttpGet(data.url).then((result) => {
  if (result.statusCode >= 200 && result.statusCode < 300) {
    setResponseBody(result.body);
    templateDataStorage.setItemCopy(data.key, result.body);
    data.gtmOnSuccess();
  } else {
    data.gtmOnFailure();
  }
  setResponseStatus(result.statusCode);
});

สิทธิ์ที่เชื่อมโยง

access_template_storage

testRegex

ทดสอบสตริงกับนิพจน์ทั่วไปที่สร้างผ่าน createRegex API แสดงผลเป็น true หากนิพจน์ทั่วไปตรงกัน หรือจะแสดงผล false ก็ได้

นิพจน์ทั่วไปที่สร้างด้วย Flag แบบ Global จะมีสถานะ ดูรายละเอียดได้ในเอกสารประกอบของ RegExp

ตัวอย่าง

const createRegex = require('createRegex');
const testRegex = require('testRegex');

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

// createRegex returns null if the regex is invalid or Re2 is not available.
if (domainRegex === null) return;

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

ไวยากรณ์

testRegex(regex, string);

พารามิเตอร์

พารามิเตอร์ ประเภท คำอธิบาย
regex ออบเจ็กต์ นิพจน์ทั่วไปที่จะทดสอบ ซึ่งแสดงผลจาก createRegex API
string สตริง สตริงทดสอบเพื่อทดสอบ

สิทธิ์ที่เชื่อมโยง

ไม่มี

toBase64

เข้ารหัสสตริงเป็น Base64 หรือ Base64Url ค่าเริ่มต้นคือการเข้ารหัส Base64

ไวยากรณ์

toBase64(input, options);

พารามิเตอร์

พารามิเตอร์ ประเภท คำอธิบาย
input สตริง สตริงที่จะเข้ารหัส
options object การกําหนดค่า API ไม่บังคับ (ดูตัวเลือกด้านล่าง)

ตัวเลือก

ตัวเลือก ประเภท คำอธิบาย เวอร์ชันต่ำสุด
urlEncoding บูลีน หากเป็น "จริง" ผลลัพธ์จะได้รับการโค้ดโดยใช้รูปแบบ base64url 1.0.0

ตัวอย่าง

const toBase64 = require('toBase64');

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

สิทธิ์ที่เชื่อมโยง

ไม่มี

BigQuery

แสดงผลออบเจ็กต์ที่มีฟังก์ชัน BigQuery

ฟังก์ชัน BigQuery.insert ช่วยให้เขียนข้อมูลลงในตาราง BigQuery ได้ โดยจะแสดงผลสัญญาที่แสดงผลเมื่อแทรกข้อมูลสำเร็จ หรือปฏิเสธเมื่อเกิดข้อผิดพลาด

เมื่อแทรกสำเร็จแล้ว พรอมต์จะได้รับการแก้ไขโดยไม่มีอาร์กิวเมนต์

เมื่อการแทรกไม่สําเร็จ พรมิสจะปฏิเสธพร้อมแสดงรายการออบเจ็กต์ที่มีเหตุผลของข้อผิดพลาด และอาจมีออบเจ็กต์แถวหากเกิดข้อผิดพลาด เป็นไปได้ที่คำขอบางส่วนจะดำเนินการเสร็จสมบูรณ์ แต่ส่วนอื่นๆ ดำเนินการไม่สำเร็จ ในกรณีนี้ ระบบจะปฏิเสธสัญญาพร้อมแสดงรายการข้อผิดพลาดสำหรับแต่ละแถวที่มีออบเจ็กต์แถวเพื่อช่วยแยกแยะแถวที่แทรก (ดูตัวอย่างข้อผิดพลาดด้านล่าง) ดูข้อมูลเพิ่มเติมได้จากเอกสารประกอบของ BigQuery เกี่ยวกับข้อความแสดงข้อผิดพลาด

ไวยากรณ์

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

พารามิเตอร์

พารามิเตอร์ ประเภท คำอธิบาย
connectionInfo object กําหนดข้อมูลที่จําเป็นสําหรับเชื่อมต่อกับตาราง BigQuery โดยจะมีพารามิเตอร์ที่ไม่บังคับ 1 รายการและพารามิเตอร์ที่ต้องระบุ 2 รายการ ดังนี้
  • projectId - รหัสโปรเจ็กต์ Google Cloud Platform(ไม่บังคับ) หากไม่ระบุ ระบบจะดึงข้อมูล projectId จากตัวแปรสภาพแวดล้อม GOOGLE_CLOUD_PROJECT ตราบใดที่การตั้งค่าสิทธิ์สำหรับรหัสโปรเจ็กต์ access_bigquery ตั้งค่าเป็น * หรือ GOOGLE_CLOUD_PROJECT หากคอนเทนเนอร์เซิร์ฟเวอร์ทำงานอยู่ใน Google Cloud ระบบจะตั้งค่า GOOGLE_CLOUD_PROJECT เป็นรหัสโปรเจ็กต์ Google Cloud อยู่แล้ว
  • datasetId - รหัสชุดข้อมูล BigQuery
  • tableId - รหัสตาราง BigQuery
rows อาร์เรย์ แถวที่จะแทรกลงในตาราง
options object ตัวเลือกคำขอที่ไม่บังคับ ตัวเลือกที่รองรับ ได้แก่ ignoreUnknownValues และ skipInvalidRows ระบบจะไม่สนใจคีย์ตัวเลือกที่ไม่รู้จัก (ดูตัวเลือกด้านล่าง)

ตัวเลือก

พารามิเตอร์ ประเภท คำอธิบาย
ignoreUnknownValues บูลีน หากตั้งค่าเป็น true ระบบจะยอมรับแถวที่มีค่าที่ไม่ตรงกับสคีมา ระบบจะไม่สนใจค่าที่ไม่รู้จัก ค่าเริ่มต้นคือ false
skipInvalidRows บูลีน หากตั้งค่าเป็น true ระบบจะแทรกแถวที่ถูกต้องทั้งหมดของคำขอ แม้ว่าจะมีแถวที่ไม่ถูกต้องอยู่ก็ตาม ค่าเริ่มต้นคือ false

ตัวอย่างข้อผิดพลาด

ข้อผิดพลาด "ไม่พบโมดูล" หมายความว่าคอนเทนเนอร์เซิร์ฟเวอร์ของคุณอาจใช้อิมเมจเวอร์ชันเก่าซึ่งยังไม่มีโมดูล BigQuery โปรดทำให้คอนเทนเนอร์เซิร์ฟเวอร์ใช้งานได้อีกครั้งโดยใช้การตั้งค่าเดียวกันโดยใช้สคริปต์การทำให้ใช้งานได้ ระบบจะรวมข้อบังคับนั้นโดยอัตโนมัติเมื่อการดำเนินการเสร็จสิ้น

ข้อผิดพลาดที่ไม่ใช่การแทรกมักจะมีออบเจ็กต์ข้อผิดพลาด 1 รายการที่มีคีย์ reason ดังนี้

[{reason: 'invalid'}]

ข้อผิดพลาดในการแทรกอาจมีออบเจ็กต์ข้อผิดพลาดหลายรายการที่มีอาร์เรย์ errors และออบเจ็กต์ row ต่อไปนี้คือตัวอย่างการตอบกลับข้อผิดพลาดจากการแทรก 2 แถวที่มีเพียงแถวเดียวที่มีข้อผิดพลาด

[
  {
    "errors": [
      {
        "reason":"invalid"
      }
    ],
    "row": {
      "string_col":"otherString",
      "number_col":-3,
      "bool_col":3
    }
  },
  {
    "errors": [
      {
        "reason":"stopped"
      }
    ],
    "row": {
      "string_col":"stringValue",
      "number_col":5,
      "bool_col:false
    }
  }
]

ตัวอย่าง

const BigQuery = require('BigQuery');

const connectionInfo = {
  'projectId': 'gcp-cloud-project-id',
  'datasetId': 'destination-dataset',
  'tableId': 'destination-table',
};

const rows = [{
  'column1': 'String1',
  'column2': 1234,
}];

const options = {
  'ignoreUnknownValues': true,
  'skipInvalidRows': false,
};

BigQuery.insert(connectionInfo, rows, options)
  .then(data.gtmOnSuccess, data.gtmOnFailure);

สิทธิ์ที่เชื่อมโยง

access_bigquery

Firestore

แสดงผลออบเจ็กต์ที่มีฟังก์ชัน Firestore

API นี้รองรับเฉพาะ Firestore ในโหมดเนทีฟ และไม่รองรับ Firestore ในโหมด Datastore นอกจากนี้ API ยังรองรับเฉพาะการใช้ฐานข้อมูลเริ่มต้นเท่านั้น

Firestore.read

ฟังก์ชัน Firestore.read จะอ่านข้อมูลจากเอกสาร Firestore และส่งคืน Promise ที่แสดงผลเป็นออบเจ็กต์ที่มีคีย์ 2 คีย์ ได้แก่ id และ data หากเอกสารไม่อยู่ พรอมต์จะปฏิเสธพร้อมออบเจ็กต์ที่มีคีย์ reason เท่ากับ not_found

ไวยากรณ์

Firestore.read(path[, options]);

พารามิเตอร์

พารามิเตอร์ ประเภท คำอธิบาย
path สตริง เส้นทางไปยังเอกสารหรือคอลเล็กชัน ต้องไม่ขึ้นต้นหรือลงท้ายด้วย '/'
options object ตัวเลือกคำขอไม่บังคับ ตัวเลือกที่รองรับ ได้แก่ projectId, disableCache และ transaction ระบบจะไม่สนใจคีย์ตัวเลือกที่ไม่รู้จัก (ดูตัวเลือกด้านล่าง)

ตัวเลือก

พารามิเตอร์ ประเภท คำอธิบาย
projectId สตริง ไม่บังคับ รหัสโปรเจ็กต์ Google Cloud Platform หากไม่ระบุ ระบบจะดึงข้อมูล projectId จากตัวแปรสภาพแวดล้อม GOOGLE_CLOUD_PROJECT ตราบใดที่การตั้งค่าสิทธิ์สำหรับรหัสโปรเจ็กต์ access_firestore ตั้งค่าเป็น * หรือ GOOGLE_CLOUD_PROJECT หากคอนเทนเนอร์เซิร์ฟเวอร์ทำงานอยู่ใน Google Cloud ระบบจะตั้งค่า GOOGLE_CLOUD_PROJECT เป็นรหัสโปรเจ็กต์ Google Cloud อยู่แล้ว
disableCache บูลีน ไม่บังคับ กำหนดว่าจะปิดใช้แคชหรือไม่ ระบบจะเปิดใช้การแคชโดยค่าเริ่มต้น ซึ่งจะแคชผลลัพธ์ไว้ตลอดระยะเวลาของคำขอ
transaction สตริง ไม่บังคับ ค่าที่ดึงมาจาก Firestore.runTransaction() การทำเครื่องหมายการดำเนินการที่จะใช้ในธุรกรรม

ตัวอย่าง

const Firestore = require('Firestore');

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

Firestore.write

ฟังก์ชัน Firestore.write จะเขียนข้อมูลลงในเอกสารหรือคอลเล็กชัน Firestore หากเป็นเส้นทางไปยังคอลเล็กชัน ระบบจะสร้างเอกสารที่มีรหัสที่สร้างขึ้นแบบสุ่ม หากเป็นเส้นทางไปยังเอกสารและยังไม่มีเอกสารดังกล่าว ระบบจะสร้างเอกสารให้ API นี้จะแสดงผลลัพธ์เป็นสัญญาที่แปลงเป็นรหัสของเอกสารที่เพิ่มหรือแก้ไข หากใช้ตัวเลือกธุรกรรม API จะยังคงแสดงผลพรอมต์ แต่จะไม่มีรหัสเนื่องจากมีการเขียนเป็นกลุ่ม

ไวยากรณ์

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

พารามิเตอร์

พารามิเตอร์ ประเภท คำอธิบาย
path สตริง เส้นทางไปยังเอกสารหรือคอลเล็กชัน ต้องไม่ขึ้นต้นหรือลงท้ายด้วย '/'
input object ค่าที่จะเขียนลงในเอกสาร หากตั้งค่าตัวเลือกการผสานไว้ API จะผสานคีย์จากอินพุตลงในเอกสาร
options object ตัวเลือกคำขอไม่บังคับ ตัวเลือกที่รองรับ ได้แก่ projectId, merge และ transaction ระบบจะไม่สนใจคีย์ตัวเลือกที่ไม่รู้จัก (ดูตัวเลือกด้านล่าง)

ตัวเลือก

พารามิเตอร์ ประเภท คำอธิบาย
projectId สตริง ไม่บังคับ รหัสโปรเจ็กต์ Google Cloud Platform หากไม่ระบุ ระบบจะดึงข้อมูล projectId จากตัวแปรสภาพแวดล้อม GOOGLE_CLOUD_PROJECT ตราบใดที่การตั้งค่าสิทธิ์สำหรับรหัสโปรเจ็กต์ access_firestore ตั้งค่าเป็น * หรือ GOOGLE_CLOUD_PROJECT หากคอนเทนเนอร์เซิร์ฟเวอร์ทำงานอยู่ใน Google Cloud ระบบจะตั้งค่า GOOGLE_CLOUD_PROJECT เป็นรหัสโปรเจ็กต์ Google Cloud อยู่แล้ว
merge บูลีน ไม่บังคับ หากตั้งค่าเป็น true ระบบจะผสานคีย์จากอินพุตลงในเอกสาร มิเช่นนั้นเมธอดจะลบล้างทั้งเอกสาร ค่าเริ่มต้นคือ false
transaction สตริง ไม่บังคับ ค่าที่ดึงมาจาก Firestore.runTransaction() การทำเครื่องหมายการดำเนินการที่จะใช้ในธุรกรรม

ตัวอย่าง

const Firestore = require('Firestore');

const input = {key1: 'value1', key2: 12345};

Firestore.write('collection/document', input, {
  projectId: 'gcp-cloud-project-id',
  merge: true,
}).then((id) => {
  data.gtmOnSuccess();
}, data.gtmOnFailure);

Firestore.query

ฟังก์ชัน Firestore.query จะค้นหาคอลเล็กชันที่ระบุและแสดงผล Promise ที่แปลงเป็นอาร์เรย์เอกสาร Firestore ที่ตรงกับเงื่อนไขการค้นหา ออบเจ็กต์เอกสาร Firestore เหมือนกับที่แสดงไว้ข้างต้นใน Firestore.read หากไม่มีเอกสารที่ตรงกับเงื่อนไขการค้นหา พรอมต์ที่แสดงผลจะแสดงผลเป็นอาร์เรย์ว่าง

ไวยากรณ์

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

พารามิเตอร์

พารามิเตอร์ ประเภท คำอธิบาย
collection สตริง เส้นทางไปยังคอลเล็กชัน ต้องไม่ขึ้นต้นหรือลงท้ายด้วย '/'
queryConditions อาร์เรย์ อาร์เรย์ของเงื่อนไขการค้นหา การค้นหาแต่ละรายการอยู่ในรูปแบบของอาร์เรย์ที่มีค่า 3 ค่า ได้แก่ คีย์ โอเปอเรเตอร์ และค่าที่คาดหวัง เช่น [[‘id’, ‘<’, ‘5’], [‘state’, ‘==’, ‘CA’]].

ระบบจะรวมเงื่อนไข "และ" เข้าด้วยกันเพื่อสร้างผลการค้นหา โปรดดูรายการโอเปอเรเตอร์การค้นหาที่เข้ากันได้ที่ โอเปอเรเตอร์การค้นหาของ Firestore
options object ตัวเลือกคำขอไม่บังคับ ตัวเลือกที่รองรับ ได้แก่ projectId, disableCache, limit และ transaction ระบบจะไม่สนใจคีย์ตัวเลือกที่ไม่รู้จัก (ดูตัวเลือกด้านล่าง)

ตัวเลือก

พารามิเตอร์ ประเภท คำอธิบาย
projectId สตริง ไม่บังคับ รหัสโปรเจ็กต์ Google Cloud Platform หากไม่ระบุ ระบบจะดึงข้อมูล projectId จากตัวแปรสภาพแวดล้อม GOOGLE_CLOUD_PROJECT ตราบใดที่การตั้งค่าสิทธิ์สำหรับรหัสโปรเจ็กต์ access_firestore ตั้งค่าเป็น * หรือ GOOGLE_CLOUD_PROJECT หากคอนเทนเนอร์เซิร์ฟเวอร์ทำงานอยู่ใน Google Cloud ระบบจะตั้งค่า GOOGLE_CLOUD_PROJECT เป็นรหัสโปรเจ็กต์ Google Cloud อยู่แล้ว
disableCache บูลีน ไม่บังคับ กำหนดว่าจะปิดใช้แคชหรือไม่ ระบบจะเปิดใช้การแคชโดยค่าเริ่มต้น ซึ่งจะแคชผลลัพธ์ไว้ตลอดระยะเวลาของคำขอ
limit number ไม่บังคับ เปลี่ยนจำนวนผลลัพธ์สูงสุดที่แสดงโดยคำค้นหา โดยค่าเริ่มต้นคือ 5
transaction สตริง ไม่บังคับ ค่าที่ดึงมาจาก Firestore.runTransaction() การทำเครื่องหมายการดำเนินการที่จะใช้ในธุรกรรม

ตัวอย่าง

const Firestore = require('Firestore');

const queries = const queries = [['id', '==', '5']];

return Firestore.query('collection', queries, {
  projectId: 'gcp-cloud-project-id',
  limit: 1,
}).then((documents) => documents[0].data.key, () => undefined);

Firestore.runTransaction

ฟังก์ชัน Firestore.runTransaction ช่วยให้ผู้ใช้อ่านและเขียนจาก Firestore ได้แบบพร้อมกัน หากมีการเขียนพร้อมกันหรือธุรกรรมอื่นทับซ้อนกัน ระบบจะพยายามทำธุรกรรมอีกครั้งไม่เกิน 2 ครั้ง หากดำเนินการไม่สำเร็จหลังจากพยายามทั้งหมด 3 ครั้ง API จะปฏิเสธพร้อมแสดงข้อผิดพลาด API นี้จะแสดงผลเป็นสัญญาที่ให้ค่าเป็นอาร์เรย์ของรหัสเอกสารสําหรับการดําเนินการเขียนแต่ละรายการ หากธุรกรรมสําเร็จ และจะปฏิเสธพร้อมข้อผิดพลาดหากธุรกรรมไม่สําเร็จ

ไวยากรณ์

Firestore.runTransaction(callback[, options]);

พารามิเตอร์

พารามิเตอร์ ประเภท คำอธิบาย
callback function การเรียกกลับที่เรียกใช้ด้วยรหัสธุรกรรมสตริง คุณสามารถส่งรหัสธุรกรรมไปยังการเรียก API ของอ่าน/เขียน/ค้นหา ฟังก์ชัน Callback นี้ต้องแสดงผลพรอมต์ การเรียกกลับอาจทํางานได้สูงสุด 3 ครั้งก่อนที่จะไม่สําเร็จ
options object ตัวเลือกคำขอไม่บังคับ ตัวเลือกที่รองรับเพียงอย่างเดียวคือ projectId ระบบจะไม่สนใจคีย์ตัวเลือกที่ไม่รู้จัก (ดูตัวเลือกด้านล่าง)

ตัวเลือก

พารามิเตอร์ ประเภท คำอธิบาย
projectId สตริง ไม่บังคับ รหัสโปรเจ็กต์ Google Cloud Platform หากไม่ระบุ ระบบจะดึงข้อมูล projectId จากตัวแปรสภาพแวดล้อม GOOGLE_CLOUD_PROJECT ตราบใดที่การตั้งค่าสิทธิ์สำหรับรหัสโปรเจ็กต์ access_firestore ตั้งค่าเป็น * หรือ GOOGLE_CLOUD_PROJECT หากคอนเทนเนอร์เซิร์ฟเวอร์ทำงานอยู่ใน Google Cloud ระบบจะตั้งค่า GOOGLE_CLOUD_PROJECT เป็นรหัสโปรเจ็กต์ Google Cloud อยู่แล้ว

ตัวอย่าง

const Firestore = require('Firestore');

const path = 'collection/document';
const projectId = 'gcp-cloud-project-id';

Firestore.runTransaction((transaction) => {
  const transactionOptions = {
    projectId: projectId,
    transaction: transaction,
  };
  // Must return a promise.
  return Firestore.read(path, transactionOptions).then((result) => {
    const newInputCount = result.data.inputCount + 1;
    const input = {key1: 'value1', inputCount: newInputCount};
    return Firestore.write(path, input, transactionOptions);
  });
}, {
  projectId: projectId
}).then((ids) => {
  data.gtmOnSuccess();
}, data.gtmOnFailure);

ตัวอย่างข้อผิดพลาด

ข้อผิดพลาดที่มีอยู่ในฟังก์ชัน Firestore แต่ละรายการจะถูกปฏิเสธด้วยออบเจ็กต์ที่มีคีย์ reason ดังนี้

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

สาเหตุของข้อผิดพลาดอาจรวมถึงแต่ไม่จํากัดเพียงรหัสข้อผิดพลาด REST API ของ Firestore

สิทธิ์ที่เชื่อมโยง

access_firestore

JSON

แสดงผลออบเจ็กต์ที่มีฟังก์ชัน JSON

ฟังก์ชัน parse() จะแยกวิเคราะห์สตริง JSON เพื่อสร้างค่าหรือออบเจ็กต์ที่อธิบายโดยสตริง หากแยกวิเคราะห์ค่าไม่ได้ (เช่น JSON อยู่ในรูปแบบที่ไม่ถูกต้อง) ฟังก์ชันจะแสดงผล undefined หากค่าอินพุตไม่ใช่สตริง ระบบจะบังคับให้อินพุตเป็นสตริง

ฟังก์ชัน stringify() จะแปลงอินพุตเป็นสตริง JSON หากไม่สามารถแยกวิเคราะห์ค่าได้ (เช่น ออบเจ็กต์มีวงจร) เมธอดจะแสดงผล undefined

ตัวอย่าง

const JSON = require('JSON');

// The JSON input string is converted to an object.
const object = JSON.parse('{"foo":"bar"}');

// The input object is converted to a JSON string.
const str = JSON.stringify({foo: 'bar'});

ไวยากรณ์

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

สิทธิ์ที่เชื่อมโยง

ไม่มี

Math

ออบเจ็กต์ที่มีฟังก์ชัน Math

ไวยากรณ์

const Math = require('Math');

// Retrieve the absolute value.
const absolute = Math.abs(-3);

// Round the input down to the nearest integer.
const roundedDown = Math.floor(3.6);

// Round the input up to the nearest integer.
const roundedUp = Math.ceil(2.2);

// Round the input to the nearest integer.
const rounded = Math.round(3.1);

// Return the largest argument.
const biggest = Math.max(1, 3);

// Return the smallest argument.
const smallest = Math.min(3, 5);

// Return the first argument raised to the power of the second argument.
const powerful = Math.pow(3, 1);

// Return the square root of the argument.
const unsquared = Math.sqrt(9);

พารามิเตอร์

ระบบจะแปลงพารามิเตอร์ของฟังก์ชันคณิตศาสตร์เป็นตัวเลข

สิทธิ์ที่เชื่อมโยง

ไม่มี

Messages

API ต่อไปนี้ทํางานร่วมกันเพื่อให้ส่งข้อความระหว่างส่วนต่างๆ ของคอนเทนเนอร์ได้

addMessageListener

เพิ่มฟังก์ชันที่คอยฟังข้อความประเภทหนึ่งๆ เมื่อส่งข้อความประเภทนั้นโดยใช้ sendMessage API (โดยปกติจะใช้แท็ก) ระบบจะเรียกใช้การเรียกกลับแบบซิงค์ โค้ดเรียกกลับจะทํางานด้วยพารามิเตอร์ 2 รายการ ได้แก่

  1. messageType:string
  2. message:Object

หากเพิ่มการเรียกกลับในไคลเอ็นต์ การเรียกกลับจะได้รับข้อความจากเหตุการณ์ทั้งหมดที่ไคลเอ็นต์สร้างขึ้น หากต้องการให้การเรียกกลับได้รับข้อความจากเหตุการณ์หนึ่งๆ เท่านั้น ให้เชื่อมโยง API นี้กับเหตุการณ์โดยใช้ bindToEvent ในฟังก์ชัน onStart ของ runContainer API ดูตัวอย่าง

ไวยากรณ์

const addMessageListener = require('addMessageListener');

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

พารามิเตอร์

พารามิเตอร์ ประเภท คำอธิบาย
messageType สตริง ประเภทข้อความที่จะฟัง หากค่าไม่ใช่สตริง ระบบจะบังคับให้ค่าเป็นสตริง
callback function การดำเนินการเรียกกลับที่จะทำงานเมื่อมีการส่งข้อความประเภทที่เกี่ยวข้อง หากการติดต่อกลับไม่ใช่ฟังก์ชัน API จะไม่ดําเนินการใดๆ

ตัวอย่าง

const addMessageListener = require('addMessageListener');
const claimRequest = require('claimRequest');
const extractEventsFromMpv1 = require('extractEventsFromMpv1');
const returnResponse = require('returnResponse');
const runContainer = require('runContainer');

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

const events = extractEventsFromMpv1();
let eventsCompleted = 0;
events.forEach((event, i) => {
  runContainer(events[i], /* onComplete= */ () => {
    if (events.length === ++eventsCompleted) {
      returnResponse();
    }
  }, /* onStart= */ (bindToEvent) => {
    if (i === 0) {
      bindToEvent(addMessageListener)('send_pixel', (messageType, message) => {
        // This will be called whenever a tag for the first event sends a
        // 'send_pixel' message.
      });
    }
  });
});

สิทธิ์ที่เชื่อมโยง

ต้องมีสิทธิ์ use_message สิทธิ์ต้องได้รับการกําหนดค่าให้อนุญาตอย่างน้อย

  • ประเภทข้อความที่มี Usage ของ listen หรือ listen_and_send

hasMessageListener

แสดงผลเป็น "จริง" หากเพิ่มตัวรับฟังข้อความสําหรับประเภทข้อความที่ระบุแล้ว หากไม่ จะแสดงค่า "เท็จ"

ไวยากรณ์

const hasMessageListener = require('hasMessageListener');

hasMessageListener('send_pixel');

สิทธิ์ที่เชื่อมโยง

ไม่มี

sendMessage

ส่งข้อความประเภทที่ระบุไปยังผู้ฟังที่ลงทะเบียนไว้ ซึ่งสามารถใช้เพื่อส่งข้อความจากแท็กกลับไปให้ไคลเอ็นต์ที่เรียกใช้คอนเทนเนอร์

ไวยากรณ์

const sendMessage = require('sendMessage');

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

พารามิเตอร์

พารามิเตอร์ ประเภท คำอธิบาย
messageType สตริง ประเภทข้อความที่จะส่ง หากค่าไม่ใช่สตริง ระบบจะบังคับให้ค่าเป็นสตริง
message object ข้อความที่จะส่ง หากข้อความไม่ใช่ออบเจ็กต์ API จะไม่ดำเนินการใดๆ

สิทธิ์ที่เชื่อมโยง

ต้องมีสิทธิ์ use_message สิทธิ์ต้องได้รับการกําหนดค่าให้อนุญาตอย่างน้อย

  • ประเภทข้อความที่มี Usage ของ listen_and_send หรือ send

Object

แสดงผลออบเจ็กต์ที่มีเมธอด Object

เมธอด keys() มีลักษณะการทํางานของ Object.keys() ในไลบรารีมาตรฐาน โดยจะแสดงผลอาร์เรย์ของชื่อพร็อพเพอร์ตี้ที่นับได้ของออบเจ็กต์หนึ่งๆ ในลําดับเดียวกับที่ลูป for...in... จะแสดง หากค่าอินพุตไม่ใช่ออบเจ็กต์ ระบบจะบังคับให้ค่าเป็นออบเจ็กต์

เมธอด values() มีลักษณะการทํางานของ Object.values() ในไลบรารีมาตรฐาน โดยจะแสดงผลอาร์เรย์ของค่าพร็อพเพอร์ตี้ที่เอนกประสงค์ของออบเจ็กต์หนึ่งๆ ในลําดับเดียวกับที่ลูป for...in... จะแสดง หากค่าอินพุตไม่ใช่ออบเจ็กต์ ระบบจะบังคับให้ค่าเป็นออบเจ็กต์

เมธอด entries() มีลักษณะการทํางานของ Object.entries() ในไลบรารีมาตรฐาน โดยจะแสดงผลอาร์เรย์ของคู่พร็อพเพอร์ตี้ที่นับได้ของออบเจ็กต์หนึ่งๆ ในลําดับเดียวกับที่ลูป for...in... จะแสดง[key, value] หากค่าอินพุตไม่ใช่ออบเจ็กต์ ระบบจะบังคับให้ค่าเป็นออบเจ็กต์

เมธอด freeze() มีลักษณะการทำงาน Object.freeze() ของไลบรารีมาตรฐาน ออบเจ็กต์ที่หยุดทำงานจะเปลี่ยนแปลงไม่ได้อีกต่อไป การหยุดทำงานของออบเจ็กต์จะป้องกันไม่ให้มีการเพิ่มพร็อพเพอร์ตี้ใหม่ ลบพร็อพเพอร์ตี้ที่มีอยู่ และเปลี่ยนแปลงค่าของพร็อพเพอร์ตี้ที่มีอยู่ freeze() จะแสดงผลออบเจ็กต์เดียวกันกับที่ส่งเข้ามา ระบบจะถือว่าอาร์กิวเมนต์พื้นฐานหรือ Null เป็นออบเจ็กต์ที่หยุดทำงานและจะแสดงผล

เมธอด delete() มีลักษณะการทํางานของโอเปอเรเตอร์ delete ของไลบรารีมาตรฐาน ซึ่งจะนําคีย์ที่ระบุออกจากออบเจ็กต์ เว้นแต่ว่าออบเจ็กต์จะหยุดไว้ เช่นเดียวกับโอเปอเรเตอร์ delete ของไลบรารีมาตรฐาน ฟังก์ชันนี้จะแสดงผล true หากค่าอินพุตแรก (objectInput) เป็นออบเจ็กต์ที่ไม่ได้ตรึงไว้ แม้ว่าค่าอินพุตที่ 2 (keyToDelete) จะระบุคีย์ที่ไม่มีอยู่ก็ตาม และจะแสดงผลลัพธ์เป็น false ในกรณีอื่นๆ ทั้งหมด อย่างไรก็ตาม การดำเนินการนี้จะแตกต่างจากโอเปอเรเตอร์การลบของไลบรารีมาตรฐานดังนี้

  • keyToDelete ต้องไม่เป็นสตริงที่คั่นด้วยจุดซึ่งระบุคีย์ที่ฝังอยู่
  • คุณใช้ delete() เพื่อนำองค์ประกอบออกจากอาร์เรย์ไม่ได้
  • คุณใช้ delete() เพื่อนำพร็อพเพอร์ตี้ออกจากขอบเขตส่วนกลางไม่ได้

ไวยากรณ์

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

พารามิเตอร์

Object.keys

พารามิเตอร์ ประเภท คำอธิบาย
objectInput any ออบเจ็กต์ที่มีคีย์ที่จะแจกแจง หากอินพุตไม่ใช่ออบเจ็กต์ ระบบจะบังคับให้เป็นออบเจ็กต์

Object.values

พารามิเตอร์ ประเภท คำอธิบาย
objectInput any ออบเจ็กต์ที่จะแสดงค่า หากอินพุตไม่ใช่ออบเจ็กต์ ระบบจะบังคับให้เป็นออบเจ็กต์

Object.entries

พารามิเตอร์ ประเภท คำอธิบาย
objectInput any ออบเจ็กต์ที่มีคู่คีย์/ค่าที่จะแสดงรายการ หากอินพุตไม่ใช่ออบเจ็กต์ ระบบจะบังคับให้เป็นออบเจ็กต์

Object.freeze

พารามิเตอร์ ประเภท คำอธิบาย
objectInput any วัตถุที่จะหยุด หากอินพุตไม่ใช่ออบเจ็กต์ ระบบจะถือว่าอินพุตนั้นเป็นออบเจ็กต์แบบคงที่

Object.delete

พารามิเตอร์ ประเภท คำอธิบาย
objectInput any ออบเจ็กต์ที่จะลบคีย์
keyToDelete สตริง คีย์ระดับบนสุดที่จะลบ

ตัวอย่าง

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

แสดงผลออบเจ็กต์ที่มีเมธอดสำหรับการโต้ตอบกับพรอมต์

พรอมต์มีฟังก์ชันการทำงานเทียบเท่ากับพรอมต์ JavaScript อินสแตนซ์แต่ละรายการมีเมธอด 3 รายการที่แสดงผล Promise ซึ่งช่วยให้ดำเนินการต่อได้เมื่อ Promise มีผล

  • .then() - จัดการทั้งเคสที่แก้ไขแล้วและถูกปฏิเสธ โดยจะใช้การเรียกกลับ 2 รายการเป็นพารามิเตอร์ ได้แก่ 1 รายการสําหรับกรณีที่สําเร็จและ 1 รายการสําหรับกรณีที่ไม่สําเร็จ
  • .catch() - จัดการเฉพาะเคสที่ถูกปฏิเสธ ใช้ Callback 1 รายการเป็นพารามิเตอร์
  • .finally() - ระบุวิธีเรียกใช้โค้ดไม่ว่า Promise จะได้รับการแก้ไขหรือถูกปฏิเสธ ใช้ Callback 1 รายการเป็นพารามิเตอร์ที่เรียกใช้โดยไม่มีอาร์กิวเมนต์

ตัวแปรที่แสดงผลพรอมต์เท่ากับค่าที่แก้ไขแล้วของพรอมต์ หรือ false หากพรอมต์ปฏิเสธ

ตัวอย่าง

promise.then((resolvedValue) => {
    // Handles when promise resolves.
  }, (rejectedValue) => {
    // Handles when promise rejects.
  });
promise.catch((rejectedValue) => {
    // Handles when promise rejects.
  });
promise.finally(() => {
    // Runs regardless of whether or not the previous promise resolves or
    // rejects.
  });

Promise.all

แสดงผลพรอมต์ที่มีลักษณะอย่างใดอย่างหนึ่งต่อไปนี้

  • แสดงผลเมื่ออินพุตทั้งหมดได้รับการแก้ไขแล้ว หรือ
  • ปฏิเสธเมื่ออินพุตใดปฏิเสธ

ไวยากรณ์

Promise.all(inputs);

พารามิเตอร์

พารามิเตอร์ ประเภท คำอธิบาย
inputs อาร์เรย์ อาร์เรย์ของค่าหรือสัญญา หากอินพุตไม่ใช่พรอมต์ ระบบจะส่งผ่านอินพุตราวกับว่าเป็นค่าที่แก้ไขแล้วของพรอมต์ แสดงข้อผิดพลาดหากอินพุตไม่ใช่อาร์เรย์

ตัวอย่าง

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

return Promise.all(['a', sendHttpGet('https://example.com')])
  .then((results) => {
    // results will equal: ['a', {statusCode: 200, headers: {}, body: ''}]
  });

สิทธิ์ที่เชื่อมโยง

ไม่มี

Promise.create

สร้างพรอมต์ที่ทำงานเทียบเท่ากับพรอมต์ JavaScript

ไวยากรณ์

Promise.create(resolver);

พารามิเตอร์

พารามิเตอร์ ประเภท คำอธิบาย
resolver function ฟังก์ชันที่เรียกใช้ด้วยฟังก์ชัน 2 รายการ ได้แก่ resolve และ reject Promise ที่แสดงผลจะแก้ไขหรือปฏิเสธเมื่อมีการเรียกใช้พารามิเตอร์ที่เกี่ยวข้อง แสดงข้อผิดพลาดหากตัวแก้ไขไม่ใช่ฟังก์ชัน

ตัวอย่าง

const Promise = require('Promise');

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

สิทธิ์ที่เชื่อมโยง

ไม่มี

Test API

API เหล่านี้ทํางานร่วมกับการทดสอบ JavaScript ในแซนด์บ็อกซ์เพื่อสร้างการทดสอบเทมเพลตที่กําหนดเองใน Google Tag Manager API การทดสอบเหล่านี้ไม่จำเป็นต้องมีrequire() คำสั่ง [ดูข้อมูลเพิ่มเติมเกี่ยวกับการทดสอบเทมเพลตที่กำหนดเอง]

assertApi

แสดงผลออบเจ็กต์ตัวจับคู่ที่สามารถใช้เพื่อยืนยันเกี่ยวกับ API ที่ระบุได้อย่างราบรื่น

ไวยากรณ์

assertApi(apiName)

พารามิเตอร์

พารามิเตอร์ ประเภท คำอธิบาย
apiName สตริง ชื่อของ API ที่จะตรวจสอบ ซึ่งเป็นสตริงเดียวกับที่ส่งไปยัง require()

ตัวจับคู่

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

ตัวอย่าง

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

assertThat

assertThat API สร้างขึ้นตามไลบรารี [Truth] ของ Google โดยจะแสดงผลออบเจ็กต์ที่สามารถใช้เพื่อยืนยันค่าของเรื่องได้อย่างราบรื่น การทดสอบจะหยุดลงทันทีและระบุว่าไม่สําเร็จหากการยืนยันไม่สําเร็จ อย่างไรก็ตาม การทดสอบไม่ผ่านรายการหนึ่งจะไม่ส่งผลต่อเฟรมทดสอบอื่นๆ

ไวยากรณ์

assertThat(actual, opt_message)

พารามิเตอร์

พารามิเตอร์ ประเภท คำอธิบาย
actual any ค่าที่จะใช้ในการตรวจสอบความต่อเนื่อง
opt_message สตริง ข้อความที่ไม่บังคับที่จะพิมพ์หากการยืนยันไม่สำเร็จ

ตัวจับคู่

โปรแกรมจับคู่ คำอธิบาย
isUndefined() ยืนยันว่าเรื่องคือ undefined
isDefined() ยืนยันว่าเรื่องไม่ใช่ undefined
isNull() ยืนยันว่าเรื่องคือ null
isNotNull() ยืนยันว่าเรื่องไม่ใช่ null
isFalse() ยืนยันว่าเรื่องคือ false
isTrue() ยืนยันว่าเรื่องคือ true
isFalsy() ยืนยันว่าเรื่องนั้นเป็นเท็จ ค่าที่เป็นเท็จคือ undefined, null, false, NaN, 0 และ '' (สตริงว่าง)
isTruthy() ยืนยันว่าเรื่องเป็นจริง ค่าที่เป็นเท็จคือ undefined, null, false, NaN, 0 และ '' (สตริงว่าง)
isNaN() ยืนยันว่าเรื่องเป็นค่า NaN
isNotNaN() ยืนยันว่าเรื่องเป็นค่าใดก็ได้ที่ไม่ใช่ NaN
isInfinity() ยืนยันว่าเรื่องเป็นค่าบวกหรือค่าลบอนันต์
isNotInfinity() ยืนยันว่าเรื่องเป็นค่าใดก็ได้ที่ไม่ใช่บวกหรือลบ หรือ Infinity
isEqualTo(expected) ยืนยันว่าเรื่องเท่ากับค่าที่ระบุ การดำเนินการนี้เป็นการคํานวณค่า ไม่ใช่การคํานวณข้อมูลอ้างอิง ระบบจะเปรียบเทียบเนื้อหาของออบเจ็กต์และอาร์เรย์แบบซ้ำ
isNotEqualTo(expected) ยืนยันว่าเรื่องไม่เท่ากับค่าที่ระบุ นี่เป็นเปรียบเทียบค่า ไม่ใช่การเปรียบเทียบข้อมูลอ้างอิง ระบบจะเปรียบเทียบเนื้อหาของออบเจ็กต์และอาร์เรย์แบบซ้ำ
isAnyOf(...expected) ยืนยันว่าเรื่องเท่ากับค่าใดค่าหนึ่งที่กำหนด นี่เป็นเปรียบเทียบค่า ไม่ใช่การเปรียบเทียบข้อมูลอ้างอิง ระบบจะเปรียบเทียบเนื้อหาของออบเจ็กต์และอาร์เรย์แบบซ้ำ
isNoneOf(...expected) ยืนยันว่าเรื่องไม่เท่ากับค่าที่ระบุ การเปรียบเทียบนี้เป็นแบบค่า ไม่ใช่แบบการเปรียบเทียบข้อมูลอ้างอิง ระบบจะเปรียบเทียบเนื้อหาของออบเจ็กต์และอาร์เรย์แบบซ้ำ
isStrictlyEqualTo(expected) ยืนยันว่าเรื่อง (===) เท่ากับค่าที่ระบุอย่างเคร่งครัด
isNotStrictlyEqualTo(expected) ยืนยันว่าเรื่องไม่เท่ากับ (!==) ค่าที่ระบุอย่างเคร่งครัด
isGreaterThan(expected) ยืนยันว่าเรื่องมากกว่า (>) ค่าที่ระบุในการเปรียบเทียบแบบจัดเรียง
isGreaterThanOrEqualTo(expected) ยืนยันว่าเรื่องมากกว่าหรือเท่ากับ (>=) ค่าที่ระบุในการเปรียบเทียบแบบจัดลำดับ
isLessThan(expected) ยืนยันว่าเรื่องน้อยกว่า (<) ค่าที่ระบุในการเปรียบเทียบแบบเรียงลำดับ
isLessThanOrEqualTo(expected) ยืนยันว่าเรื่องมีค่าน้อยกว่าหรือเท่ากับ (<=) ค่าที่ระบุในการเปรียบเทียบแบบจัดลำดับ
contains(...expected) ยืนยันว่าเรื่องเป็นอาร์เรย์หรือสตริงที่มีค่าที่ระบุทั้งหมดตามลำดับใดก็ได้ การเปรียบเทียบนี้เป็นแบบค่า ไม่ใช่แบบข้อมูลอ้างอิง ระบบจะเปรียบเทียบเนื้อหาของออบเจ็กต์และอาร์เรย์แบบย้อนกลับ
doesNotContain(...expected) ยืนยันว่าเรื่องเป็นอาร์เรย์หรือสตริงที่ไม่มีค่าที่ระบุ การเปรียบเทียบนี้เป็นแบบค่า ไม่ใช่แบบการเปรียบเทียบข้อมูลอ้างอิง ระบบจะเปรียบเทียบเนื้อหาของออบเจ็กต์และอาร์เรย์แบบซ้ำ
containsExactly(...expected) ยืนยันว่าเรื่องเป็นอาร์เรย์ที่มีค่าที่ระบุทั้งหมดตามลำดับใดก็ได้และไม่มีค่าอื่นๆ การเปรียบเทียบนี้เป็นแบบค่า ไม่ใช่แบบการเปรียบเทียบข้อมูลอ้างอิง ระบบจะเปรียบเทียบเนื้อหาของออบเจ็กต์และอาร์เรย์แบบย้อนกลับ
doesNotContainExactly(...expected) ยืนยันว่าเรื่องเป็นอาร์เรย์ที่มีชุดค่าที่แตกต่างจากค่าที่ระบุในลำดับใดก็ได้ การเปรียบเทียบนี้เป็นแบบค่า ไม่ใช่แบบการเปรียบเทียบข้อมูลอ้างอิง ระบบจะเปรียบเทียบเนื้อหาของออบเจ็กต์และอาร์เรย์แบบซ้ำ
hasLength(expected) ยืนยันว่าเรื่องเป็นอาร์เรย์หรือสตริงที่มีความยาวที่ระบุ การยืนยันจะดำเนินการไม่สําเร็จเสมอหากค่าไม่ใช่อาร์เรย์หรือสตริง
isEmpty() ยืนยันว่าเรื่องเป็นอาร์เรย์หรือสตริงที่ว่างเปล่า (ความยาว = 0) การยืนยันจะดำเนินการไม่สําเร็จเสมอหากค่าไม่ใช่อาร์เรย์หรือสตริง
isNotEmpty() ยืนยันว่าเรื่องเป็นอาร์เรย์หรือสตริงที่ไม่ใช่สตริงว่าง (ความยาว > 0) การยืนยันจะดำเนินการไม่สำเร็จเสมอหากค่าไม่ใช่อาร์เรย์หรือสตริง
isArray() ยืนยันว่าประเภทของเรื่องเป็นอาร์เรย์
isBoolean() ยืนยันว่าประเภทของเรื่องเป็นบูลีน
isFunction() ยืนยันว่าประเภทของเรื่องคือฟังก์ชัน
isNumber() ยืนยันว่าประเภทของเรื่องเป็นตัวเลข
isObject() ยืนยันว่าประเภทของเรื่องคือออบเจ็กต์
isString() ยืนยันว่าประเภทของเรื่องคือสตริง

ตัวอย่าง

assertThat(undefined).isUndefined();
assertThat(id, 'ID must be defined').isDefined();
assertThat(null).isNull();
assertThat(undefined).isNotNull();
assertThat(true).isTrue();
assertThat(false).isFalse();
assertThat(1).isTruthy();
assertThat('').isFalsy();
assertThat(1/0).isInfinity();
assertThat(0).isNotInfinity();
assertThat(-'foo').isNaN();
assertThat(100).isNotNaN();
assertThat(sentUrl).isEqualTo('https://endpoint.example.com/?account=12345');
assertThat(category).isNotEqualTo('premium');
assertThat(5).isAnyOf(1, 2, 3, 4, 5);
assertThat(42).isNoneOf('the question', undefined, 41.9);
assertThat('value').isStrictlyEqualTo('value');
assertThat('4').isNotStrictlyEqualTo(4);
assertThat(['a', 'b', 'c']).contains('a', 'c');
assertThat(['x', 'y', 'z']).doesNotContain('f');
assertThat(['1', '2', '3']).containsExactly('3', '2', '1');
assertThat(['4', '5']).doesNotContainExactly('4');
assertThat('a string').hasLength(8);
assertThat([]).isEmpty();
assertThat('another string').isNotEmpty();

fail

ทดสอบปัจจุบันไม่สําเร็จทันทีและพิมพ์ข้อความที่ระบุไว้ (หากระบุ)

ไวยากรณ์

fail(opt_message);

พารามิเตอร์

พารามิเตอร์ ประเภท คำอธิบาย
opt_message สตริง ข้อความแสดงข้อผิดพลาดแบบไม่บังคับ

ตัวอย่าง

fail('This test has failed.');

mock

mock API ช่วยให้คุณลบล้างลักษณะการทํางานของ API ใน Sandbox ได้ Mock API ใช้งานได้อย่างปลอดภัยในโค้ดเทมเพลต แต่จะทํางานได้เฉพาะในโหมดทดสอบเท่านั้น ระบบจะรีเซ็ตการจำลองก่อนทำการทดสอบแต่ละครั้ง

ไวยากรณ์

mock(apiName, returnValue);

พารามิเตอร์

พารามิเตอร์ ประเภท คำอธิบาย
apiName สตริง ชื่อของ API ที่จะจำลอง ซึ่งจะเป็นสตริงเดียวกับที่ส่งไปยัง require()
returnValue any ค่าที่จะแสดงผลสำหรับ API หรือฟังก์ชันที่เรียกแทน API หาก returnValue เป็นฟังก์ชัน ระบบจะเรียกใช้ฟังก์ชันนั้นแทน API ที่อยู่ในแซนด์บ็อกซ์ หาก returnValue ไม่ใช่ฟังก์ชัน ระบบจะแสดงผลค่านั้นแทน API ที่อยู่ในแซนด์บ็อกซ์

ตัวอย่าง

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

mockObject

mockObject API ช่วยให้คุณลบล้างลักษณะการทํางานของ API ในแซนด์บ็อกซ์ที่แสดงผลออบเจ็กต์ API นี้ใช้งานได้อย่างปลอดภัยในโค้ดเทมเพลต แต่จะใช้งานได้ในโหมดทดสอบเท่านั้น ระบบจะรีเซ็ตการจำลองก่อนทำการทดสอบแต่ละครั้ง

ไวยากรณ์

mockObject(apiName, objectMock);

พารามิเตอร์

พารามิเตอร์ ประเภท คำอธิบาย
apiName สตริง ชื่อของ API ที่จะจำลอง ซึ่งจะเป็นสตริงเดียวกับที่ส่งไปยัง require()
objectMock object ค่าที่จะแสดงผลสำหรับ API หรือฟังก์ชันที่เรียกแทน API ต้องเป็นออบเจ็กต์

ตัวอย่าง

const storage = {};
let firestoreId = 1;

function asTestPromise(result) {
  return {
    then: (callback) => callback(result)
  };
}

mockObject('Firestore', {
  write: (collection, input) => {
    storage[collection + '/' + (++firestoreId)] = input;
    return asTestPromise(firestoreId);
  },
  read: (document) => asTestPromise({data: storage[document]})
});

runCode

เรียกใช้โค้ดของเทมเพลต ซึ่งก็คือเนื้อหาของแท็บโค้ดในสภาพแวดล้อมการทดสอบปัจจุบันด้วยออบเจ็กต์ข้อมูลอินพุตที่ระบุ

ไวยากรณ์

runCode(data)

พารามิเตอร์

พารามิเตอร์ ประเภท คำอธิบาย
data object ออบเจ็กต์ข้อมูลที่จะใช้ในการทดสอบ

ผลลัพธ์

แสดงค่าของตัวแปรสำหรับเทมเพลตตัวแปร และจะแสดง undefined สำหรับเทมเพลตประเภทอื่นๆ ทั้งหมด

ตัวอย่าง

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