ממשקי API לתיוג בצד השרת

במסמך הזה מתוארים ממשקי ה-API לתיוג בצד השרת.

addEventCallback

רושם פונקציית קריאה חוזרת שתופעל בסיום אירוע. הקריאה החוזרת תופעל אחרי שכל התגים של האירוע יופעלו. הקריאה החוזרת עוברת שני ערכים: המזהה של הקונטיינר שמפעיל את הפונקציה, ואובייקט שמכיל מידע על האירוע.

כשמשתמשים ב-API הזה בתג, הוא משויך לאירוע הנוכחי. כשמשתמשים ב-API הזה בצד לקוח, צריך לקשר אותו לאירוע ספציפי באמצעות הפונקציה bindToEvent של ה-API runContainer. מידע נוסף מופיע בדוגמה.

תחביר

const addEventCallback = require('addEventCallback');

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

פרמטרים

פרמטר סוג תיאור
callback פונקציה הפונקציה שתפעיל בסוף האירוע.

האובייקט 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 פונקציה הפונקציה שצריך להפעיל.

ההרשאות המשויכות

ללא.

claimRequest

צריך להשתמש ב-API הזה בלקוח כדי לתבוע בעלות על הבקשה. אחרי ששולחים בקשה, הקונטיינר לא מפעיל לקוחות נוספים.

ה-API הזה יקפיץ חריג אם הוא מופעל בתג או במשתנה. ה-API הזה מחריג החרגה אם נשלחת קריאה אליו אחרי שהלקוח חוזר (למשל, אם קוראים לו בקריאה חוזרת (callback) אסינכרונית, כמו ב-callLater או בפונקציה onComplete runContainer).

לפני שהלקוח קורא ל-API של runContainer, הוא צריך לתבוע בעלות על הבקשה באמצעות ה-API הזה.

דוגמה

const claimRequest = require('claimRequest');

claimRequest();

תחביר

claimRequest();

ההרשאות המשויכות

ללא.

computeEffectiveTldPlusOne

הפונקציה מחזירה את הערך האפקטיבי של הדומיין ברמה העליונה + 1 (eTLD+1) של הדומיין או כתובת ה-URL הנתונים. הדומיין eTLD+1 מחושב על ידי הערכת הדומיין ביחס לכללי רשימת הסיומות הציבוריות. eTLD+1 הוא בדרך כלל הדומיין ברמה הגבוהה ביותר שבו ניתן להגדיר קובץ cookie.

אם הארגומנט הוא 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 string דומיין או כתובת URL שבהם צריך לחשב את ה-eTLD+1.

ההרשאות המשויכות

ללא.

createRegex

יצירת מכונה של ביטוי רגולרי (regex) חדש ומחזירה אותו בתוך אובייקט. אי אפשר לגשת ישירות לביטוי הרגולרי. עם זאת, אפשר להעביר אותו ל-API של testRegex, ל-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 string הטקסט של הביטוי הרגולרי.
flags string מחרוזת אופציונלית שמכילה את הדגלים של הביטוי הרגולרי שנוצר. המערכת תומכת ב-'g' (גלובלי) וב-'i' (לא תלוי-רישיות). המערכת מתעלמת מכל שאר התווים.

ההרשאות המשויכות

ללא.

גרסת תמונה מינימלית

2.0.0

decodeUri

מפענח כל תווים מקודדים ב-URI שסופק. הפונקציה מחזירה string שמייצגת את ה-URI המפוענח. הפונקציה מחזירה את הערך undefined אם מזינים קלט לא תקין.

דוגמה

const decodeUri = require('decodeUri');

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

תחביר

decodeUri(encoded_uri);

פרמטרים

פרמטר סוג תיאור
encoded_uri string URI שמקודד על ידי encodeUri() או באמצעים אחרים.

ההרשאות המשויכות

ללא.

decodeUriComponent

מפענח כל תווים מקודדים ברכיב ה-URI שסופק. הפונקציה מחזירה string שמייצגת את רכיב ה-URI המפוענח. הפונקציה מחזירה את הערך undefined אם נותנים קלט לא חוקי.

דוגמה

const decodeUriComponent = require('decodeUriComponent');

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

תחביר

decodeUriComponent(encoded_uri_component);

פרמטרים

פרמטר סוג תיאור
encoded_uri_component string רכיב URI שעבר קידוד על ידי encodeUriComponent() או באמצעים אחרים.

ההרשאות המשויכות

ללא.

encodeUri

הפונקציה מחזירה מזהה משאב אחיד (URI) מקודד באמצעות תו בריחה (escape) של תווים מיוחדים. הפונקציה מחזירה string שמייצגת את המחרוזת שצוינה בקידוד כ-URI.

דוגמה

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

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

תחביר

encodeUri(uri);

פרמטרים

פרמטר סוג תיאור
uri string URI מלא.

ההרשאות המשויכות

ללא.

encodeUriComponent

הפונקציה מחזירה מזהה משאב אחיד (URI) מקודד באמצעות תו בריחה (escape) של תווים מיוחדים. הפונקציה מחזירה string שמייצגת את המחרוזת שסופקה ומקודדת כ-URI.

דוגמה

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

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

תחביר

encodeUriComponent(str);

פרמטרים

פרמטר סוג תיאור
str string רכיב של 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

מפענח מחרוזת בקידוד base64. הפונקציה מחזירה את הערך undefined אם הקלט לא תקין.

תחביר

fromBase64(base64EncodedString);

פרמטרים

פרמטר סוג תיאור
base64EncodedString string מחרוזת בקידוד Base64.

דוגמה

const fromBase64 = require('fromBase64');

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

ההרשאות המשויכות

ללא.

generateRandom

מחזירה number (מספר שלם) אקראי בתוך הטווח הנתון.

דוגמה

const generateRandom = require('generateRandom');

const randomValue = generateRandom(0, 10000000);

תחביר

generateRandom(min, max);

פרמטרים

פרמטר סוג תיאור
min number הערך הפוטנציאלי המינימלי של המספר השלם המוחזר (כולל).
max number הערך הפוטנציאלי המקסימלי של המספר השלם המוחזר (כולל).

ההרשאות המשויכות

ללא.

getAllEventData

מחזירה עותק של נתוני האירוע.

תחביר

getAllEventData();

ההרשאות המשויכות

read_event_data

getClientName

הפונקציה מחזירה string שמכיל את השם של הלקוח הנוכחי.

תחביר

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

מחזירה מערך שמכיל את הערכים של כל קובצי ה-cookie בעלי השם הנתון.

דוגמה

const getCookieValues = require('getCookieValues');

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

תחביר

getCookieValues(name[, noDecode]);

פרמטרים

פרמטר סוג תיאור
name string השם של קובץ ה-cookie.
noDecode boolean אם הערך שלו הוא true, הערכים של קובצי ה-cookie לא מפוענחים לפני שהם מוחזרים. ברירת המחדל היא 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 כלשהו הנתיב של המפתח, שבו רכיבי הנתיב מופרדים באמצעות נקודות. רכיבי הנתיב יכולים להיות מפתחות באובייקט או אינדקסים במערך. אם הערך keyPath אינו מחרוזת, הוא מועתק למחרוזת.

תחביר

getEventData(keyPath);

ההרשאות המשויכות

read_event_data

getGoogleAuth

הפונקציה מחזירה אובייקט הרשאה שכאשר משתמשים בו עם sendHttpGet או עם sendHttpRequest, תכלול כותרת הרשאה ל-Google Cloud APIs. ב-API הזה נעשה שימוש ב-Application Default Credentials כדי למצוא באופן אוטומטי פרטי כניסה מסביבת השרת.

דוגמה

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. צריך להגדיר את ההרשאה עם היקף מורשה אחד או יותר.

getGoogleScript

אחזור משאב מקבוצה מוגדרת מראש של סקריפטים של Google, והחזרת הבטחה עם הסקריפט והמטא-נתונים המשויכים לשמירה במטמון.

ההבטחה תתאים לאובייקט שמכיל שני מפתחות: script ו-metadata. אם הבקשה תיכשל, ההבטחה תידחה באמצעות מפתח 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 string שם הסקריפט. הסקריפטים הנתמכים הם '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 אובייקט אפשרויות בקשה אופציונליות. בהמשך מפורטות האפשרויות הנתמכות.

אפשרויות

אפשרות סוג תיאור
id string רלוונטי ל-'GTAG' עם מזהה המדידה gtag ו-'GTM' עם מזהה מאגר התגים באינטרנט (לדוגמה: GTM-XXXX).
debug כלשהו אם truthy, היא מבקשת ומחזירה את גרסת ניפוי הבאגים של סקריפט המדידה.
timeout number הזמן הקצוב לתפוגה של הבקשה באלפיות השנייה. המערכת מתעלמת מערכים לא חיוביים. אם הזמן הקצוב של הבקשה פג, הקריאה החוזרת תופעל עם undefined לערך הסקריפט ו-{} לאובייקט המטא-נתונים.

המערכת מתעלמת ממפתחות אפשרויות לא מזוהים.

ההרשאות המשויכות

נדרשת ההרשאה send_http. צריך להגדיר את ההרשאה באופן שיאפשר גישה לפחות לכל:

  • מתן הרשאה ל-Google Domains

getRemoteAddress

הפונקציה מחזירה ייצוג string של כתובת ה-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

הפונקציה מחזירה את גוף הבקשה כ-string, אם יש כזו, או undefined אחרת.

תחביר

getRequestBody();

ההרשאות המשויכות

read_request

getRequestHeader

הפונקציה מחזירה את הערך של כותרת הבקשה בעלת השם כ-string, אם קיימת. אחרת, היא undefined. אם הכותרת חוזרת על עצמה, הערכים המוחזרים מצורפים יחד עם ', '.

דוגמה

const getRequestHeader = require('getRequestHeader');

const host = getRequestHeader('host');

תחביר

getRequestHeader(headerName);

פרמטרים

פרמטר סוג תיאור
headerName string שם הכותרת. הערך הזה לא תלוי רישיות.

ההרשאות המשויכות

read_request

getRequestMethod

הפונקציה מחזירה את שיטת הבקשה, למשל 'GET' או 'POST', כ-string.

דוגמה

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

הפונקציה מחזירה את הערך המפוענח של הפרמטר בעל השם של מחרוזת השאילתה כ-string, או undefined אם הפרמטר לא נמצא. אם הפרמטר חוזר על עצמו במחרוזת השאילתה, מוחזר הערך הראשון שמופיע במחרוזת השאילתה.

דוגמה

const getRequestQueryParameter = require('getRequestQueryParameter');

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

תחביר

getRequestQueryParameter(name);

פרמטרים

פרמטר סוג תיאור
name string שם הפרמטר של השאילתה.

ההרשאות המשויכות

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.

הפונקציה מחזירה number שמייצג את הזמן הנוכחי באלפיות השנייה מאז פרק הזמן של יוניקס (Unix epoch) ומחזירה באמצעות Date.now().

תחביר

getTimestamp();

ההרשאות המשויכות

ללא.

getTimestampMillis

הפונקציה מחזירה number שמייצג את הזמן הנוכחי באלפיות השנייה מאז פרק הזמן של יוניקס (Unix epoch) ומחזירה באמצעות Date.now().

תחביר

getTimestampMillis();

ההרשאות המשויכות

ללא.

getType

מחזירה מחרוזת שמתארת את סוג הערך הנתון.

סוג הקלט הערך המוחזר
string 'string'
number 'number'
boolean '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 כלשהו ערך הקלט.

ההרשאות המשויכות

ללא.

hmacSha256

מחשבת חתימה מקודדת באמצעות קוד אימות הודעות מבוסס גיבוב (HMAC) עם SHA-256. ברירת המחדל היא קידוד base64url.

כדי להשתמש ב-API הזה, צריך להגדיר את משתנה הסביבה SGTM_CREDENTIALS בשרת לנתיב של קובץ מפתח JSON בקידוד UTF-8, בפורמט הבא:

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

הערכים הם מפתחות HMAC בקידוד base64.

דוגמה

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 string הנתונים לחישוב ערך ה-HMAC.
keyId string מזהה מפתח מקובץ מפתח ה-JSON שמפנה למפתח שבו צריך להשתמש.
options אובייקט הגדרה אופציונלית של ה-API. (ראו אפשרויות בהמשך).

אפשרויות

אפשרות סוג תיאור
outputEncoding string מציינת את פורמט הקידוד של הערך המוחזר. הפורמטים הנתמכים הם 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. ב-Logs Explorer, מריצים את השאילתה logName =~ "stdout" כדי לראות את רשומות היומן שנוצרו על ידי ה-API הזה.

דוגמה

const logToConsole = require('logToConsole');

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

תחביר

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

פרמטרים

ה-API לוקח ארגומנט אחד או יותר, וכל אחד מהם מומר למחרוזת, אם יש צורך, ונרשם במסוף.

ההרשאות המשויכות

logging

makeInteger

ממירה את הערך הנתון ל-number (שלם).

תחביר

makeInteger(value);

פרמטרים

פרמטר סוג תיאור
value כל סוג הערך להמרה.

ההרשאות המשויכות

ללא.

makeNumber

ממירה את הערך הנתון ל-number.

תחביר

makeNumber(value);

פרמטרים

פרמטר סוג תיאור
value כל סוג הערך להמרה.

ההרשאות המשויכות

ללא.

makeString

מחזירה את הערך הנתון כ-string.

תחביר

makeString(value);

פרמטרים

פרמטר סוג תיאור
value כל סוג הערך להמרה.

ההרשאות המשויכות

ללא.

makeTableMap

הפונקציה ממירה אובייקט פשוט בטבלה עם שתי עמודות ל-Map. כך אפשר לשנות שדה בתבנית SIMPLE_TABLE שיש בו שתי עמודות לפורמט שניתן לנהל יותר.

לדוגמה, הפונקציה הזו יכולה להמיר אובייקט בטבלה:

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

למפה:

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

מחזירה אובייקט: ה-Map המומר של צמדי מפתח-ערך נוספו אליו, או null אחרת.

תחביר

makeTableMap(tableObj, keyColumnName, valueColumnName);

פרמטרים

פרמטר סוג תיאור
tableObj רשימה אובייקט הטבלה להמרה. זו רשימה של מפות שבהן כל Map מייצג שורה בטבלה. כל שם מאפיין באובייקט שורה הוא שם העמודה, וערך המאפיין הוא ערך העמודה בשורה.
keyColumnName string שם העמודה שהערכים שלה יהפכו למפתחות של Map שהומר.
valueColumnName string שם העמודה שהערכים שלה יהפכו לערכים של 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 string כתובת ה-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 אובייקט הפרמטרים של האירוע.
onComplete פונקציה קריאה חוזרת שמופעלת לאחר שכל התגים מסיימים לפעול.
onStart פונקציה קריאה חוזרת (callback) מופעלת באופן מיידי, לפני שהתגים מתחילים לפעול.

ההרשאות המשויכות

run_container

sendEventToGoogleAnalytics

שולחת אירוע יחיד באמצעות נתוני אירועים נפוצים ל-Google Analytics, ומחזירה הבטחה שמפנה לאובייקט עם מפתח location או דוחה לאובייקט עם מפתח reason. היעד, Universal Analytics או Google Analytics 4, מבוסס על מזהה המדידה בנתוני האירוע.

השדה location מוגדר לכותרת location, אם יש כזו.

דוגמה

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();
}, (err) => {
  setResponseStatus(500);
  data.gtmOnFailure();
});

תחביר

sendEventToGoogleAnalytics(event);

פרמטרים

פרמטר סוג תיאור
event אובייקט האירוע בפורמט סכימה מאוחדת.

ההרשאות המשויכות

נדרשת ההרשאה send_http. צריך להגדיר את ההרשאה באופן שיאפשר גישה לפחות לכל:

  • מתן הרשאה ל-Google Domains

sendHttpGet

שולחת בקשת HTTP GET לכתובת ה-URL שצוינה ומחזירה הבטחה, שמסתיימת בתוצאה של הבקשה כשהבקשה מסתיימת או נגמר הזמן הקצוב.

התוצאה שטופלה היא אובייקט שמכיל שלושה מפתחות: statusCode, headers ו-body. אם הבקשה נכשלה (למשל כתובת URL לא תקינה, אין נתיב למארח, כשל במשא ומתן מסוג SSL וכו'), ההבטחה תידחה עם: {reason: 'failed'}. אם האפשרות timeout מוגדרת ונגמר הזמן הקצוב לבקשה, ההבטחה תידחה עם הערך: {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 string כתובת ה-URL המבוקשת.
options אובייקט אפשרויות אופציונליות לבקשות. (ראו אפשרויות בהמשך).

אפשרויות

אפשרות סוג תיאור
headers string כותרות נוספות לבקשות.
timeout number הזמן הקצוב לתפוגה (באלפיות שנייה) לפני ביטול הבקשה. ברירת המחדל היא 15000.
authorization אובייקט אובייקט הרשאה אופציונלי מהקריאה ל-getGoogleAuth כדי לכלול כותרות הרשאות כששולחים בקשות ל-googleapis.com.

ההרשאות המשויכות

send_http

sendHttpRequest

שולחת בקשת HTTP לכתובת ה-URL שצוינה ומחזירה הבטחה, שנפתרת עם התשובה לאחר השלמת הבקשה או תום הזמן הקצוב לתפוגה.

התוצאה שטופלה היא אובייקט שמכיל שלושה מפתחות: statusCode, headers ו-body. אם הבקשה נכשלה (למשל כתובת URL לא תקינה, אין נתיב למארח, כשל במשא ומתן מסוג SSL וכו'), ההבטחה תידחה עם: {reason: 'failed'}. אם האפשרות timeout מוגדרת ונגמר הזמן הקצוב לבקשה, ההבטחה תידחה עם הערך: {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 string כתובת ה-URL המבוקשת.
options אובייקט אפשרויות אופציונליות לבקשות. (ראו אפשרויות בהמשך).
body string גוף הבקשה אופציונלי.

אפשרויות

אפשרות סוג תיאור
headers string כותרות נוספות לבקשות.
method אובייקט שיטת הבקשה. ברירת המחדל היא GET.
timeout number הזמן הקצוב לתפוגה (באלפיות שנייה) לפני ביטול הבקשה. ברירת המחדל היא 15000.
authorization אובייקט אובייקט הרשאה אופציונלי מהקריאה ל-getGoogleAuth כדי לכלול כותרות הרשאות כששולחים בקשות ל-googleapis.com.

ההרשאות המשויכות

send_http

sendPixelFromBrowser

שולחת פקודה לדפדפן כדי לטעון את כתובת ה-URL שסופקה כתג <img>. פרוטוקול הפקודה הזה נתמך ב-Google Tag בתגי האינטרנט של GA4 ו-Google Analytics: GA Event. צריך להגדיר את כתובת ה-URL של מאגר התגים בצד השרת. פרטים נוספים זמינים בהוראות.

ה-API הזה מחזיר את הערך false אם הבקשה הנכנסת לא תומכת בפרוטוקול הפקודה, או אם התגובה כבר התאפסה. אחרת, ה-API הזה מחזיר את הערך true.

דוגמה:

const sendPixelFromBrowser = require('sendPixelFromBrowser');

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

תחביר

sendPixelFromBrowser(url)

פרמטרים

פרמטר סוג תיאור
url string כתובת ה-URL שצריך לשלוח לדפדפן.

ההרשאות המשויכות

send_pixel_from_browser

setCookie

מגדיר או מוחק קובץ cookie עם האפשרויות שצוינו.

כדי למחוק קובץ cookie, צריך להגדיר קובץ cookie עם אותו נתיב ואותו דומיין שבאמצעותם קובץ ה-cookie נוצר, ולהקצות לו ערך שפג תוקפו בעבר, למשל "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 string שם קובץ ה-cookie. השם לא תלוי-רישיות.
value string הערך של קובץ ה-cookie
options אובייקט מאפיינים אופציונליים של קובצי Cookie:domain, expires, fallbackDomain, httpOnly, max- גיל, path, secure ו-sameSite. (ראו אפשרויות בהמשך).
noEncode boolean אם הערך הוא True, הערך של קובץ ה-cookie לא יקודד. ברירת המחדל היא false.

  • domain: המארח שאליו קובץ ה-cookie יישלח. אם מוגדר הערך המיוחד 'auto', המארח יחושב באופן אוטומטי באמצעות האסטרטגיה הבאה:

    • eTLD+1 של הכותרת Forwarded, אם קיימת.
    • eTLD+1 של הכותרת X-Forwarded-Host, אם קיימת.
    • הכותרת eTLD+1 מתוך Host.

  • expires: משך החיים המקסימלי של קובץ ה-cookie. התאריך הזה חייב להיות בפורמט UTC, למשל: "Sat, 26 Oct 1985 08:21:00 GMT". אם מוגדרות גם expires וגם max-age, יש קדימות ל-max-age.

  • httpOnly: מונע מ-JavaScript לגשת לקובץ ה-cookie אם true.

  • max-age: מספר השניות עד שפג התוקף של קובץ ה-cookie. אם הערך של מספר אפס או מספר שלילי, קובץ ה-cookie יפוג באופן מיידי. אם מגדירים גם expires וגם max-age, יש קדימות ל-max-age.

  • path: נתיב שחייב להופיע בכתובת ה-URL המבוקשת, אחרת הדפדפן לא ישלח את הכותרת של קובץ ה-Cookie.

  • secure: אם מוגדר הערך true, קובץ ה-Cookie נשלח לשרת רק כשבקשה נשלחת מנקודת קצה (endpoint) https:.

  • sameSite: הצהרה שאסור לשלוח קובץ cookie עם בקשות ממקורות שונים. חייב להיות 'strict', 'lax' או 'none'.

ההרשאות המשויכות

set_cookie

setPixelResponse

הגדרה של גוף התגובה ל-GIF ביחס 1x1, הגדרת הכותרת Content-Type כ-'image/gif', הגדרת כותרות לשמירה במטמון כך שסוכני משתמשים לא ישמרו את התגובה במטמון ומגדירה את סטטוס התשובה ל-200.

שימו לב שצריך להפעיל את returnResponse כדי שהתגובה תישלח חזרה ללקוח.

תחביר

setPixelResponse();

ההרשאות המשויכות

נדרשת ההרשאה access_response. צריך להגדיר את ההרשאה כדי לאפשר גישה לפחות לפריטים הבאים:

  • headers – חובה לאשר את המפתחות הבאים
    • content-type
    • cache-control
    • expires
    • pragma
  • body
  • status

setResponseBody

מגדיר את גוף התשובה לארגומנט.

שימו לב שצריך להפעיל את returnResponse כדי שהתגובה תישלח חזרה ללקוח.

תחביר

setResponseBody(body[, encoding]);

פרמטרים

פרמטר סוג תיאור
body string הערך שיש להגדיר כגוף התגובה.
encoding string קידוד התווים של גוף התשובה (ברירת המחדל היא 'utf8'). הערכים הנתמכים כוללים את 'ascii', 'utf8', 'utf16le', 'ucs2', 'base64', 'latin1', 'binary' ו-'hex'.

ההרשאות המשויכות

נדרשת ההרשאה access_response. צריך להגדיר את ההרשאה כדי לאפשר גישה לפחות לפריטים הבאים:

  • body

setResponseHeader

מגדיר כותרת בתשובה שתוחזר. אם כותרת עם השם הזה (לא תלוי-רישיות) הוגדרה בעבר על ידי ה-API הזה, הקריאה השנייה תחליף או תמחק את הערך שהוגדר על ידי הקריאה הקודמת.

שימו לב שצריך להפעיל את returnResponse כדי שהתגובה תישלח חזרה ללקוח.

תחביר

setResponseHeader(name, value);

פרמטרים

פרמטר סוג תיאור
name string שם הכותרת. שמות כותרות ה-HTTP לא תלויי-רישיות, ולכן שם הכותרת יהיה באותיות קטנות.
value מחרוזת undefined ערך הכותרת. אם הערך הוא null או לא מוגדר, הפעולה הזו מנקה את הכותרת בעלת השם מהתשובה שתוחזר.

ההרשאות המשויכות

נדרשת ההרשאה access_response. צריך להגדיר את ההרשאה כדי לאפשר גישה לפחות לפריטים הבאים:

  • headers

setResponseStatus

מגדיר את קוד הסטטוס של ה-HTTP של התגובה שתוחזר.

שימו לב שצריך להפעיל את returnResponse כדי שהתגובה תישלח חזרה ללקוח.

תחביר

setResponseStatus(statusCode);

פרמטרים

פרמטר סוג תיאור
statusCode number קוד מצב ה-HTTP שיש להחזיר.

ההרשאות המשויכות

נדרשת ההרשאה access_response. צריך להגדיר את ההרשאה כדי לאפשר גישה לפחות לפריטים הבאים:

  • status

sha256

הפונקציה מחשבת את תקציר SHA-256 של הקלט ומפעילים קריאה חוזרת עם תקציר בקידוד base64, אלא אם האובייקט options מציין קידוד פלט שונה.

החתימה וההתנהגות האלה של ה-API תואמים ל-API של sha256 לקונטיינרים של אינטרנט. עם זאת, בתבניות מותאמות אישית בקונטיינרים של השרת צריך להשתמש ב-API sha256Sync לקוד פשוט יותר.

דוגמה

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 string המחרוזת שיש לגבב.
onSuccess פונקציה מופעל עם התקציר שנוצר, מקודד ב-base64, אלא אם האובייקט options מציין קידוד פלט שונה.
options אובייקט אובייקט אופציונלי שמציין את קידוד הפלט. אם צוין, האובייקט צריך להכיל את המפתח outputEncoding עם הערך אחד מ-base64 או hex.

ההרשאות המשויכות

ללא.

sha256Sync

הפונקציה מחשבת ומחזירה את תקציר SHA-256 של הקלט, שמקודד ב-base64, אלא אם האובייקט 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 string המחרוזת שיש לגבב.
options אובייקט אובייקט אופציונלי שמציין את קידוד הפלט. אם צוין, האובייקט צריך להכיל את המפתח 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

בדיקת מחרוזת מול ביטוי רגולרי שנוצר באמצעות API של createRegex. הפונקציה מחזירה את הערך true אם הביטוי הרגולרי תואם. הפונקציה מחזירה את הערך false אחרת.

ביטוי רגולרי שנוצר עם הדגל הגלובלי ניתן לשמור על מצב. פרטים נוספים זמינים במסמכי העזרה של 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 string מחרוזת בדיקה לבדיקה.

ההרשאות המשויכות

ללא.

toBase64

הפונקציה מקודדת מחרוזת כ-base64 או כ-base64url. ברירת המחדל היא קידוד base64.

תחביר

toBase64(input, options);

פרמטרים

פרמטר סוג תיאור
input string המחרוזת לקידוד.
options אובייקט הגדרה אופציונלית של ה-API. (ראו אפשרויות בהמשך).

אפשרויות

אפשרות סוג תיאור גירסת מינימום
urlEncoding boolean אם הערך הוא True, התוצאה תקודד באמצעות הפורמט 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 אובייקט מגדיר את המידע הנדרש כדי להתחבר לטבלה ב-BigQuery. יש פרמטר אופציונלי אחד ושני פרמטרים נדרשים:
  • 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 אובייקט אפשרויות בקשה אופציונליות. האפשרויות הנתמכות הן: ignoreUnknownValues ו-skipINVALIDRows. המערכת מתעלמת ממפתחות של אפשרויות לא מוכרים. (ראו אפשרויות בהמשך).

פרמטר סוג תיאור
ignoreUnknownValues boolean אם הערך שמוגדר הוא true, צריך לאשר את השורות שמכילות ערכים שלא תואמים לסכימה. המערכת מתעלמת מהערכים הלא ידועים. ברירת המחדל היא false.
skipInvalidRows boolean אם היא מוגדרת לערך true, צריך להוסיף את כל השורות החוקיות של הבקשה, גם אם קיימות שורות לא תקינות. ברירת המחדל היא false.

דוגמאות לשגיאות

אם השגיאה "המודול לא נמצא", סביר להניח שבקונטיינר של השרת פועלת גרסה ישנה יותר של התמונה שלנו, שעדיין לא כללה את מודול BigQuery. צריך לפרוס מחדש את מאגר התגים בצד השרת עם אותן ההגדרות באמצעות סקריפט הפריסה. המודול ייכלל באופן אוטומטי כאשר הפעולה תסתיים.

בדרך כלל, שגיאת אי-הכנסה כוללת אובייקט שגיאה אחד עם מפתח reason:

[{reason: 'invalid'}]

שגיאת הוספה יכולה להכיל מספר אובייקטי שגיאה עם מערך errors ואובייקט row. הדוגמה הבאה היא לתגובת שגיאה מהוספת שתי שורות שבהן יש שגיאה רק בשורה אחת:

[
  {
    "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 במצב Native ולא ב-Firestore במצב Datastore. בנוסף, ה-API תומך רק בשימוש במסד הנתונים שמוגדר כברירת מחדל.

Firestore.read

הפונקציה Firestore.read קוראת נתונים ממסמך Firestore ומחזירה הבטחה שמפנה לאובייקט שמכיל שני מפתחות: id ו-data. אם המסמך לא קיים, ההבטחה נדחית באמצעות אובייקט שמכיל מפתח reason שווה ל-not_found.

תחביר

Firestore.read(path[, options]);

פרמטר סוג תיאור
path string הנתיב למסמך או לאוסף. הערך לא יכול להתחיל או להסתיים ב-'/'.
options אובייקט Optional request options. The supported options are: projectId, disableCache, and transaction. Unknown option keys are ignored. (See Options, below.)

פרמטר סוג תיאור
projectId string אופציונלי. מזהה הפרויקט ב-Google Cloud Platform. אם לא מזינים את הערך, projectId מאוחזר ממשתנה הסביבה GOOGLE_CLOUD_PROJECT כל עוד הגדרת ההרשאה access_firestore של מזהה הפרויקט מוגדרת ל-* או ל-GOOGLE_CLOUD_PROJECT. אם הקונטיינר של השרת פועל ב-Google Cloud, כבר מוגדר הערך GOOGLE_CLOUD_PROJECT למזהה הפרויקט ב-Google Cloud.
disableCache boolean אופציונלי. המדיניות קובעת אם להשבית את המטמון או לא. השמירה במטמון מופעלת כברירת מחדל, והתוצאה תישמר במטמון למשך הבקשה.
transaction string אופציונלי. הערך שאוחזר מ-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 string הנתיב למסמך או לאוסף. הערך לא יכול להתחיל או להסתיים ב-'/'.
input אובייקט הערך שיש לכתוב במסמך. אם אפשרות המיזוג מוגדרת, ה-API ימזג את המפתחות מהקלט עם המסמך.
options אובייקט אפשרויות אופציונליות לבקשות. האפשרויות הנתמכות הן: projectId, Merge ו-transaction. המערכת מתעלמת ממפתחות של אפשרויות לא מוכרים. (ראו אפשרויות בהמשך).

פרמטר סוג תיאור
projectId string אופציונלי. מזהה הפרויקט ב-Google Cloud Platform. אם לא מזינים את הערך, projectId מאוחזר ממשתנה הסביבה GOOGLE_CLOUD_PROJECT כל עוד הגדרת ההרשאה access_firestore של מזהה הפרויקט מוגדרת ל-* או ל-GOOGLE_CLOUD_PROJECT. אם הקונטיינר של השרת פועל ב-Google Cloud, כבר מוגדר הערך GOOGLE_CLOUD_PROJECT למזהה הפרויקט ב-Google Cloud.
merge boolean אופציונלי. אם המדיניות מוגדרת לערך true, ממזגים את המפתחות מהקלט עם המסמך, אחרת השיטה תבטל את המסמך כולו. ברירת המחדל היא false.
transaction string אופציונלי. הערך שאוחזר מ-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 מפעילה שאילתה על האוסף הנתון ומחזירה הבטחה, שתואמת למערך מסמכי Firestore שתואמים לתנאי השאילתה. אובייקט המסמך של Firestore זהה לזה שצוין למעלה ב-Firestore.read. אם אין מסמכים שתואמים לתנאי השאילתה, ההבטחה שתוחזר תטופל למערך ריק.

תחביר

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

פרמטר סוג תיאור
collection string הנתיב לאוסף. הערך לא יכול להתחיל או להסתיים ב-'/'.
queryConditions מערך מערך תנאים של שאילתות. כל שאילתה מופיעה כמערך עם שלושה ערכים: key, operator ו-expectedValue. E.g.: [[‘id’, ‘<’, ‘5’], [‘state’, ‘==’, ‘CA’]].

מוסיפים את התנאים באמצעות AND כדי ליצור את תוצאת השאילתה. לרשימת האופרטורים התואמים של השאילתות אפשר לעיין ב אופרטורים של Firestore.
options אובייקט אפשרויות אופציונליות לבקשות. האפשרויות הנתמכות הן: projectId, disableCache, limit ו-transaction. המערכת מתעלמת ממפתחות של אפשרויות לא מוכרים. (ראו אפשרויות בהמשך).

פרמטר סוג תיאור
projectId string אופציונלי. מזהה הפרויקט ב-Google Cloud Platform. אם לא מזינים את הערך, projectId מאוחזר ממשתנה הסביבה GOOGLE_CLOUD_PROJECT כל עוד הגדרת ההרשאה access_firestore של מזהה הפרויקט מוגדרת ל-* או ל-GOOGLE_CLOUD_PROJECT. אם הקונטיינר של השרת פועל ב-Google Cloud, כבר מוגדר הערך GOOGLE_CLOUD_PROJECT למזהה הפרויקט ב-Google Cloud.
disableCache boolean אופציונלי. המדיניות קובעת אם להשבית את המטמון או לא. השמירה במטמון מופעלת כברירת מחדל, והתוצאה תישמר במטמון למשך הבקשה.
limit number אופציונלי. שינוי מספר התוצאות המקסימלי שהשאילתה מחזירה, וברירת המחדל שלו היא 5.
transaction string אופציונלי. הערך שאוחזר מ-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. במקרה של כתיבה בו-זמנית או מחלוקת עם עסקה אחרת, יתבצע ניסיון חוזר של העסקה עד פעמיים. אם הניסיון נכשל אחרי שלושה ניסיונות סה"כ, ה-API ידחה עם שגיאה. ה-API הזה מחזיר הבטחה שעונה למערך של מזהי מסמכים, לכל פעולת כתיבה, אם הטרנזקציה מוצלחת, ותידחה עם השגיאה אם היא תיכשל.

תחביר

Firestore.runTransaction(callback[, options]);

פרמטרים

פרמטר סוג תיאור
callback פונקציה קריאה חוזרת (callback) שמופעלת עם מזהה עסקה במחרוזת. אפשר להעביר את מזהה הטרנזקציה לקריאות ל-API לקריאה/כתיבה/שאילתה. פונקציית הקריאה החוזרת חייבת להחזיר הבטחה. הקריאה החוזרת עשויה לפעול עד שלוש פעמים לפני שהיא תיכשל.
options אובייקט אפשרויות אופציונליות לבקשות. האפשרות היחידה שנתמכת היא projectId. המערכת מתעלמת ממפתחות של אפשרויות לא מוכרים. (ראו אפשרויות בהמשך).

פרמטר סוג תיאור
projectId string אופציונלי. מזהה הפרויקט ב-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.
  }
});

סיבות השגיאה יכולות לכלול, בין היתר, את קודי השגיאה של API ל-REST ב-Firestore.

ההרשאות המשויכות

access_firestore

JSON

מחזירה אובייקט שמספק פונקציות JSON.

הפונקציה parse() מנתחת מחרוזת JSON כדי ליצור את הערך או האובייקט שמתוארים במחרוזת. אם אי אפשר לנתח את הערך (למשל, פורמט JSON שגוי), הפונקציה תחזיר את הערך undefined. אם ערך הקלט הוא לא מחרוזת, הקלט ייאכף למחרוזת.

הפונקציה stringify() ממירה את הקלט למחרוזת JSON. אם אי אפשר לנתח את הערך (למשל לאובייקט יש מחזור), ה-method תחזיר את הערך 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

הפונקציה מוסיפה פונקציה שמאזינים להודעה מסוג מסוים. כשהודעה מהסוג הזה נשלחת באמצעות API של sendMessage (בדרך כלל באמצעות תג), הקריאה החוזרת תפעל באופן סינכרוני. הקריאה החוזרת פועלת עם שני פרמטרים:

  1. messageType:string
  2. message:Object

אם הקריאה החוזרת (callback) מתווספת בלקוח, היא תקבל הודעות לגבי כל האירועים שהלקוח יצר. אם הקריאה החוזרת צריכה לקבל הודעות רק מאירוע מסוים, צריך לקשר את ה-API הזה לאירוע באמצעות bindToEvent בפונקציה onStart של ה-API של runContainer. דוגמה:

תחביר

const addMessageListener = require('addMessageListener');

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

פרמטרים

פרמטר סוג תיאור
messageType string סוג ההודעה להאזנה. אם הערך אינו מחרוזת, הוא יאופס למחרוזת.
callback פונקציה הקריאה החוזרת (callback) שתרוץ כשתישלח הודעה מסוג ההודעה הרלוונטי. אם הקריאה החוזרת היא לא פונקציה, ה-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

הפונקציה מחזירה true אם נוסף מאזינים להודעה מסוג ההודעה הנתון. הפונקציה מחזירה את הערך False, אחרת.

תחביר

const hasMessageListener = require('hasMessageListener');

hasMessageListener('send_pixel');

ההרשאות המשויכות

ללא.

sendMessage

שליחת הודעה מהסוג שצוין למאזינים רשומים. אפשר להשתמש כך כדי לשלוח הודעות מתג חזרה ללקוח שהריץ את הקונטיינר.

Syntax

const sendMessage = require('sendMessage');

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

פרמטרים

פרמטר סוג תיאור
messageType string סוג ההודעה שצריך לשלוח. אם הערך אינו מחרוזת, הוא יאופס למחרוזת.
message אובייקט ההודעה שצריך לשלוח. אם ההודעה היא לא אובייקט, ה-API לא יבצע כל פעולה.

ההרשאות המשויכות

נדרשת ההרשאה use_message. צריך להגדיר את ההרשאה כך שתאפשר לפחות:

  • סוג הודעה עם Usage מתוך listen_and_send או send.

Object

מחזירה אובייקט שמספק Object methods.

ה-method keys() מספקת את ההתנהגות של Object.keys() בספרייה הרגילה. היא מחזירה מערך של שמות המאפיינים המספורים של אובייקט מסוים, באותו סדר כמו לולאה של for...in.... אם ערך הקלט הוא לא אובייקט, הוא ייאכף לאובייקט.

ה-method values() מספקת את ההתנהגות של Object.values() בספרייה הרגילה. היא מחזירה מערך של ערכי המאפיינים המספורים של אובייקט מסוים, באותו סדר כמו לולאה של for...in.... אם ערך הקלט הוא לא אובייקט, הוא יאופס לאובייקט.

ה-method entries() מספקת את ההתנהגות של Object.entries() בספרייה הרגילה. היא מחזירה מערך של צמדים של המאפיין [key, value], המחושב על ידי אובייקט מסוים, באותו סדר כמו לולאה של for...in.... אם ערך הקלט הוא לא אובייקט, הוא ייאכף לאובייקט.

ה-method freeze() מספקת את ההתנהגות של Object.freeze() בספרייה הרגילה. אי אפשר לשנות אובייקט שהוקפא. ההקפאה של אובייקט מונעת הוספה של מאפיינים חדשים, הסרה של מאפיינים קיימים ושינוי הערכים של מאפיינים קיימים. freeze() מחזיר את אותו אובייקט שהועבר. המערכת תתייחס לארגומנט ראשוני או לארגומנט null כאילו היה אובייקט קפוא, ויוחזר.

ה-method delete() מספקת את התנהגות אופרטור המחיקה של הספרייה הרגילה. היא מסירה את המפתח הנתון מהאובייקט, אלא אם הוא מוקפא. בדומה לאופרטור המחיקה של ספרייה רגילה, היא מחזירה true אם ערך הקלט הראשון (objectInput) הוא אובייקט שלא הוקפא גם אם ערך הקלט השני (keyToDelete) מציין מפתח שלא קיים. בכל שאר המקרים, הפונקציה תחזיר את הערך false. עם זאת, הוא שונה מאופרטור המחיקה של 'ספרייה רגילה' בדרכים הבאות:

  • הערך keyToDelete לא יכול להיות מחרוזת מופרדת באמצעות נקודות שמציין מפתח מקונן.
  • אי אפשר להשתמש ב-delete() כדי להסיר רכיבים ממערך.
  • לא ניתן להשתמש ב-delete() כדי להסיר נכסים מההיקף הגלובלי.

תחביר

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

פרמטרים

Object.keys

פרמטר סוג תיאור
objectInput כלשהו האובייקט שהמפתחות שלו לספירה. אם הקלט הוא לא אובייקט, הוא ייאכף לאובייקט.

Object.values

פרמטר סוג תיאור
objectInput כלשהו האובייקט שאת הערכים שלו לספירה. אם הקלט הוא לא אובייקט, הוא ייאכף לאובייקט.

Object.entries

פרמטר סוג תיאור
objectInput כלשהו האובייקט שיש לספור צמדי מפתח/ערך שלו. אם הקלט הוא לא אובייקט, הוא ייאכף לאובייקט.

Object.freeze

פרמטר סוג תיאור
objectInput כלשהו האובייקט להקפיא. אם הקלט אינו אובייקט, הוא יטופל כאובייקט שהוקפא.

Object.delete

פרמטר סוג תיאור
objectInput כלשהו האובייקט שאת המפתח שלו צריך למחוק.
keyToDelete string המפתח ברמה העליונה למחיקה.

דוגמה

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. בכל מכונה יש שלוש שיטות שמחזירות הבטחה, וכך אפשר לבצע פעולה נוספת כשההבטחה מופיעה:

  • .then() - מטפל גם בבקשות שנפתרו וגם בבקשות שנדחו. נדרשות שתי קריאות חוזרות (callback) כפרמטרים: אחת למקרה הצלחה ואחת למקרה של כשל.
  • .catch() – טיפול רק במקרים שנדחו. מקבל קריאה חוזרת (callback) אחד כפרמטר.
  • .finally() – מאפשרת להריץ את הקוד בלי שההבטחה טופלה או נדחתה. הפונקציה מקבלת קריאה חוזרת אחת כפרמטר שמופעל ללא ארגומנט.

משתנה שמחזיר הבטחה זהה לערך שלגביו התקבלה ההבטחה, או 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 פונקציה פונקציה שמופעלת באמצעות שתי פונקציות – פתרון ודחייה. ההבטחה שהוחזרה תיפתר או תידחה כאשר הפרמטר התואם יופעל. מקפיצה שגיאה אם המקודד אינו פונקציה.

דוגמה

const Promise = require('Promise');

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

ההרשאות המשויכות

ללא.

ממשקי API לבדיקה

ממשקי ה-API האלה פועלים עם בדיקות JavaScript בארגז חול כדי לבנות בדיקות לתבניות מותאמות אישית ב-Google Tag Manager. ממשקי ה-API האלה לבדיקה לא צריכים הצהרת require(). [מידע נוסף על בדיקות של תבניות בהתאמה אישית].

assertApi

הפונקציה מחזירה אובייקט תואם שיכול לשמש לשליחת טענות נכונות (assertions) באופן שוטף לגבי ה-API הנתון.

תחביר

assertApi(apiName)

פרמטרים

פרמטר סוג תיאור
apiName string שם ה-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

המודל של API assertThat מבוסס על ספריית [Truth] של Google. היא מחזירה אובייקט שיכול לשמש לטעינת טענות נכונות (assertions) באופן שוטף על ערך של נושא. שגיאה של טענת נכוֹנוּת (assertion) תפסיק באופן מיידי את הבדיקה ותסמן אותה כנכשלה. עם זאת, כשל בבדיקה אחת לא ישפיע על מקרי בדיקה אחרים.

תחביר

assertThat(actual, opt_message)

פרמטרים

פרמטר סוג תיאור
actual כלשהו הערך שצריך להשתמש בו בבדיקות השוטפות.
opt_message string הודעה אופציונלית להדפסה אם טענת הנכוֹנוּת (assertion) נכשלת.

התאמות

תואם תיאור
isUndefined() מצהיר/ה שהנושא הוא undefined.
isDefined() מצהיר/ה שהנושא אינו undefined.
isNull() מצהיר/ה שהנושא הוא null.
isNotNull() מצהיר/ה שהנושא אינו null.
isFalse() מצהיר/ה שהנושא הוא false.
isTrue() מצהיר/ה שהנושא הוא true.
isFalsy() טוען שהנושא הוא חשוד. ערכי Falsy הם undefined, null, false, NaN, 0 ו-'' (מחרוזת ריקה).
isTruthy() טוען שהנושא נכון. ערכי Falsy הם undefined, null, false, NaN, 0 ו-'' (מחרוזת ריקה).
isNaN() מצהירה שהנושא הוא הערך NaN.
isNotNaN() מצהירה שהנושא הוא כל ערך מלבד NaN.
isInfinity() מצהיר שהנושא הוא אינסוף חיובי או שלילי.
isNotInfinity() מצהירה שהנושא הוא כל ערך מלבד אינסוף חיובי או שלילי.
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) מצהירה שהנושא הוא מערך או מחרוזת באורך הנתון. טענת הנכוֹנוּת (assertion) תמיד תיכשל אם הערך הוא לא מערך או מחרוזת.
isEmpty() טוענת שהנושא הוא מערך או מחרוזת ריקים (length = 0). טענת הנכוֹנוּת (assertion) תמיד נכשלת אם הערך הוא לא מערך או מחרוזת.
isNotEmpty() מצהירה שהנושא הוא מערך או מחרוזת שלא ריקים (אורך > 0). טענת הנכוֹנוּת (assertion) תמיד נכשלת אם הערך הוא לא מערך או מחרוזת.
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 string טקסט אופציונלי של הודעת שגיאה.

דוגמה

fail('This test has failed.');

mock

ה-API של mock מאפשר לבטל את ההתנהגות של ממשקי Sandboxed API. ה-mock API בטוח לשימוש בקוד תבנית, אבל הוא לא פעיל כשהוא לא במצב בדיקה. הדוגמאות מתאפסות לפני כל בדיקה.

תחביר

mock(apiName, returnValue);

פרמטרים

פרמטר סוג תיאור
apiName string שם ה-API להדמיה. אותה מחרוזת שהועברה אל require()
returnValue כלשהו הערך שצריך להחזיר עבור ה-API או פונקציה שנקראת במקום ה-API. אם returnValue היא פונקציה, קוראים לפונקציה הזו במקום ה-API של Sandboxed. אם returnValue הוא כל דבר שאינו פונקציה, הערך הזה מוחזר במקום ה-API של Sandboxed.

דוגמאות

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

runCode

מריצה את הקוד של התבנית, כלומר את התוכן של הכרטיסייה Code בסביבת הבדיקה הנוכחית, עם אובייקט נתון של נתוני קלט.

תחביר

runCode(data)

פרמטרים

פרמטר סוג תיאור
data אובייקט אובייקט נתונים לשימוש בבדיקה.

ערך החזרה

הפונקציה מחזירה את הערך של משתנה בתבניות של משתנים, ומחזירה את הערך undefined לכל שאר סוגי התבניות.

דוגמה

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