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

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

addEventCallback

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

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

نحو

const addEventCallback = require('addEventCallback');

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

پارامترها

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

مثال

در کارخواه:

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)

پارامترها

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

هیچ‌کدام.

claimRequest

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

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

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

مثال

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

پارامترها

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

هیچ‌کدام.

createRegex

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

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

این 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);

پارامترها

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

هیچ‌کدام.

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

2.0.0

decodeUri

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

نمونه

const decodeUri = require('decodeUri');

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

نحو

decodeUri(encoded_uri);

پارامترها

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

هیچ‌کدام.

decodeUriComponent

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

نمونه

const decodeUriComponent = require('decodeUriComponent');

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

نحو

decodeUriComponent(encoded_uri_component);

پارامترها

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

هیچ‌کدام.

encodeUri

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

نمونه

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

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

نحو

encodeUri(uri);

پارامترها

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

هیچ‌کدام.

encodeUriComponent

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

مثال

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

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

نحو

encodeUriComponent(str);

پارامترها

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

هیچ‌کدام.

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

پارامترها

مثال

const fromBase64 = require('fromBase64');

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

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

هیچ‌کدام.

generateRandom

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

نمونه

const generateRandom = require('generateRandom');

const randomValue = generateRandom(0, 10000000);

نحو

generateRandom(min, max);

پارامترها

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

هیچ‌کدام.

getAllEventData

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

نحو

getAllEventData();

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

read_event_data

getClientName

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

نحو

getClientName();

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

read_container_data

getContainerVersion

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

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

نمونه

const getContainerVersion = require('getContainerVersion');

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

نحو

getContainerVersion();

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

read_container_data

getCookieValues

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

مثال

const getCookieValues = require('getCookieValues');

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

نحو

getCookieValues(name[, noDecode]);

پارامترها

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

get_cookies

getEventData

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

مثال

const getEventData = require('getEventData');

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

پارامترها

نحو

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

پارامترها

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

به اجازه 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]);

پارامترها

گزینه‌ها

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

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

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

• مجاز کردن Google Domains

getRemoteAddress

با خواندن سرایندهای درخواست مثل «بازارسال‌شده» و «بازارسال‌شده برای»، نمایش رشته‌ای نشانی IP را که درخواست از آنجا سرچشمه گرفته است برمی‌گرداند، برای نمونه 12.345.67.890 برای IPv4 یا 2001:0db8:85a3:0:0:8a2e:0370:7334 برای IPv6. توجه: این 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);

پارامترها

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

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

پارامترها

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

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

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

نمونه

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

پارامترها

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

هیچ‌کدام.

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)

پارامترها

گزینه‌ها

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

use_custom_private_keys

پایین‌ترین نسخه تصویر

۱.۰.۰

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

پارامترها

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

هیچ‌کدام.

makeNumber

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

نحو

makeNumber(value);

پارامترها

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

هیچ‌کدام.

makeString

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

نحو

makeString(value);

پارامترها

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

هیچ‌کدام.

makeTableMap

شیء جدول ساده‌ای را با دو ستون به Map تبدیل می‌کند. از این برای تغییر فیلد الگوی SIMPLE_TABLE با دو ستون به قالبی قابل‌مدیریت‌تر استفاده می‌شود.

برای مثال، این تابع می‌تواند شیء جدول را تبدیل کند:

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

در نقشه:

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

یک شیء برمی‌گرداند: Map تبدیل‌شده جفت‌های کلید-مقدار به آن اضافه شده است، یا درغیراین‌صورت null.

نحو

makeTableMap(tableObj, keyColumnName, valueColumnName);

پارامترها

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

هیچ‌کدام.

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

پارامترها

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

هیچ‌کدام.

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

پارامترها

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

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

پارامترها

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

به اجازه 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]);

پارامترها

گزینه‌ها

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

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

پارامترها

گزینه‌ها

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

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)

پارامترها

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

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

پارامترها

گزینه‌ها

• 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 را ارسال نخواهد کرد.

• امن: اگر روی 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]);

پارامترها

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

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

• body

setResponseHeader

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

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

نحو

setResponseHeader(name, value);

پارامترها

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

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

• headers

setResponseStatus

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

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

نحو

setResponseStatus(statusCode);

پارامترها

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

به اجازه 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);

پارامترها

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

هیچ‌کدام.

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

پارامترها

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

هیچ‌کدام.

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

پارامترها

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

هیچ‌کدام.

toBase64

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

نحو

toBase64(input, options);

پارامترها

گزینه‌ها

نمونه

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

پارامترها

گزینه‌ها

نمونه‌های خطا

خطای پیدا نشدن واحد به این معنی است که احتمالاً نسخه قدیمی‌تری از تصویر ما در سراسر سرور شما اجرا می‌شود که هنوز واحد BigQuery را دربرنگرفته است. لطفاً محتوی سرورتان را با همان تنظیمات بااستفاده از دستورگان پیاده‌سازی ما دوباره پیاده‌سازی کنید. پس‌از اتمام عملیات، این ماژول به‌طور خودکار اضافه خواهد شد.

خطای غیردرج معمولاً یک شیء خطا با کلید reason دارد:

[{reason: 'invalid'}]

خطای درج می‌تواند شامل چندین شیء خطا با یک آرایه errors و یک شیء row باشد. در زیر نمونه‌ای از پاسخ خطا برای درج دو ردیف که فقط یکی از آن‌ها خطا دارد آورده شده است:

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

نمونه

const BigQuery = require('BigQuery');

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

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

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

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

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

access_bigquery

Firestore

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

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

Firestore.read

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

نحو

Firestore.read(path[, options]);

پارامترها

گزینه‌ها

نمونه

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

نحو

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

پارامترها

گزینه‌ها

نمونه

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

پارامترها

گزینه‌ها

نمونه

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

پارامترها

گزینه‌ها

نمونه

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

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

نحو

const addMessageListener = require('addMessageListener');

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

پارامترها

نمونه

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

پارامترها

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

به اجازه 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) شیئی باشد که ثابت نشده است، حتی اگر مقدار ورودی دوم (keyToDelete) کلیدی را مشخص کند که وجود ندارد، true را برمی‌گرداند. در همه موارد دیگر، false را برمی‌گرداند. بااین‌حال، این عملگر با عملگر حذف «کتابخانه استاندارد» در موارد زیر تفاوت دارد:

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

نحو

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

پارامترها

Object.keys

Object.values

Object.entries

Object.freeze

Object.delete

نمونه

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

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

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

• .then() - هم پرونده‌های حل‌شده و هم پرونده‌های ردشده را مدیریت می‌کند. دو بازخوان به‌عنوان پارامتر می‌گیرد: یکی برای حالت موفقیت و یکی برای حالت شکست.
• .catch() - فقط به موارد ردشده رسیدگی می‌کند. یک تماس برگشتی را به‌عنوان پارامتر می‌گیرد.
• .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);

پارامترها

مثال

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.create(resolver);

پارامترها

نمونه

const Promise = require('Promise');

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

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

هیچ‌کدام.

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

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

assertApi

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

نحو

assertApi(apiName)

پارامترها

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

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

پارامترها

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

نمونه‌ها

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

پارامترها

مثال

fail('This test has failed.');

mock

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

نحو

mock(apiName, returnValue);

پارامترها

نمونه‌ها

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

mockObject

میانای برنامه‌سازی کاربردی mockObject به شما امکان می‌دهد رفتار «میاناهای برنامه‌سازی کاربردی در جعبه شنی» را که شیئی را برمی‌گردانند ملغی کنید. استفاده از این میانای برنامه‌سازی کاربردی در کد الگو ایمن است، اما فقط در حالت آزمایشی قابل‌استفاده است. پیش‌از اجرای هر آزمایش، شبیه‌سازی‌ها بازنشانی می‌شوند.

نحو

mockObject(apiName, objectMock);

پارامترها