במסמך הזה מתוארים ממשקי ה-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.
});
ההרשאות המשויכות
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' (לא תלוי-רישיות). המערכת מתעלמת מכל שאר התווים. |
ההרשאות המשויכות
ללא.
גרסת תמונה מינימלית
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();
ההרשאות המשויכות
getClientName
הפונקציה מחזירה string שמכיל את השם של הלקוח הנוכחי.
תחביר
getClientName();
ההרשאות המשויכות
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();
ההרשאות המשויכות
getCookieValues
מחזירה מערך שמכיל את הערכים של כל קובצי ה-cookie בעלי השם הנתון.
דוגמה
const getCookieValues = require('getCookieValues');
const lastVisit = getCookieValues('lastVisit')[0];
if (lastVisit) {
// ...
}
תחביר
getCookieValues(name[, noDecode]);
פרמטרים
פרמטר | סוג | תיאור |
---|---|---|
name |
string | השם של קובץ ה-cookie. |
noDecode |
boolean |
אם הערך שלו הוא true , הערכים של קובצי ה-cookie לא מפוענחים לפני שהם מוחזרים. ברירת המחדל היא false .
|
ההרשאות המשויכות
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);
ההרשאות המשויכות
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();
ההרשאות המשויכות
getRequestHeader
הפונקציה מחזירה את הערך של כותרת הבקשה בעלת השם כ-string, אם קיימת. אחרת, היא undefined
. אם הכותרת חוזרת על עצמה, הערכים המוחזרים מצורפים יחד עם ', '
.
דוגמה
const getRequestHeader = require('getRequestHeader');
const host = getRequestHeader('host');
תחביר
getRequestHeader(headerName);
פרמטרים
פרמטר | סוג | תיאור |
---|---|---|
headerName |
string | שם הכותרת. הערך הזה לא תלוי רישיות. |
ההרשאות המשויכות
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();
ההרשאות המשויכות
getRequestQueryParameter
הפונקציה מחזירה את הערך המפוענח של הפרמטר בעל השם של מחרוזת השאילתה כ-string, או undefined
אם הפרמטר לא נמצא. אם הפרמטר חוזר על עצמו במחרוזת השאילתה, מוחזר הערך הראשון שמופיע במחרוזת השאילתה.
דוגמה
const getRequestQueryParameter = require('getRequestQueryParameter');
const query = getRequestQueryParameter('query');
if (query) {
// Process query here.
}
תחביר
getRequestQueryParameter(name);
פרמטרים
פרמטר | סוג | תיאור |
---|---|---|
name |
string | שם הפרמטר של השאילתה. |
ההרשאות המשויכות
getRequestQueryParameters
הפונקציה מחזירה את הפרמטרים של השאילתה של בקשת ה-HTTP הנכנסת כאובייקט שממפה את שמות הפרמטרים של השאילתות לערך או לערכים התואמים. השמות והערכים של הפרמטרים מפוענחים.
דוגמה
const getRequestQueryParameters = require('getRequestQueryParameters');
const queryParameters = getRequestQueryParameters();
if (queryParameters['search']) {
// Handle the search query here.
const maxResults = queryParameters['max_results'];
}
תחביר
getRequestQueryParameters();
ההרשאות המשויכות
getRequestQueryString
מחזירה את שאילתת הבקשה כמחרוזת, בלי סימן השאלה בהתחלה, או מחרוזת ריקה אם כתובת ה-URL של הבקשה לא כוללת מחרוזת שאילתה.
דוגמה
const getRequestQueryString = require('getRequestQueryString');
const queryString = getRequestQueryString();
if (queryString !== '') {
// Handle the query string.
}
תחביר
getRequestQueryString();
ההרשאות המשויכות
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 . |
ההרשאות המשויכות
גרסת תמונה מינימלית
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 לוקח ארגומנט אחד או יותר, וכל אחד מהם מומר למחרוזת, אם יש צורך, ונרשם במסוף.
ההרשאות המשויכות
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
.
ההרשאות המשויכות
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) מופעלת באופן מיידי, לפני שהתגים מתחילים לפעול. |
ההרשאות המשויכות
sendEventToGoogleAnalytics
שולחת אירוע יחיד באמצעות נתוני אירועים נפוצים ל-Google Analytics, ומחזירה הבטחה שמפנה לאובייקט עם מפתח location
או דוחה לאובייקט עם מפתח reason
. היעד, Universal Analytics או 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 |
אובייקט | האירוע בפורמט סכימה מאוחדת. |
ההרשאות המשויכות
נדרשת ההרשאה 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 . |
ההרשאות המשויכות
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 . |
ההרשאות המשויכות
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 שצריך לשלוח לדפדפן. |
ההרשאות המשויכות
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
.
- eTLD+1 של הכותרת
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'
.
ההרשאות המשויכות
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);
});
ההרשאות המשויכות
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. יש
פרמטר אופציונלי אחד ושני פרמטרים נדרשים:
|
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);
ההרשאות המשויכות
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.
ההרשאות המשויכות
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
(בדרך כלל באמצעות תג), הקריאה החוזרת תפעל באופן סינכרוני. הקריאה החוזרת פועלת עם שני פרמטרים:
messageType:string
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'});