میاناهای برنامه‌سازی کاربردی برچسب‌گذاری سمت سرور

این سند میاناهای برنامه‌سازی کاربردی برای برچسب‌گذاری سمت سرور را شرح می‌دهد.

addEventCallback

تابع بازخوانی‌ای را ثبت می‌کند که در پایان رویداد فراخوانده می‌شود. وقتی همه برچسب‌های رویداد اجرا شد، فراخوانی برگشتی فراخوانده می‌شود. دو مقدار به callback ارسال می‌شود: شناسه محفظه‌ای که تابع را فرامی‌خواند و شیئی که حاوی اطلاعاتی درباره رویداد است.

وقتی از این API در برچسبی استفاده می‌شود، به رویداد فعلی مرتبط می‌شود. وقتی از این API در کارخواه استفاده می‌شود، باید بااستفاده از تابع bindToEvent در runContainer API به رویداد خاصی محدود شود. برای جزئیات بیشتر، نمونه را ببینید.

نحو

const addEventCallback = require('addEventCallback');

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

پارامترها

پارامتر نوع شرح
callback تابع تابعی که در پایان رویداد فراخوانی می‌شود.

شیء eventData حاوی داده‌های زیر است:

نام کلید نوع شرح
tags Array آرایه‌ای از اشیای داده برچسب. هر برچسبی که درطول رویداد فعال شده باشد یک ورودی در این آرایه خواهد داشت. شیء داده برچسب حاوی شناسه برچسب (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 در کارخواه برای ادعای درخواست استفاده کنید. وقتی درخواستی ادعا می‌شود، محفظه کارخواه دیگری را اجرا نمی‌کند.

اگر این میانای برنامه‌سازی کاربردی در برچسب یا متغیر فراخوانده شود، استثنایی ایجاد می‌کند. اگر این میانای برنامه‌سازی کاربردی پس‌از بازگشت کارخواه فراخوانده شود (مثلاً اگر در یک فراخوانی متقابل ناهمگام مانند callLater یا تابع runContainer onComplete فراخوانده شود)، استثنایی ایجاد می‌کند.

کارخواه باید قبل‌از فراخوانی runContainer API، درخواست را بااستفاده از این API مطالبه کند.

نمونه

const claimRequest = require('claimRequest');

claimRequest();

نحو

claimRequest();

اجازه‌های مرتبط

هیچ‌کدام.

computeEffectiveTldPlusOne

دامنه سطح بالای مؤثر + ۱ (eTLD+1) دامنه یا نشانی وب ارائه‌شده را برمی‌گرداند. eTLD+1 با ارزیابی دامنه دربرابر قوانین فهرست پسوند عمومی محاسبه می‌شود. eTLD+1 معمولاً بالاترین سطح دامنه‌ای است که می‌توانید در آن کوکی تنظیم کنید.

اگر آرگومان تهی یا تعریف‌نشده باشد، مقدار آرگومان بدون تغییر برگردانده می‌شود. درغیراین‌صورت، آرگومان به رشته تبدیل می‌شود. اگر آرگومان دامنه یا نشانی وب معتبری نباشد، رشته خالی برگردانده می‌شود. اگر سرور نتواند فهرست پسوند عمومی را واکشی کند، مقدار آرگومان بدون تغییر برگردانده می‌شود.

نمونه

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 رشته دامنه یا نشانی وبی که eTLD+1 در آن محاسبه می‌شود.

اجازه‌های مرتبط

هیچ‌کدام.

createRegex

نمونه عبارت باقاعده جدیدی ایجاد می‌کند و آن را به‌صورت پیچیده‌شده در یک شیء برمی‌گرداند. نمی‌توانید مستقیماً به عبارت باقاعده دسترسی داشته باشید. بااین‌حال، می‌توانید آن را به میانای برنامه‌سازی کاربردی testRegex، String.replace()، String.match()، و String.search() منتقل کنید.

اگر عبارت باقاعده نامعتبر باشد یا Re2 در سرور دردسترس نباشد، null را برمی‌گرداند.

این میانای برنامه‌سازی کاربردی از پیاده‌سازی Re2 استفاده می‌کند. تصویر Docker سرور باید نسخه 2.0.0 یا بالاتر باشد.

نمونه

const createRegex = require('createRegex');

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

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

نحو

createRegex(pattern, flags);

پارامترها

پارامتر نوع شرح
pattern رشته نوشتار عبارت باقاعده.
flags رشته رشته اختیاری حاوی پرچم‌های عبارت باقاعده درحال ایجاد. از `g` (سراسری) و `i` (صرف‌نظر از اندازه حروف) پشتیبانی می‌شود. همه نویسه‌های دیگر بدون اطلاع نادیده گرفته می‌شوند.

اجازه‌های مرتبط

هیچ‌کدام.

حداقل نسخه تصویر

2.0.0

decodeUri

همه نویسه‌های کدگذاری‌شده در URI ارائه‌شده را رمزگشایی می‌کند. رشته‌ای را برمی‌گرداند که نشان‌دهنده URI رمزگشایی‌شده است. اگر ورودی نامعتبر ارائه شود، undefined را برمی‌گرداند.

نمونه

const decodeUri = require('decodeUri');

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

نحو

decodeUri(encoded_uri);

پارامترها

پارامتر نوع شرح
encoded_uri رشته شناسه منبع یکسانی که توسط encodeUri() یا روش‌های دیگر کدگذاری شده است.

اجازه‌های مرتبط

هیچ‌کدام.

decodeUriComponent

هر نویسه کدگذاری‌شده را در مؤلفه URI ارائه‌شده رمزگشایی می‌کند. رشته‌ای را برمی‌گرداند که نشان‌دهنده مؤلفه URI رمزگشایی‌شده است. اگر ورودی نامعتبر باشد، undefined را برمی‌گرداند.

نمونه

const decodeUriComponent = require('decodeUriComponent');

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

نحو

decodeUriComponent(encoded_uri_component);

پارامترها

پارامتر نوع شرح
encoded_uri_component رشته مؤلفه URI که توسط encodeUriComponent() یا به‌روش دیگری کدگذاری شده است.

اجازه‌های مرتبط

هیچ‌کدام.

encodeUri

با گریز از نویسه‌های خاص، «شناسه منبع یکسان» (URI) کدگذاری‌شده‌ای را برمی‌گرداند. رشته‌ای را برمی‌گرداند که نشان‌دهنده رشته ارائه‌شده کدگذاری‌شده به‌عنوان URI است.

نمونه

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

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

نحو

encodeUri(uri);

پارامترها

پارامتر نوع شرح
uri رشته یک URI کامل.

اجازه‌های مرتبط

هیچ‌کدام.

encodeUriComponent

با گریز از نویسه‌های خاص، «شناسه منبع یکسان» (URI) کدگذاری‌شده‌ای را برمی‌گرداند. رشته‌ای را برمی‌گرداند که نشان‌دهنده رشته ارائه‌شده است که به‌عنوان شناسه منبع یکسان کدگذاری شده است.

نمونه

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

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

نحو

encodeUriComponent(str);

پارامترها

پارامتر نوع شرح
str رشته بخشی از URI.

اجازه‌های مرتبط

هیچ‌کدام.

extractEventsFromMpv1

درخواست Measurement Protocol V1 ورودی را به فهرستی از رویدادها در قالب «طرح‌واره یکپارچه» ترجمه می‌کند. فهرست رویدادهای استخراج‌شده را برمی‌گرداند. اگر درخواست در قالب صحیح نباشد، خطا ایجاد می‌کند.

نمونه

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

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

نحو

extractEventsFromMpv1();

اجازه‌های مرتبط

به اجازه read_request نیاز دارد. اجازه باید به‌گونه‌ای پیکربندی شود که حداقل به موارد زیر اجازه دسترسی دهد:

  • body
  • query parameters

extractEventsFromMpv2

درخواست Measurement Protocol V2 ورودی را به فهرستی از رویدادها در قالب «طرح‌واره یکپارچه» ترجمه می‌کند. فهرست رویدادهای استخراج‌شده را برمی‌گرداند. اگر درخواست در قالب صحیح نباشد، خطا ایجاد می‌کند.

نمونه

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

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

نحو

extractEventsFromMpv2();

اجازه‌های مرتبط

به اجازه read_request نیاز دارد. اجازه باید به‌گونه‌ای پیکربندی شود که حداقل به موارد زیر اجازه دسترسی دهد:

  • body
  • query parameters

fromBase64

رشته کدبندی‌شده با base64 را رمزگشایی می‌کند. اگر ورودی نامعتبر باشد، undefined را برمی‌گرداند.

نحو

fromBase64(base64EncodedString);

پارامترها

پارامتر نوع شرح
base64EncodedString رشته رشته کدبندی‌شده Base64.

نمونه

const fromBase64 = require('fromBase64');

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

اجازه‌های مرتبط

هیچ‌کدام.

generateRandom

عددی (عدد صحیح) تصادفی را در محدوده ارائه‌شده برمی‌گرداند.

نمونه

const generateRandom = require('generateRandom');

const randomValue = generateRandom(0, 10000000);

نحو

generateRandom(min, max);

پارامترها

پارامتر نوع شرح
min number حداقل مقدار بالقوه عدد صحیح برگردانده‌شده (شامل).
max number حداکثر مقدار بالقوه عدد صحیح برگردانده‌شده (شامل).

اجازه‌های مرتبط

هیچ‌کدام.

getAllEventData

نسخه‌ای از داده‌های رویداد را برمی‌گرداند.

نحو

getAllEventData();

اجازه‌های مرتبط

read_event_data

getAnonymizedIpAddress

نمایش رشته ناشناس‌سازی‌شده نشانی IP را که درخواست از آنجا ارسال شده است برمی‌گرداند.

برای نشانی‌های IPv4، آخرین هشت‌تایی به 0 ماسک می‌شود (برای مثال، 198.51.100.42 به 198.51.100.0 تبدیل می‌شود). برای نشانی‌های IPv6، آخرین ۸۰ بیت به صفر ماسک می‌شود و ۴۸ بیت اول حفظ می‌شود (برای مثال، 2001:db8:cafe:1234:5678:90ab:cdef:1234 به 2001:db8:cafe:: تبدیل می‌شود).

اگر نشانی IP نامعتبر باشد یا قابل‌حل نباشد، "::" را برمی‌گرداند، بنابراین نتیجه همیشه برای استفاده به‌عنوان ip_override ایمن است.

نمونه

const getAnonymizedIpAddress = require('getAnonymizedIpAddress');

const anonymizedIp = getAnonymizedIpAddress();

نحو

getAnonymizedIpAddress();

اجازه‌های مرتبط

user_ip

getClientName

رشته‌ای را برمی‌گرداند که حاوی نام مشتری فعلی است.

نحو

getClientName();

اجازه‌های مرتبط

read_container_data

getContainerVersion

شیئی حاوی داده‌های مربوط به محفظه فعلی را برمی‌گرداند. شیء برگردانده‌شده فیلدهای زیر را خواهد داشت:

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

نمونه

const getContainerVersion = require('getContainerVersion');

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

نحو

getContainerVersion();

اجازه‌های مرتبط

read_container_data

getCookieValues

آرایه‌ای حاوی مقادیر همه کوکی‌ها با نام داده‌شده برمی‌گرداند.

نمونه

const getCookieValues = require('getCookieValues');

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

نحو

getCookieValues(name[, noDecode]);

پارامترها

پارامتر نوع شرح
name رشته نام کوکی.
noDecode مقدار منطقی اگر true، مقادیر کوکی قبل‌از برگردانده شدن رمزگشایی نخواهد شد. پیش‌فرض‌ها به false.

اجازه‌های مرتبط

get_cookies

getEventData

کپی مقدار را در مسیر داده‌شده در داده‌های رویداد برمی‌گرداند. اگر داده‌های رویداد وجود نداشته باشد یا اگر مقداری در مسیر داده‌شده وجود نداشته باشد، undefined را برمی‌گرداند.

نمونه

const getEventData = require('getEventData');

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

پارامترها

پارامتر نوع شرح
keyPath any مسیر کلید، که در آن اجزای مسیر با نقطه از هم جدا شده‌اند. مؤلفه‌های مسیر می‌توانند کلیدهایی در یک شیء یا شاخص‌هایی در یک آرایه باشند. اگر keyPath رشته نباشد، به رشته تبدیل می‌شود.

نحو

getEventData(keyPath);

اجازه‌های مرتبط

read_event_data

getGoogleAuth

یک شیء مجوز برمی‌گرداند که وقتی با sendHttpGet یا sendHttpRequest استفاده شود، سرصفحه مجوز برای Google Cloud APIs را دربر خواهد داشت. این API از اطلاعات اعتباری پیش‌فرض برنامه برای پیدا کردن خودکار اطلاعات اعتباری از محیط سرور استفاده می‌کند.

نمونه

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

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

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

نحو

getGoogleAuth(scopes);

پارامترها

پارامتر نوع شرح
scopes Array آرایه‌ای از دامنه‌های Google API مربوط به OAuth 2.0 برای درخواست دسترسی.

اجازه‌های مرتبط

به اجازه use_google_credentials نیاز دارد. اجازه باید با یک یا چند دامنه مجاز پیکربندی شود.

getGoogleScript

منبعی را از مجموعه ازپیش تعیین‌شده‌ای از اسکریپت‌های Google بازیابی می‌کند و یک قول با اسکریپت و فراداده‌های ذخیره‌سازی موقت مرتبط برمی‌گرداند.

این وعده به شیئی حاوی دو کلید تبدیل می‌شود: script و metadata. اگر درخواست ناموفق باشد، promise با کلید reason رد خواهد شد.

شیء metadata حاوی فراداده ذخیره‌سازی موقت زیر براساس سرایندهای پاسخ منبع خواهد بود؛ هر فیلد فقط درصورتی وجود خواهد داشت که سرایند مربوطه در پاسخ منبع وجود داشته باشد.

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

نمونه

const getGoogleScript = require('getGoogleScript');

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

نحو

getGoogleScript(script[, options]);

پارامترها

پارامتر نوع شرح
script رشته نام دستورگان. اسکریپت‌های پشتیبانی‌شده عبارت‌اند از 'ANALYTICS'، 'GTAG'، و 'GTM'.

گزینه 'ANALYTICS' اسکریپت Google Analytics را از https://www.google-analytics.com/analytics.js واکشی می‌کند.

گزینه 'GTAG' اسکریپت برچسب سایت فراگیر (gtag.js) را از https://www.googletagmanager.com/gtag/js واکشی می‌کند.

گزینه 'GTM' اسکریپت Google Tag Manager را از https://www.googletagmanager.com/gtm.js واکشی می‌کند.
options شیء گزینه‌های درخواست اختیاری. گزینه‌های پشتیبانی‌شده را در زیر ببینید.

گزینه‌ها

گزینه نوع شرح
id رشته قابل‌اعمال برای 'GTAG' با شناسه سنجش gtag و 'GTM' با شناسه محفظه وب (مثلاً GTM-XXXX).
debug any اگر درست باشد، نسخه اشکال‌زدایی اسکریپت اندازه‌گیری را درخواست می‌کند و برمی‌گرداند.
timeout number مهلت درخواست به میلی‌ثانیه؛ مقادیر غیرمثبت نادیده گرفته می‌شود. اگر درخواست منقضی شود، فراخوانی با undefined برای مقدار اسکریپت و {} برای شیء فراداده فراخوانده می‌شود.

کلیدهای گزینه ناشناخته نادیده گرفته می‌شوند.

اجازه‌های مرتبط

به اجازه send_http نیاز دارد. اجازه باید به‌گونه‌ای پیکربندی شود که حداقل دسترسی به موارد زیر را مجاز کند:

  • مجاز کردن Google Domains

getRemoteAddress

نمایش رشته‌ای نشانی IP را که درخواست از آنجا ارسال شده است برمی‌گرداند، مثلاً 12.345.67.890 برای IPv4 یا 2001:0db8:85a3:0:0:8a2e:0370:7334 برای IPv6، با خواندن سرایندهای درخواست مانند Forwarded و X-Forwarded-For. توجه: این API نهایت تلاش خود را برای کشف IP مبدأ انجام می‌دهد، اما نمی‌تواند تضمین کند که نتیجه دقیق است.

نحو

getRemoteAddress();

اجازه‌های مرتبط

به اجازه read_request نیاز دارد. اجازه باید به‌گونه‌ای پیکربندی شود که حداقل به موارد زیر اجازه دسترسی دهد:

  • سرایندهای Forwarded و X-Forwarded-For
  • نشانی IP ازراه‌دور

getRequestBody

درصورت وجود، بدنه درخواست را به‌صورت رشته برمی‌گرداند، درغیراین‌صورت undefined را برمی‌گرداند.

نحو

getRequestBody();

اجازه‌های مرتبط

read_request

getRequestHeader

مقدار سرایند درخواست نام‌گذاری‌شده را به‌صورت رشته برمی‌گرداند، اگر وجود داشته باشد، یا undefined درغیراین‌صورت. اگر سرایند تکرار شود، مقادیر برگردانده‌شده با ', ' به یکدیگر می‌پیوندند.

نمونه

const getRequestHeader = require('getRequestHeader');

const host = getRequestHeader('host');

نحو

getRequestHeader(headerName);

پارامترها

پارامتر نوع شرح
headerName رشته نام سرایند. این مقدار به حروف بزرگ و کوچک حساس نیست.

اجازه‌های مرتبط

read_request

getRequestMethod

روش درخواست را، مثلاً 'GET' یا 'POST'، به‌صورت رشته برمی‌گرداند.

نمونه

const getRequestMethod = require('getRequestMethod');

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

نحو

getRequestMethod();

اجازه‌های مرتبط

هیچ‌کدام.

getRequestPath

مسیر درخواست را بدون رشته پُرسمان برمی‌گرداند. برای مثال، اگر نشانی وب '/foo?id=123' باشد، این مقدار '/foo' را برمی‌گرداند. به‌طور خودکار پیشوند نشانی وب حامل سرور را از مسیر حذف می‌کند. برای مثال، اگر نشانی وب حامل سرور https://example.com/analytics و مسیر درخواست '/analytics/foo' باشد، این '/foo' را برمی‌گرداند.

نمونه

const getRequestPath = require('getRequestPath');

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

نحو

getRequestPath();

اجازه‌های مرتبط

read_request

getRequestQueryParameter

مقدار رمزگشایی‌شده پارامتر رشته پُرسمان نام‌گذاری‌شده را به‌عنوان رشته برمی‌گرداند، یا اگر پارامتر وجود نداشته باشد، undefined را برمی‌گرداند. اگر پارامتر در رشته پُرسمان تکرار شود، اولین مقداری که در رشته پُرسمان ظاهر می‌شود برگردانده خواهد شد.

نمونه

const getRequestQueryParameter = require('getRequestQueryParameter');

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

نحو

getRequestQueryParameter(name);

پارامترها

پارامتر نوع شرح
name رشته نام پارامتر پُرسمان.

اجازه‌های مرتبط

read_request

getRequestQueryParameters

پارامترهای پُرسمان درخواست اچ‌تی‌تی‌پی ورودی را به‌عنوان شیئی برمی‌گرداند که نام‌های پارامتر پُرسمان را به مقدار یا مقادیر مربوطه نگاشت می‌کند. نام‌ها و مقادیر پارامتر رمزگشایی می‌شوند.

نمونه

const getRequestQueryParameters = require('getRequestQueryParameters');

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

نحو

getRequestQueryParameters();

اجازه‌های مرتبط

read_request

getRequestQueryString

پرسمان درخواست را به‌صورت رشته، بدون علامت سؤال ابتدایی، یا رشته‌ای خالی (اگر نشانی وب درخواست حاوی رشته پرسمان نباشد) برمی‌گرداند.

نمونه

const getRequestQueryString = require('getRequestQueryString');

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

نحو

getRequestQueryString();

اجازه‌های مرتبط

read_request

getTimestamp

منسوخ‌شده. getTimestampMillis را ترجیح دهید.

عددی را برمی‌گرداند که نشان‌دهنده زمان فعلی برحسب میلی‌ثانیه از تاریخ یونیکس است، همان‌طور که توسط Date.now() برگردانده شده است.

نحو

getTimestamp();

اجازه‌های مرتبط

هیچ‌کدام.

getTimestampMillis

عددی را برمی‌گرداند که نشان‌دهنده زمان فعلی برحسب میلی‌ثانیه از تاریخ یونیکس است، همان‌طور که توسط Date.now() برگردانده شده است.

نحو

getTimestampMillis();

اجازه‌های مرتبط

هیچ‌کدام.

getType

رشته‌ای را برمی‌گرداند که نوع مقدار داده‌شده را توصیف می‌کند.

نوع ورودی مقدار برگردانده‌شده
رشته 'string'
number 'number'
مقدار منطقی 'boolean'
null 'null'
undefined 'undefined'
Array 'array'
شیء 'object'
تابع 'function'

نمونه

const getType = require('getType');

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

نحو

getType(value);

پارامترها

پارامتر نوع شرح
value any مقدار ورودی.

اجازه‌های مرتبط

هیچ‌کدام.

hmacSha256

امضای کدگذاری‌شده را بااستفاده از کد اصالت‌سنجی پیام مبتنی بر درهم‌سازی (HMAC) با SHA-256 محاسبه می‌کند. به‌طور پیش‌فرض روی کدبندی base64url تنظیم شده است.

برای استفاده از این «میانای برنامه‌سازی کاربردی»، متغیر محیطی SGTM_CREDENTIALS را در سرور روی مسیر فایل کلید JSON کدبندی‌شده با UTF-8 با قالب زیر تنظیم کنید:

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

مقادیر، کلیدهای HMAC کدبندی‌شده با base64 هستند. نوشتار JSON نباید با نشانگر ترتیب بایت شروع شود.

نمونه

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

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

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

نحو

hmacSha256(data, keyId, options)

پارامترها

پارامتر نوع شرح
data رشته داده‌ها برای محاسبه مقدار HMAC.
keyId رشته شناسه کلید از فایل کلید JSON که به کلید مورداستفاده ارجاع می‌دهد.
options شیء پیکربندی میانای برنامه‌سازی کاربردی اختیاری. (گزینه‌های زیر را ببینید.)

گزینه‌ها

گزینه نوع شرح
outputEncoding رشته قالب کدبندی را برای مقدار برگشتی مشخص می‌کند. قالب‌های پشتیبانی‌شده عبارت‌اند از hex، base64، یا base64url. اگر مشخص نشده باشد، به‌طور پیش‌فرض روی base64url تنظیم می‌شود.

اجازه‌های مرتبط

use_custom_private_keys

حداقل نسخه تصویر

1.0.0

isRequestMpv1

اگر درخواست ورودی درخواست Measurement Protocol V1 باشد، true را برمی‌گرداند، درغیراین‌صورت false را برمی‌گرداند.

نمونه

const isRequestMpv1 = require('isRequestMpv1');

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

نحو

isRequestMpv1();

اجازه‌های مرتبط

هیچ‌کدام.

isRequestMpv2

اگر درخواست ورودی از نوع Measurement Protocol V2 باشد، true را برمی‌گرداند، وگرنه false را برمی‌گرداند.

نمونه

const isRequestMpv2 = require('isRequestMpv2');

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

نحو

isRequestMpv2();

اجازه‌های مرتبط

هیچ‌کدام.

logToConsole

متغیرهای مستقل خود را در کنسول ثبت می‌کند.

این گزارش‌ها در کاوشگر گزارش‌ها در «کنسول 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, ...]);

پارامترها

این میانای برنامه‌سازی کاربردی یک یا چند متغیر مستقل می‌گیرد که هرکدام درصورت لزوم به رشته تبدیل می‌شوند و در کنسول ثبت می‌شوند.

اجازه‌های مرتبط

logging

makeInteger

مقدار داده‌شده را به عدد (عدد صحیح) تبدیل می‌کند.

نحو

makeInteger(value);

پارامترها

پارامتر نوع شرح
value هر نوع مقداری که باید تبدیل شود.

اجازه‌های مرتبط

هیچ‌کدام.

makeNumber

مقدار داده‌شده را به عدد تبدیل می‌کند.

نحو

makeNumber(value);

پارامترها

پارامتر نوع شرح
value هر نوع مقداری که باید تبدیل شود.

اجازه‌های مرتبط

هیچ‌کدام.

makeString

مقدار داده‌شده را به‌عنوان رشته برمی‌گرداند.

نحو

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 رشته نام ستونی که مقادیر آن به کلیدهای Map تبدیل‌شده تبدیل خواهد شد.
valueColumnName رشته نام ستونی که مقادیر آن به مقادیر در Map تبدیل‌شده تبدیل خواهد شد.

اجازه‌های مرتبط

هیچ‌کدام.

parseUrl

شیئی را برمی‌گرداند که حاوی همه بخش‌های تشکیل‌دهنده نشانی وب داده‌شده است، مشابه شیء URL.

این میانای برنامه‌سازی کاربردی برای هر نشانی وب ناقصی undefined را برمی‌گرداند. برای نشانی‌های وب با قالب‌بندی مناسب، فیلدهایی که در رشته نشانی وب وجود ندارند، مقدار رشته خالی خواهند داشت، یا در مورد 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 رشته نشانی وب کاملی که تجزیه خواهد شد.

اجازه‌های مرتبط

هیچ‌کدام.

returnResponse

پاسخی را که قبلاً توسط الگوهای دیگر بااستفاده از میاناهای برنامه‌سازی کاربردی اصلاح‌کننده پاسخ تنظیم شده است، ازجمله setCookie،‏ setPixelResponse،‏ setResponseBody،‏ setResponseHeader، و setResponseStatus، پاک می‌کند. به‌طور پیش‌فرض روی رمز وضعیت HTTP 200، بدنه خالی، و بدون سرایند تنظیم شده است.

توصیه می‌شود که این میانای برنامه‌سازی کاربردی از الگوی مشتری استفاده شود.

نحو

returnResponse();

نمونه

نمونه runContainer را ببینید.

اجازه‌های مرتبط

return_response

runContainer

منطق حامل (متغیرها، محرک‌ها، برچسب‌ها) را در محدوده یک رویداد اجرا می‌کند. اگر این میانای برنامه‌سازی کاربردی درطول اجرای محفظه فراخوانده شود، محفظه دوباره اجرا می‌شود.

کال‌بک‌های onComplete و onStart تابعی به‌نام bindToEvent دریافت می‌کنند. از bindToEvent برای اجرای API در بافت رویداد استفاده کنید. برای جزئیات بیشتر، نمونه addEventCallback را ببینید.

توصیه می‌شود که این میانای برنامه‌سازی کاربردی از الگوی مشتری استفاده شود.

مثال

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 تابع فراخوانی برگشتی که بلافاصله، قبل‌از شروع فعال شدن برچسب‌ها، فراخوانی می‌شود.

اجازه‌های مرتبط

run_container

sendEventToGoogleAnalytics

بااستفاده از داده‌های رویداد رایج، رویداد تکی به Google Analytics ارسال می‌کند و قولی برمی‌گرداند که به شیئی با کلید location تبدیل می‌شود یا به شیئی با کلید reason رد می‌شود. مقصد، Google Analytics، براساس شناسه سنجش در داده‌های رویداد است.

فیلد 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 را به نشانی وب مشخص‌شده ارسال می‌کند و قولی را برمی‌گرداند که پس‌از تکمیل درخواست یا اتمام مهلت، با نتیجه حل می‌شود.

نتیجه حل‌شده شیئی است که حاوی سه کلید است: statusCode، headers، و body. اگر درخواست ناموفق بود (مثلاً نشانی وب نامعتبر، عدم وجود مسیر به میزبان، ناموفق بودن مذاکره 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 رشته نشانی وب درخواست‌شده.
options شیء گزینه‌های درخواست اختیاری. (گزینه‌های زیر را ببینید.)

گزینه‌ها

گزینه نوع شرح
headers رشته سرایندهای درخواست اضافی.
timeout number زمان وقفه، برحسب میلی‌ثانیه، قبل‌از اینکه درخواست لغو شود. پیش‌فرض‌ها به 15000.
authorization شیء شیء مجوز اختیاری از تماس با getGoogleAuth برای گنجاندن سرایندهای مجوز هنگام درخواست به googleapis.com.

اجازه‌های مرتبط

send_http

sendHttpRequest

درخواست HTTP به نشانی وب مشخص‌شده ارسال می‌کند و قولی برمی‌گرداند که پس‌از تکمیل درخواست یا اتمام مهلت، با پاسخ حل می‌شود.

نتیجه حل‌شده شیئی است که حاوی سه کلید است: statusCode، headers، و body. اگر درخواست ناموفق بود (مثلاً نشانی وب نامعتبر، عدم وجود مسیر به میزبان، ناموفق بودن مذاکره 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 رشته نشانی وب درخواست‌شده.
options شیء گزینه‌های درخواست اختیاری. (گزینه‌های زیر را ببینید.)
body رشته متن درخواست اختیاری.

گزینه‌ها

گزینه نوع شرح
headers رشته سرایندهای درخواست اضافی.
method شیء روش درخواست. پیش‌فرض‌ها به GET.
timeout number زمان وقفه، برحسب میلی‌ثانیه، قبل‌از اینکه درخواست لغو شود. پیش‌فرض‌ها به 15000.
authorization شیء شیء مجوز اختیاری از تماس با getGoogleAuth برای گنجاندن سرایندهای مجوز هنگام درخواست به googleapis.com.

اجازه‌های مرتبط

send_http

sendPixelFromBrowser

فرمانی به مرورگر ارسال می‌کند تا نشانی وب ارائه‌شده را به‌عنوان برچسب <img> بار کند. این پروتکل فرمان در برچسب Google برای Google Analytics و برچسب‌های وب Google Analytics: رویداد GA پشتیبانی می‌شود. باید نشانی وب حامل سرور را پیکربندی کنید. برای جزئیات بیشتر، دستورالعمل‌ها را ببینید.

اگر درخواست ورودی از پروتکل فرمان پشتیبانی نکند یا اگر پاسخ قبلاً پاک شده باشد، این API false را برمی‌گرداند. درغیراین‌صورت، این API true را برمی‌گرداند.

مثال:

const sendPixelFromBrowser = require('sendPixelFromBrowser');

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

نحو

sendPixelFromBrowser(url)

پارامترها

پارامتر نوع شرح
url رشته نشانی وب برای ارسال به مرورگر.

اجازه‌های مرتبط

send_pixel_from_browser

setCookie

کوکی‌ای را با گزینه‌های مشخص‌شده تنظیم یا حذف می‌کند.

برای حذف کوکی، باید کوکی‌ای با همان مسیر و دامنه‌ای که کوکی با آن ایجاد شده است تنظیم کنید و مقدار انقضایی را که در گذشته است به آن اختصاص دهید، مثلاً "Thu, 01 Jan 1970 00:00:00 GMT".

توجه داشته باشید که returnResponse باید برای پاسخ فراخوانی شود تا به مشتری برگردانده شود.

نمونه

const setCookie = require('setCookie');

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

نحو

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

پارامترها

پارامتر نوع شرح
name رشته نام کوکی. نام به حروف بزرگ و کوچک حساس نیست.
value رشته مقدار کوکی.
options شیء ویژگی‌های اختیاری کوکی:domain، expires، fallbackDomain،httpOnly، max- age، path، secure، وsameSite. (گزینه‌ها را در زیر ببینید.)
noEncode مقدار منطقی اگر درست باشد، مقدار کوکی کدگذاری نخواهد شد. پیش‌فرض‌ها به false.

گزینه‌ها

  • domain: میزبانی که کوکی به آن ارسال خواهد شد. اگر روی مقدار ویژه «خودکار» تنظیم شود، میزبان به‌طور خودکار بااستفاده از استراتژی زیر محاسبه خواهد شد:

    • eTLD+1 سرصفحه Forwarded، درصورت وجود.
    • eTLD+1 سرصفحه X-Forwarded-Host، درصورت وجود.
    • eTLD+1 از سرصفحه Host.

  • expires: حداکثر طول عمر کوکی. این باید رشته تاریخ با قالب UTC باشد، برای نمونه «Sat, 26 Oct 1985 08:21:00 GMT». اگر هم expires و هم max-age تنظیم شده باشد، max-age اولویت دارد.

  • httpOnly: اگر true، جاوا اسکریپت را از دسترسی به کوکی منع می‌کند.

  • max-age: تعداد ثانیه‌های باقی‌مانده تا منقضی شدن کوکی. عدد صفر یا منفی کوکی را فوراً منقضی می‌کند. اگر هر دو expires و max-age تنظیم شده باشند، max-age اولویت دارد.

  • path: مسیری که باید در نشانی وب درخواستی وجود داشته باشد، درغیراین‌صورت مرورگر سرصفحه Cookie را ارسال نخواهد کرد.

  • secure: اگر روی true تنظیم شده باشد، کوکی فقط زمانی به سرور ارسال می‌شود که درخواست از نقطه پایانی https: ایجاد شده باشد.

  • sameSite: تأکید می‌کند که کوکی نباید با درخواست‌های میان‌مبدئی ارسال شود. باید 'strict'،‏ 'lax'، یا 'none' باشد.

اجازه‌های مرتبط

set_cookie

setPixelResponse

بدنه پاسخ را روی GIF‏ ۱×۱ تنظیم می‌کند، سرایند Content-Type را روی «image/gif» تنظیم می‌کند، سرایندهای ذخیره‌سازی موقت را طوری تنظیم می‌کند که نماینده‌های کاربر پاسخ را در حافظه پنهان ذخیره نکنند، و وضعیت پاسخ را روی ۲۰۰ تنظیم می‌کند.

توجه داشته باشید که returnResponse باید برای پاسخ فراخوانی شود تا به مشتری برگردانده شود.

نحو

setPixelResponse();

اجازه‌های مرتبط

به اجازه access_response نیاز دارد. اجازه باید به‌گونه‌ای پیکربندی شود که حداقل به موارد زیر اجازه دسترسی دهد:

  • headers - باید کلیدهای زیر را مجاز کند
    • content-type
    • cache-control
    • expires
    • pragma
  • body
  • status

setResponseBody

بدنه پاسخ را روی آرگومان تنظیم می‌کند.

توجه داشته باشید که returnResponse باید برای پاسخ فراخوانی شود تا به مشتری برگردانده شود.

نحو

setResponseBody(body[, encoding]);

پارامترها

پارامتر نوع شرح
body رشته مقداری که باید به‌عنوان بدنه پاسخ تنظیم شود.
encoding رشته کدبندی نویسه بدنه پاسخ (به‌طور پیش‌فرض 'utf8'). مقادیر پشتیبانی‌شده شامل 'ascii'، 'utf8'، 'utf16le'، 'ucs2'، 'base64'، 'latin1'، 'binary'، و 'hex' است.

اجازه‌های مرتبط

به اجازه access_response نیاز دارد. اجازه باید به‌گونه‌ای پیکربندی شود که حداقل به موارد زیر اجازه دسترسی دهد:

  • body

setResponseHeader

سرصفحه‌ای را در پاسخی که برگردانده می‌شود تنظیم می‌کند. اگر سرصفحه‌ای با این نام (غیرحساس به حروف بزرگ و کوچک) قبلاً توسط این میانای برنامه‌سازی کاربردی تنظیم شده باشد، تماس بعدی مقدار تنظیم‌شده توسط تماس‌گیرنده قبلی را بازنویسی یا پاک خواهد کرد.

توجه داشته باشید که returnResponse باید برای پاسخ فراخوانی شود تا به مشتری برگردانده شود.

نحو

setResponseHeader(name, value);

پارامترها

پارامتر نوع شرح
name رشته نام سرایند. نام‌های سرایند HTTP حروف‌حساس نیستند، بنابراین نام سرایند با حروف کوچک نوشته خواهد شد.
value رشته تعریف‌نشده مقدار سرایند. اگر تهی یا تعریف‌نشده باشد، این کار سرایند نام‌گذاری‌شده را از پاسخی که برگردانده خواهد شد پاک می‌کند.

اجازه‌های مرتبط

به اجازه access_response نیاز دارد. اجازه باید به‌گونه‌ای پیکربندی شود که حداقل به موارد زیر اجازه دسترسی دهد:

  • headers

setResponseStatus

رمز وضعیت HTTP پاسخی را که برگردانده خواهد شد تنظیم می‌کند.

توجه داشته باشید که returnResponse باید برای پاسخ فراخوانی شود تا به مشتری برگردانده شود.

نحو

setResponseStatus(statusCode);

پارامترها

پارامتر نوع شرح
statusCode number رمز وضعیت HTTP که باید برگردانده شود.

اجازه‌های مرتبط

به اجازه access_response نیاز دارد. اجازه باید به‌گونه‌ای پیکربندی شود که حداقل به موارد زیر اجازه دسترسی دهد:

  • status

sha256

خلاصه SHA-256 ورودی را محاسبه می‌کند و یک فراخوانی برگشتی با خلاصه کدبندی‌شده در base64 را فراخوانی می‌کند، مگراینکه شیء options کدبندی خروجی متفاوتی را مشخص کند.

این امضا و رفتار میانای برنامه‌سازی کاربردی با میانای برنامه‌سازی کاربردی sha256 برای حامل‌های وب مطابقت دارد؛ بااین‌حال، «الگوهای سفارشی» در حامل‌های سرور باید از میانای برنامه‌سازی کاربردی 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 رشته رشته‌ای که باید درهم‌سازی شود.
onSuccess تابع با خلاصه حاصل، کدبندی‌شده در base64، فراخوانی می‌شود، مگراینکه شیء options کدبندی خروجی متفاوتی را مشخص کند.
options شیء شیء گزینه‌های اختیاری برای مشخص کردن کدبندی خروجی. درصورت مشخص شدن، شیء باید حاوی کلید outputEncoding با مقدار یکی از base64 یا hex باشد.

اجازه‌های مرتبط

هیچ‌کدام.

sha256Sync

خلاصه SHA-256 ورودی را که در مبنای ۶۴ کدبندی شده است محاسبه می‌کند و برمی‌گرداند، مگراینکه شیء options کدبندی خروجی دیگری را مشخص کند.

نمونه

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

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

نحو

sha256Sync(input, options = undefined);

پارامترها

پارامتر نوع شرح
input رشته رشته‌ای که باید درهم‌سازی شود.
options شیء شیء گزینه‌های اختیاری برای مشخص کردن کدبندی خروجی. درصورت مشخص شدن، شیء باید حاوی کلید outputEncoding با مقدار یکی از base64 یا hex باشد.

اجازه‌های مرتبط

هیچ‌کدام.

templateDataStorage

شیئی را با روش‌هایی برای دسترسی به فضای ذخیره‌سازی داده‌های الگو برمی‌گرداند. فضای ذخیره‌سازی داده الگو امکان هم‌رسانی داده‌ها را در سراسر اجراهای یک الگو فراهم می‌کند. داده‌های ذخیره‌شده در فضای ذخیره‌سازی داده‌های الگو در سرور اجراکننده محفظه باقی می‌ماند. در بیشتر موارد، چندین سرور درحال اجرای محفظه هستند، بنابراین ذخیره کردن داده‌ها در فضای ذخیره‌سازی داده‌های الگو تضمین نمی‌کند که هر درخواست بعدی به داده‌ها دسترسی داشته باشد.

«داده» در نام «templateDataStorage» به این واقعیت اشاره دارد که فقط انواع داده‌های ساده و غیرتابع را می‌توان بااستفاده از این API ذخیره کرد. هر تابع یا ارجاع به تابعی که به میانای برنامه‌سازی کاربردی ارسال شود، به‌جای آن به‌عنوان null ذخیره خواهد شد.

نحو

const templateDataStorage = require('templateDataStorage');

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

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

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

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

نمونه

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

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

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

اجازه‌های مرتبط

access_template_storage

testRegex

رشته‌ای را دربرابر عبارت باقاعده ایجادشده ازطریق میانای برنامه‌سازی کاربردی createRegex آزمایش می‌کند. اگر عبارت باقاعده مطابقت داشته باشد، 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 رشته رشته آزمایشی برای آزمایش.

اجازه‌های مرتبط

هیچ‌کدام.

toBase64

رشته‌ای را به‌صورت base64 یا base64url کدبندی می‌کند. به‌طور پیش‌فرض کدبندی base64 است.

نحو

toBase64(input, options);

پارامترها

پارامتر نوع شرح
input رشته رشته برای کدبندی کردن.
options شیء پیکربندی میانای برنامه‌سازی کاربردی اختیاری. (گزینه‌های زیر را ببینید.)

گزینه‌ها

گزینه نوع شرح حداقل نسخه
urlEncoding مقدار منطقی اگر درست باشد، نتیجه بااستفاده از قالب base64url کدبندی خواهد شد. 1.0.0

نمونه

const toBase64 = require('toBase64');

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

اجازه‌های مرتبط

هیچ‌کدام.

BigQuery

شیئی را برمی‌گرداند که عملکردهای BigQuery را ارائه می‌دهد.

تابع BigQuery.insert امکان نوشتن داده‌ها در جدول BigQuery را فراهم می‌کند. این روش یک promise برمی‌گرداند که درصورت درج موفقیت‌آمیز حل می‌شود یا درصورت بروز خطا رد می‌شود.

وقتی درج موفقیت‌آمیز باشد، وعده بدون هیچ آرگومانی حل می‌شود.

وقتی درج ناموفق باشد، وعده با فهرستی از اشیاء حاوی دلیل خطا و احتمالاً شیء ردیف درصورت وقوع خطا رد می‌شود. ممکن است بخشی از درخواست با موفقیت تکمیل شود، درحالی‌که بخش‌های دیگر تکمیل نشوند. در این حالت، promise با فهرستی از خطاها برای هر ردیف با یک شیء ردیف رد می‌شود تا به تشخیص ردیف‌های درج‌شده کمک کند (نمونه‌های خطا را در زیر ببینید). برای اطلاعات بیشتر، به اسناد 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 Array ردیف‌هایی که باید در جدول درج شود.
options شیء گزینه‌های درخواست اختیاری. گزینه‌های پشتیبانی‌شده عبارتند از: ignoreUnknownValues و skipInvalidRows. کلیدهای گزینه ناشناخته نادیده گرفته می‌شوند. (گزینه‌ها را در زیر ببینید.)

گزینه‌ها

پارامتر نوع شرح
ignoreUnknownValues مقدار منطقی اگر روی true تنظیم شده باشد، ردیف‌هایی را که حاوی مقادیری هستند که با طرحواره مطابقت ندارند بپذیرد. مقادیر ناشناخته نادیده گرفته می‌شوند. پیش‌فرض‌ها به false.
skipInvalidRows مقدار منطقی اگر روی 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 را ارائه می‌دهد.

این میانای برنامه‌سازی کاربردی فقط از Firestore در حالت بومی پشتیبانی می‌کند، نه Firestore در حالت Datastore. همچنین، این میانای برنامه‌سازی کاربردی فقط از پایگاه داده پیش‌فرض پشتیبانی می‌کند.

Firestore.read

تابع Firestore.read داده‌ها را از سند Firestore می‌خواند و قولی را برمی‌گرداند که به شیء حاوی دو کلید id و data تبدیل می‌شود. اگر سند وجود نداشته باشد، وعده با شیئی که حاوی کلید reason برابر با not_found است رد می‌شود.

نحو

Firestore.read(path[, options]);

پارامترها

پارامتر نوع شرح
path رشته مسیر سند یا مجموعه. نباید با «/» شروع یا تمام شود.
options شیء گزینه‌های درخواست اختیاری. گزینه‌های پشتیبانی‌شده عبارت‌اند از: projectId،‏ disableCache، و transaction. کلیدهای گزینه ناشناخته نادیده گرفته می‌شوند. (گزینه‌ها را در زیر ببینید.)

گزینه‌ها

پارامتر نوع شرح
projectId رشته اختیاری. شناسه پروژه Google Cloud Platform. اگر حذف شود، projectId از متغیر محیطی GOOGLE_CLOUD_PROJECT بازیابی می‌شود تا زمانی که access_firestore تنظیم اجازه برای شناسه پروژه روی * یا GOOGLE_CLOUD_PROJECT تنظیم شده باشد. اگر حامل سرور در Google Cloud اجرا می‌شود، GOOGLE_CLOUD_PROJECT ازقبل روی شناسه پروژه Google Cloud تنظیم شده است.
disableCache مقدار منطقی اختیاری. تعیین می‌کند که حافظه پنهان غیرفعال شود یا نه. ذخیره در حافظه نهان به‌طور پیش‌فرض فعال است و نتایج را برای مدت درخواست در حافظه نهان ذخیره می‌کند.
transaction رشته اختیاری. مقدار بازیابی‌شده از Firestore.runTransaction(). عملیات را برای استفاده در تراکنش علامت‌گذاری می‌کند.

نمونه

const Firestore = require('Firestore');

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

Firestore.write

تابع Firestore.write داده‌ها را در سند یا مجموعه Firestore می‌نویسد. اگر مسیر به یک مجموعه باشد، سندی با شناسه تولیدشده به‌صورت تصادفی ایجاد خواهد شد. اگر مسیر به یک سند باشد و آن سند وجود نداشته باشد، ایجاد خواهد شد. این میانای برنامه‌سازی کاربردی قولی را برمی‌گرداند که به شناسه سند اضافه‌شده یا اصلاح‌شده منتهی می‌شود. اگر از گزینه تراکنش استفاده شود، میانای برنامه‌سازی کاربردی همچنان یک promise برمی‌گرداند، اما حاوی شناسه نخواهد بود زیرا نوشتن‌ها به‌صورت دسته‌ای انجام می‌شود.

نحو

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

پارامترها

پارامتر نوع شرح
path رشته مسیر سند یا مجموعه. نباید با «/» شروع یا تمام شود.
input شیء مقداری که باید در سند نوشته شود. اگر گزینه ادغام تنظیم شده باشد، میانای برنامه‌سازی کاربردی کلیدها را از ورودی در سند ادغام خواهد کرد.
options شیء گزینه‌های درخواست اختیاری. گزینه‌های پشتیبانی‌شده عبارت‌اند از: projectId، merge، و transaction. کلیدهای گزینه ناشناخته نادیده گرفته می‌شوند. (گزینه‌ها را در زیر ببینید.)

گزینه‌ها

پارامتر نوع شرح
projectId رشته اختیاری. شناسه پروژه Google Cloud Platform. اگر حذف شود، projectId از متغیر محیطی GOOGLE_CLOUD_PROJECT بازیابی می‌شود تا زمانی که access_firestore تنظیم اجازه برای شناسه پروژه روی * یا GOOGLE_CLOUD_PROJECT تنظیم شده باشد. اگر حامل سرور در Google Cloud اجرا می‌شود، GOOGLE_CLOUD_PROJECT ازقبل روی شناسه پروژه Google Cloud تنظیم شده است.
merge مقدار منطقی اختیاری. اگر روی true تنظیم شده باشد، کلیدها را از ورودی در سند ادغام کنید، درغیراین‌صورت این روش کل سند را لغو خواهد کرد. پیش‌فرض‌ها به false.
transaction رشته اختیاری. مقدار بازیابی‌شده از Firestore.runTransaction(). عملیات را برای استفاده در تراکنش علامت‌گذاری می‌کند.

نمونه

const Firestore = require('Firestore');

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

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

Firestore.query

تابع Firestore.query مجموعه داده‌شده را پُرسمان می‌کند و قولی را برمی‌گرداند که به آرایه‌ای از اسناد Firestore که با شرایط پُرسمان مطابقت دارند حل می‌شود. شیء سند Firestore همان است که در بالا در Firestore.read فهرست شده است. اگر هیچ سندی با شرایط پُرسمان مطابقت نداشته باشد، قول برگردانده‌شده به آرایه خالی تبدیل می‌شود.

نحو

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

پارامترها

پارامتر نوع شرح
collection رشته مسیر مجموعه. نباید با «/» شروع یا تمام شود.
queryConditions Array آرایه‌ای از شرایط پُرسمان. هر پُرسمان به‌صورت آرایه‌ای با سه مقدار ارائه می‌شود: key، operator، و expectedValue. E.g.: [[‘id’, ‘<’, ‘5’], [‘state’, ‘==’, ‘CA’]].

شرایط باهم ترکیب می‌شوند تا نتیجه پُرسمان ایجاد شود. لطفاً برای مشاهده فهرست عملگرهای پُرسمان سازگار، به عملگرهای پُرسمان Firestore مراجعه کنید.
options شیء گزینه‌های درخواست اختیاری. گزینه‌های پشتیبانی‌شده عبارت‌اند از: projectId،‏ disableCache، limit، و transaction. کلیدهای گزینه ناشناخته نادیده گرفته می‌شوند. (گزینه‌ها را در زیر ببینید.)

گزینه‌ها

پارامتر نوع شرح
projectId رشته اختیاری. شناسه پروژه Google Cloud Platform. اگر حذف شود، projectId از متغیر محیطی GOOGLE_CLOUD_PROJECT بازیابی می‌شود تا زمانی که access_firestore تنظیم اجازه برای شناسه پروژه روی * یا GOOGLE_CLOUD_PROJECT تنظیم شده باشد. اگر حامل سرور در Google Cloud اجرا می‌شود، GOOGLE_CLOUD_PROJECT ازقبل روی شناسه پروژه Google Cloud تنظیم شده است.
disableCache مقدار منطقی اختیاری. تعیین می‌کند که حافظه پنهان غیرفعال شود یا نه. ذخیره در حافظه نهان به‌طور پیش‌فرض فعال است و نتایج را برای مدت درخواست در حافظه نهان ذخیره می‌کند.
limit number اختیاری. حداکثر تعداد نتایج برگردانده‌شده توسط پُرسمان را تغییر می‌دهد، مقدار پیش‌فرض ۵ است.
transaction رشته اختیاری. مقدار بازیابی‌شده از Firestore.runTransaction(). عملیات را برای استفاده در تراکنش علامت‌گذاری می‌کند.

نمونه

const Firestore = require('Firestore');

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

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

Firestore.runTransaction

تابع Firestore.runTransaction به کاربر اجازه می‌دهد به‌صورت اتمی از Firestore بخواند و در آن بنویسد. اگر نوشتن هم‌زمان یا تداخل تراکنش دیگری رخ دهد، تراکنش تا دو بار تکرار خواهد شد. اگر پس‌از سه تلاش ناموفق باشد، API با خطا رد خواهد شد. این API یک promise برمی‌گرداند که درصورت موفقیت‌آمیز بودن تراکنش، به آرایه‌ای از شناسه‌های سند برای هر عملیات نوشتن تبدیل می‌شود، و درصورت ناموفق بودن، با خطا رد می‌شود.

نحو

Firestore.runTransaction(callback[, options]);

پارامترها

پارامتر نوع شرح
callback تابع فراخوانی که با شناسه تراکنش رشته‌ای فراخوانی می‌شود. شناسه تراکنش را می‌توان به فراخوانی‌های API خواندن/ نوشتن/ پُرسمان منتقل کرد. این تابع بازخوانی باید یک promise برگرداند. فراخوانی برگشتی ممکن است تا سه بار قبل‌از ناموفق شدن اجرا شود.
options شیء گزینه‌های درخواست اختیاری. تنها گزینه پشتیبانی‌شده projectId است. کلیدهای گزینه ناشناخته نادیده گرفته می‌شوند. (گزینه‌ها را در زیر ببینید.)

گزینه‌ها

پارامتر نوع شرح
projectId رشته اختیاری. شناسه پروژه Google Cloud Platform. اگر حذف شود، projectId از متغیر محیطی GOOGLE_CLOUD_PROJECT بازیابی می‌شود تا زمانی که access_firestore تنظیم اجازه برای شناسه پروژه روی * یا GOOGLE_CLOUD_PROJECT تنظیم شده باشد. اگر حامل سرور در Google Cloud اجرا می‌شود، GOOGLE_CLOUD_PROJECT ازقبل روی شناسه پروژه Google Cloud تنظیم شده است.

نمونه

const Firestore = require('Firestore');

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

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

نمونه خطا

خطاهای موجود در هر تابع Firestore با شیئی که حاوی کلید reason است رد خواهد شد:

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

دلایل خطا می‌تواند شامل کدهای خطای Firestore REST API باشد اما محدود به آن‌ها نیست.

اجازه‌های مرتبط

access_firestore

JSON

شیئی را برمی‌گرداند که توابع JSON را ارائه می‌دهد.

تابع parse() رشته JSON را تجزیه می‌کند تا مقدار یا شیء توصیف‌شده توسط رشته را بسازد. اگر مقدار تجزیه نشود (مثلاً JSON بدشکل)، تابع undefined را برمی‌گرداند. اگر مقدار ورودی رشته نباشد، ورودی به رشته تبدیل می‌شود.

تابع stringify() ورودی را به رشته JSON تبدیل می‌کند. اگر مقدار قابل تجزیه نباشد (مثلاً شیء دارای چرخه باشد)، روش undefined را برمی‌گرداند.

نمونه

const JSON = require('JSON');

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

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

نحو

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

اجازه‌های مرتبط

هیچ‌کدام.

Math

شیئی که توابع Math را ارائه می‌دهد.

نحو

const Math = require('Math');

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

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

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

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

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

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

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

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

پارامترها

پارامترهای تابع ریاضی به عدد تبدیل می‌شوند.

اجازه‌های مرتبط

هیچ‌کدام.

Messages

میاناهای برنامه‌سازی کاربردی زیر باهم کار می‌کنند تا امکان انتقال پیام بین بخش‌های مختلف یک محفظه را فراهم کنند.

addMessageListener

تابعی اضافه می‌کند که به پیام از نوع خاصی گوش می‌دهد. وقتی پیامی از آن نوع بااستفاده از میانای برنامه‌سازی کاربردی sendMessage ارسال می‌شود (معمولاً توسط برچسب)، فراخوانی برگشتی به‌صورت همگام اجرا خواهد شد. فراخوانی با دو پارامتر اجرا می‌شود:

  1. messageType:string
  2. message:Object

اگر فراخوان در کارخواه اضافه شود، فراخوان پیام‌ها را در سراسر همه رویدادهایی که کارخواه ایجاد می‌کند دریافت خواهد کرد. اگر callback باید پیام‌ها را فقط از رویداد خاصی دریافت کند، این API را بااستفاده از bindToEvent در تابع onStart مربوط به runContainer API به رویداد متصل کنید. مثال را ببینید.

نحو

const addMessageListener = require('addMessageListener');

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

پارامترها

پارامتر نوع شرح
messageType رشته نوع پیام برای گوش دادن. اگر مقدار رشته نباشد، به رشته تبدیل می‌شود.
callback تابع فراخوانی برگشتی برای اجرا شدن هنگام ارسال پیام از نوع پیام قابل‌اجرا. اگر کال‌بک تابع نباشد، میانای برنامه‌سازی کاربردی کاری انجام نخواهد داد.

نمونه

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

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

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

اجازه‌های مرتبط

به اجازه use_message نیاز دارد. اجازه باید به‌گونه‌ای پیکربندی شود که حداقل این موارد را مجاز کند:

  • نوع پیام با Usage از listen یا listen_and_send.

hasMessageListener

اگر شنونده پیام برای نوع پیام داده‌شده اضافه شده باشد، مقدار «درست» را برمی‌گرداند. درغیراین‌صورت نادرست را برمی‌گرداند.

نحو

const hasMessageListener = require('hasMessageListener');

hasMessageListener('send_pixel');

اجازه‌های مرتبط

هیچ‌کدام.

sendMessage

پیامی از نوع مشخص‌شده به شنونده ثبت‌شده ارسال می‌کند. از این مورد می‌توان برای ارسال پیام از برچسب به کارخواهی که محفظه را اجرا کرده است استفاده کرد.

نحو

const sendMessage = require('sendMessage');

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

پارامترها

پارامتر نوع شرح
messageType رشته نوع پیام برای ارسال. اگر مقدار رشته نباشد، به رشته تبدیل می‌شود.
message شیء پیام برای ارسال. اگر پیام شیء نباشد، API کاری انجام نخواهد داد.

اجازه‌های مرتبط

به اجازه use_message نیاز دارد. اجازه باید به‌گونه‌ای پیکربندی شود که حداقل این موارد را مجاز کند:

  • نوع پیام با Usage از listen_and_send یا send.

Object

شیئی را برمی‌گرداند که روش‌های Object را ارائه می‌دهد.

روش keys() رفتار Object.keys() «کتابخانه استاندارد» را ارائه می‌دهد. این متد آرایه‌ای از نام‌های ویژگی‌های قابل‌شمارش خود شیء داده‌شده را به همان ترتیبی که یک حلقه for...in... انجام می‌دهد، برمی‌گرداند. اگر مقدار ورودی شیء نباشد، به شیء تبدیل می‌شود.

روش values() رفتار Object.values() «کتابخانه استاندارد» را ارائه می‌دهد. آرایه‌ای از مقادیر ویژگی قابل‌شمارش خود شیء داده‌شده را به همان ترتیبی که حلقه for...in... انجام می‌دهد برمی‌گرداند. اگر مقدار ورودی شیء نباشد، به شیء تبدیل می‌شود.

روش entries() رفتار Object.entries() «کتابخانه استاندارد» را ارائه می‌دهد. آرایه‌ای از جفت‌های [key, value] ویژگی قابل‌شمارش خود شیء داده‌شده را با همان ترتیبی که حلقه for...in... انجام می‌دهد برمی‌گرداند. اگر مقدار ورودی شیء نباشد، به شیء تبدیل می‌شود.

روش freeze() رفتار Object.freeze() «کتابخانه استاندارد» را ارائه می‌دهد. شیء ثابت‌شده دیگر قابل‌تغییر نیست؛ ثابت کردن شیء مانع از اضافه شدن ویژگی‌های جدید به آن، برداشته شدن ویژگی‌های موجود، و تغییر مقادیر ویژگی‌های موجود می‌شود. ‫freeze() همان شیء را که ارسال شده است برمی‌گرداند. با آرگومان اولیه یا تهی طوری رفتار می‌شود که گویی شیء ثابتی است و برگردانده خواهد شد.

روش delete() رفتار عملگر حذف «کتابخانه استاندارد» را ارائه می‌دهد. کلید داده‌شده را از شیء برمی‌دارد، مگراینکه شیء ثابت شده باشد. مانند عملگر حذف Standard Library، اگر مقدار ورودی اول (objectInput) شیئی باشد که ثابت نشده است، true را برمی‌گرداند، حتی اگر مقدار ورودی دوم (keyToDelete) کلیدی را مشخص کند که وجود ندارد. در همه موارد دیگر، false را برمی‌گرداند. بااین‌حال، این عملگر از عملگر حذف «کتابخانه استاندارد» به روش‌های زیر متفاوت است:

  • keyToDelete نمی‌تواند رشته‌ای با جداکننده نقطه باشد که کلید تودرتو را مشخص می‌کند.
  • نمی‌توان از delete() برای برداشتن عناصر از آرایه استفاده کرد.
  • از delete() نمی‌توان برای برداشتن هیچ‌یک از ویژگی‌ها از دامنه جهانی استفاده کرد.

نحو

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

پارامترها

Object.keys

پارامتر نوع شرح
objectInput any شیئی که کلیدهای آن باید شمارش شود. اگر ورودی شیء نباشد، به شیء تبدیل خواهد شد.

Object.values

پارامتر نوع شرح
objectInput any شیئی که مقادیر آن باید شمارش شود. اگر ورودی شیء نباشد، به شیء تبدیل خواهد شد.

Object.entries

پارامتر نوع شرح
objectInput any شیئی که جفت‌های کلید/مقدار آن باید شمارش شود. اگر ورودی شیء نباشد، به شیء تبدیل می‌شود.

Object.freeze

پارامتر نوع شرح
objectInput any شیء موردنظر برای ثابت کردن. اگر ورودی شیء نباشد، به‌عنوان شیء ثابت درنظر گرفته می‌شود.

Object.delete

پارامتر نوع شرح
objectInput any شیئی که کلید آن حذف می‌شود.
keyToDelete رشته کلید سطح بالا برای حذف.

نمونه

const Object = require('Object');

// The keys of an object are enumerated in an array.
const keys = Object.keys({foo: 'bar'});

// The values of an object are enumerated in an array.
const values = Object.values({foo: 'bar'});

// The key/value pairs of an object are enumerated in an array.
const entries = Object.entries({foo: 'bar'});

// The input object is frozen.
const frozen = Object.freeze({foo: 'bar'});

// The key is removed from the input object.
const obj1 = {deleteme: 'value'};
Object.delete(obj1, 'deleteme');
// Only a top-level key can be specified as the key to delete.
const obj2 = {nested: {key: 'value'}};
Object.delete(obj2, 'nested.key'); // This has no effect.
Object.delete(obj2.nested, 'key'); // This deletes the nested key.

Promise

شیئی را برمی‌گرداند که روش‌هایی برای تعامل با وعده‌ها ارائه می‌دهد.

«قول‌ها» ازنظر عملکردی معادل قول‌های جاوا اسکریپت هستند. هر نمونه سه روش دارد که یک Promise را برمی‌گرداند که امکان اقدام بیشتر را هنگام تسویه Promise فراهم می‌کند:

  • .then() - هم پرونده‌های حل‌شده و هم پرونده‌های ردشده را مدیریت می‌کند. این تابع دو فراخوانی برگشتی را به‌عنوان پارامتر می‌پذیرد: یکی برای حالت موفقیت و دیگری برای حالت شکست.
  • .catch() - فقط به پرونده‌های ردشده رسیدگی می‌کند. یک فراخوانی برگشتی را به‌عنوان پارامتر می‌گیرد.
  • .finally() - روشی برای اجرای کد ارائه می‌دهد، چه وعده حل شده باشد یا رد شده باشد. یک پاسخ تماس را به‌عنوان پارامتری می‌گیرد که بدون هیچ استدلالی فراخوانی می‌شود.

متغیری که یک promise را برمی‌گرداند برابر با مقدار حل‌شده promise است، یا false اگر promise رد شود.

نمونه

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 Array آرایه‌ای از مقادیر یا وعده‌ها. اگر ورودی یک promise نباشد، ورودی به‌گونه‌ای منتقل می‌شود که گویی مقدار حل‌شده یک promise است. اگر ورودی آرایه نباشد، خطا می‌دهد.

نمونه

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

یک promise ایجاد می‌کند که ازنظر عملکردی معادل یک promise جاوا اسکریپت است.

نحو

Promise.create(resolver);

پارامترها

پارامتر نوع شرح
resolver تابع تابعی که با دو تابع فراخوانی می‌شود -- حل کردن و رد کردن. وقتی پارامتر مربوطه فراخوانی شود، وعده برگشتی حل یا رد خواهد شد. اگر حل‌کننده تابع نباشد، خطا ایجاد می‌کند.

نمونه

const Promise = require('Promise');

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

اجازه‌های مرتبط

هیچ‌کدام.

میاناهای برنامه‌سازی کاربردی آزمایشی

این میاناهای برنامه‌سازی کاربردی با آزمایش‌های جاوا اسکریپت جعبه امن کار می‌کنند تا آزمایش‌هایی برای الگوهای سفارشی در Google Tag Manager بسازند. این میاناهای برنامه‌سازی کاربردی آزمایشی به بیانیه require() نیاز ندارند. [درباره آزمایش‌های الگو سفارشی بیشتر بدانید].

assertApi

یک شیء تطبیق‌دهنده برمی‌گرداند که می‌تواند برای ایجاد ادعاهای روان درباره API داده‌شده استفاده شود.

نحو

assertApi(apiName)

پارامترها

پارامتر نوع شرح
apiName رشته نام api برای بررسی؛ همان رشته‌ای که به require() ارسال شده است.

تطبیق‌دهنده‌ها

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

نمونه‌ها

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

assertThat

assertThat API از کتابخانه [Truth] Google الگوبرداری شده است. این متد شیئی را برمی‌گرداند که می‌توان از آن برای ایجاد ادعاهای روان درباره مقدار موضوع استفاده کرد. شکست ادعا بلافاصله آزمایش را متوقف می‌کند و آن را به‌عنوان ناموفق علامت‌گذاری می‌کند. بااین‌حال، شکست در یک آزمایش بر سایر چارچوب‌های تست تأثیر نخواهد گذاشت.

نحو

assertThat(actual, opt_message)

پارامترها

پارامتر نوع شرح
actual any مقداری که باید در بررسی‌های روان استفاده شود.
opt_message رشته پیام اختیاری برای چاپ درصورت ناموفق بودن ادعا.

تطبیق‌دهنده‌ها

تطبیق‌دهنده شرح
isUndefined() ادعا می‌کند که موضوع undefined است.
isDefined() ادعا می‌کند که موضوع undefined نیست.
isNull() ادعا می‌کند که موضوع null است.
isNotNull() ادعا می‌کند که موضوع null نیست.
isFalse() ادعا می‌کند که موضوع false است.
isTrue() ادعا می‌کند که موضوع true است.
isFalsy() ادعا می‌کند که موضوع نادرست است. مقادیر نادرست عبارت‌اند از undefined، null، false، NaN، 0، و '' (رشته خالی).
isTruthy() ادعا می‌کند که موضوع درست است. مقادیر نادرست عبارت‌اند از undefined، null، false، NaN، 0، و '' (رشته خالی).
isNaN() ادعا می‌کند که موضوع مقدار NaN است.
isNotNaN() ادعا می‌کند که موضوع هر مقداری به‌جز NaN است.
isInfinity() ادعا می‌کند که موضوع بی‌نهایت مثبت یا منفی است.
isNotInfinity() ادعا می‌کند که موضوع هر مقداری به‌جز بی‌نهایت مثبت یا منفی است.
isEqualTo(expected) ادعا می‌کند که موضوع با مقدار داده‌شده برابر است. این مقایسه مقدار است، نه مقایسه مرجع. محتوای اشیاء و آرایه‌ها به‌صورت بازگشتی مقایسه می‌شوند.
isNotEqualTo(expected) تأیید می‌کند که موضوع با مقدار داده‌شده برابر نیست. این مقایسه مقدار است، نه مقایسه مرجع. محتوای اشیاء و آرایه‌ها به‌صورت بازگشتی مقایسه می‌شوند.
isAnyOf(...expected) ادعا می‌کند که موضوع با یکی از مقادیر داده‌شده برابر است. این مقایسه مقدار است، نه مقایسه مرجع. محتوای اشیاء و آرایه‌ها به‌صورت بازگشتی مقایسه می‌شوند.
isNoneOf(...expected) ادعا می‌کند که موضوع با هیچ‌یک از مقادیر داده‌شده برابر نیست. این مقایسه مقدار است، نه مقایسه مرجع. محتوای اشیاء و آرایه‌ها به‌صورت بازگشتی مقایسه می‌شوند.
isStrictlyEqualTo(expected) ادعا می‌کند که موضوع دقیقاً برابر (===) با مقدار داده‌شده است.
isNotStrictlyEqualTo(expected) ادعا می‌کند که موضوع دقیقاً برابر (!==) با مقدار داده‌شده نیست.
isGreaterThan(expected) ادعا می‌کند که موضوع در مقایسه مرتب‌شده بزرگ‌تر از (>) مقدار داده‌شده است.
isGreaterThanOrEqualTo(expected) ادعا می‌کند که فاعل بزرگ‌تر یا مساوی با (>=) مقدار داده‌شده در مقایسه مرتب‌شده است.
isLessThan(expected) ادعا می‌کند که موضوع در مقایسه مرتب‌شده کمتر از (<) مقدار داده‌شده است.
isLessThanOrEqualTo(expected) ادعا می‌کند که فاعل کمتر یا مساوی (<=) مقدار داده‌شده در مقایسه مرتب‌شده است.
contains(...expected) ادعا می‌کند که موضوع آرایه یا رشته‌ای است که حاوی همه مقادیر داده‌شده به هر ترتیبی است. این مقایسه مقدار است، نه مقایسه مرجع. محتوای اشیاء و آرایه‌ها به‌صورت بازگشتی مقایسه می‌شود.
doesNotContain(...expected) تأیید می‌کند که موضوع یک آرایه یا رشته است که هیچ‌یک از مقادیر داده‌شده را ندارد. این مقایسه مقدار است، نه مقایسه مرجع. محتوای اشیاء و آرایه‌ها به‌صورت بازگشتی مقایسه می‌شوند.
containsExactly(...expected) ادعا می‌کند که موضوع آرایه‌ای است که شامل همه مقادیر داده‌شده به هر ترتیبی است و هیچ مقدار دیگری ندارد. این مقایسه مقدار است، نه مقایسه مرجع. محتوای اشیاء و آرایه‌ها به‌صورت بازگشتی مقایسه می‌شود.
doesNotContainExactly(...expected) ادعا می‌کند که موضوع آرایه‌ای است که حاوی مجموعه متفاوتی از مقادیر نسبت به مقادیر داده‌شده به هر ترتیبی است. این مقایسه مقدار است، نه مقایسه مرجع. محتوای اشیاء و آرایه‌ها به‌صورت بازگشتی مقایسه می‌شود.
hasLength(expected) تأیید می‌کند که موضوع آرایه یا رشته‌ای با طول مشخص‌شده است. اگر مقدار آرایه یا رشته نباشد، ادعا همیشه رد می‌شود.
isEmpty() ادعا می‌کند که موضوع یک آرایه یا رشته خالی است (طول = ۰). اگر مقدار آرایه یا رشته نباشد، ادعا همیشه ناموفق است.
isNotEmpty() ادعا می‌کند که موضوع آرایه یا رشته‌ای است که خالی نیست (طول > 0). اگر مقدار آرایه یا رشته نباشد، ادعا همیشه رد می‌شود.
isArray() ادعا می‌کند که نوع موضوع آرایه است.
isBoolean() ادعا می‌کند که نوع موضوع بولی است.
isFunction() ادعا می‌کند که نوع موضوع تابع است.
isNumber() ادعا می‌کند که نوع موضوع عدد است.
isObject() ادعا می‌کند که نوع موضوع یک شیء است.
isString() ادعا می‌کند که نوع موضوع رشته است.

نمونه‌ها

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

fail

فوراً آزمایش فعلی را ناموفق می‌کند و پیام ارائه‌شده را (درصورت وجود) چاپ می‌کند.

نحو

fail(opt_message);

پارامترها

پارامتر نوع شرح
opt_message رشته نوشتار پیام خطای اختیاری.

نمونه

fail('This test has failed.');

mock

mock API به شما امکان می‌دهد رفتار Sandboxed APIs را لغو کنید. استفاده از API ساختگی در کد الگو ایمن است، اما فقط در حالت آزمایشی کار می‌کند. قبل‌از اجرای هر آزمایش، شبیه‌سازی‌ها بازنشانی می‌شوند.

نحو

mock(apiName, returnValue);

پارامترها

پارامتر نوع شرح
apiName رشته نام API برای شبیه‌سازی؛ همان رشته‌ای که به require() ارسال شده است
returnValue any مقداری که برای API یا تابع فراخوانی‌شده به‌جای API برگردانده می‌شود. اگر returnValue تابع باشد، آن تابع به‌جای Sandboxed API فراخوانده می‌شود؛ اگر returnValue هر چیزی به‌جز تابع باشد، آن مقدار به‌جای Sandboxed API برگردانده می‌شود.

نمونه‌ها

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

mockObject

mockObject API به شما امکان می‌دهد رفتار Sandboxed API را که شیء برمی‌گرداند لغو کنید. استفاده از این API در کد الگو ایمن است، اما فقط در حالت آزمایشی قابل اجرا است. قبل‌از اجرای هر آزمایش، شبیه‌سازی‌ها بازنشانی می‌شوند.

نحو

mockObject(apiName, objectMock);

پارامترها

پارامتر نوع شرح
apiName رشته نام API برای شبیه‌سازی؛ همان رشته‌ای که به require() ارسال شده است
objectMock شیء مقداری که برای API یا تابع فراخوانی‌شده به‌جای API برگردانده می‌شود. باید شیء باشد.

نمونه‌ها

const storage = {};
let firestoreId = 1;

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

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

runCode

کد الگو، یعنی محتوای برگه کد، را در محیط آزمایشی فعلی با شیء داده ورودی مشخص اجرا می‌کند.

نحو

runCode(data)

پارامترها

پارامتر نوع شرح
data شیء مورد داده‌ای که باید در آزمایش استفاده شود.

برگرداندن مقدار

مقدار متغیر را برای الگوهای متغیر برمی‌گرداند؛ برای همه انواع الگوهای دیگر، undefined را برمی‌گرداند.

نمونه

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