واجهات برمجة التطبيقات لوضع العلامات من جهة الخادم

يوضح هذا المستند واجهات برمجة التطبيقات لوضع العلامات من جهة الخادم.

addEventCallback

يسجِّل دالة معاودة الاتصال التي سيتم استدعاؤها في نهاية الحدث. سيتم استدعاء معاودة الاتصال عند تنفيذ جميع العلامات للحدث. يتم تمرير قيمة معاودة الاتصال وهما: معرّف الحاوية التي تستدعي الدالة وكائنًا يحتوي على معلومات حول الحدث.

وعند استخدام واجهة برمجة التطبيقات هذه في علامة، يتم ربطها بالحدث الحالي. عند استخدام واجهة برمجة التطبيقات هذه في برنامج، يجب أن تكون مرتبطة بحدث معيّن باستخدام دالة bindToEvent في واجهة برمجة تطبيقات runContainer. راجِع المثال لمزيد من التفاصيل.

البنية

const addEventCallback = require('addEventCallback');

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

المَعلمات

المَعلمة النوع الوصف
callback الوظيفة الدالة المطلوب استدعاؤها في نهاية الحدث.

يتضمّن الكائن eventData البيانات التالية:

اسم المفتاح النوع الوصف
tags مصفوفة مصفوفة من عناصر بيانات العلامة. وتحتوي كل علامة يتم تنشيطها أثناء الحدث على إدخال في هذه المصفوفة. يحتوي عنصر بيانات العلامة على رقم تعريف العلامة (id)، وحالة التنفيذ (status)، ووقت التنفيذ (executionTime). وستتضمّن بيانات العلامة أيضًا البيانات الوصفية الإضافية للعلامة التي تم ضبطها في العلامة.

في أحد العملاء:

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

claimRequest();

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

في إحدى العلامات:

const addEventCallback = require('addEventCallback');

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

الأذونات المرتبطة

read_event_metadata

callLater

تعمل هذه السياسة على جدولة استدعاء دالة ليظهر بشكل غير متزامن. سيتم استدعاء الدالة بعد إرجاع التعليمة البرمجية الحالية. يعادل ذلك setTimeout(<function>, 0).

مثال

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

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

البنية

callLater(function)

المَعلمات

المَعلمة النوع الوصف
function الوظيفة الدالة المطلوب استدعاءها.

الأذونات المرتبطة

بلا عُري

claimRequest

استخدام واجهة برمجة التطبيقات هذه في العميل للمطالبة بالطلب. بعد المطالبة بأحد الطلبات، لا تقوم الحاوية بتشغيل عملاء إضافيين.

تعرِض واجهة برمجة التطبيقات هذه استثناءً إذا تم طلبها في علامة أو متغيّر. وتطرح واجهة برمجة التطبيقات هذه استثناءً في حال استدعائها بعد رجوع العميل إلى الموقع الإلكتروني (مثلاً، في حال استدعائها في استدعاء غير متزامن، كما في callLater أو دالة onComplete لبرامج runContainer).

على العميل المطالبة بالطلب باستخدام واجهة برمجة التطبيقات هذه قبل طلب واجهة برمجة تطبيقات runContainer.

مثال

const claimRequest = require('claimRequest');

claimRequest();

البنية

claimRequest();

الأذونات المرتبطة

بلا عُري

computeEffectiveTldPlusOne

لعرض نطاق المستوى الأعلى الفعّال + 1 (eTLD+1) للنطاق أو عنوان URL المحدَّد. يتم احتساب نطاق eTLD+1 من خلال تقييم النطاق مقابل قواعد قائمة اللاحقة العامة. يكون عادةً eTLD+1 هو النطاق الأعلى مستوى الذي يمكنك إعداد ملف تعريف ارتباط عليه.

إذا كانت الوسيطة فارغة أو غير معرَّفة، فسيتم إرجاع قيمة الوسيطة بدون تغيير. بخلاف ذلك، يتم فرض الوسيطة على سلسلة. إذا لم تكن الوسيطة نطاقًا أو عنوان URL صالحًا، فسيتم عرض سلسلة فارغة. إذا لم يتمكن الخادم من استرجاع قائمة اللاحقات العامة، فسيتم عرض قيمة الوسيطة بدون تغيير.

مثال

const computeEffectiveTldPlusOne = require('computeEffectiveTldPlusOne');

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

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

البنية

computeEffectiveTldPlusOne(domainOrUrl);

المَعلمات

المَعلمة النوع الوصف
domainOrUrl سلسلة هو نطاق أو عنوان URL يتم استخدامه لحساب eTLD+1.

الأذونات المرتبطة

بلا عُري

createRegex

تنشئ مثيلاً جديدًا من تعبيرات عادية وتعيده ملفوفًا في كائن. ولا يمكنك الوصول إلى التعبير العادي مباشرةً. ويمكنك تمريره إلى testRegex API وString.replace() وString.match() وString.search().

تعرض null في حال كان التعبير العادي غير صالح أو عدم توفّر Re2 على الخادم.

تستخدم واجهة برمجة التطبيقات هذه عملية تنفيذ 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 سلسلة معرّف الموارد المنتظم (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) مُرمّز من خلال استبعاد الأحرف الخاصة. تعرض سلسلة تمثل السلسلة المقدَّمة التي تم ترميزها على أنّها معرّف موارد منتظم (URI).

مثال

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

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

البنية

encodeUriComponent(str);

المَعلمات

المَعلمة النوع الوصف
str سلسلة يشير ذلك المصطلح إلى مكوّن لمعرّف الموارد المنتظم (URI).

الأذونات المرتبطة

بلا عُري

extractEventsFromMpv1

يترجم طلب الإصدار 1 الوارد من Measurement Protocol إلى قائمة أحداث بتنسيق المخطط الموحّد. تعرض قائمة الأحداث المُستخرَجة. يعرض خطأ إذا لم يكن الطلب بالتنسيق الصحيح.

مثال

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

يترجم طلب الإصدار 2 الوارد من Measurement Protocol إلى قائمة أحداث بتنسيق المخطط الموحّد. تعرض قائمة الأحداث المُستخرَجة. يعرض خطأ إذا لم يكن الطلب بالتنسيق الصحيح.

مثال

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 رقم القيمة الصغرى المحتملة للعدد الصحيح الذي تم عرضه (شاملاً).
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]);

المَعلمات

المَعلمة النوع الوصف
name سلسلة اسم ملف تعريف الارتباط.
noDecode boolean وفي حال 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 أيّ مسار المفتاح، حيث يتم فصل مكونات المسار بنقاط. ويمكن أن تكون مكونات المسار مفاتيح في كائن أو فهارس في مصفوفة. إذا لم تكن العلامة keyPath سلسلة، يتم فرضها على سلسلة.

البنية

getEventData(keyPath);

الأذونات المرتبطة

read_event_data

getGoogleAuth

لعرض عنصر تفويض، وعند استخدامه مع sendHttpGet أو sendHttpRequest، سيتضمن عنوان تفويض لـ Google Cloud APIs. تستخدم واجهة برمجة التطبيقات هذه بيانات الاعتماد التلقائية للتطبيق للعثور تلقائيًا على بيانات الاعتماد من بيئة الخادم.

مثال

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

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

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

البنية

getGoogleAuth(scopes);

المَعلمات

المَعلمة النوع الوصف
scopes مصفوفة مصفوفة من نطاقات OAuth 2.0 Google API لطلب الوصول إليها.

الأذونات المرتبطة

يجب الحصول على إذن use_google_credentials. يجب ضبط الإذن باستخدام نطاق مسموح به واحد أو أكثر.

getGoogleScript

يسترد موردًا من مجموعة محدّدة مسبقًا من نصوص Google البرمجية وعرض واعدًا مع النص البرمجي والبيانات الوصفية للتخزين المؤقت ذات الصلة.

سيتحوّل الوعد إلى كائن يحتوي على مفتاحَين: script وmetadata. إذا تعذّر الطلب، سيتم رفض الوعد باستخدام مفتاح reason.

سيحتوي الكائن metadata على البيانات الوصفية التالية للتخزين المؤقت استنادًا إلى عناوين استجابة الموارد، ولن يتوفّر كل حقل إلا إذا كان العنوان المقابل متوفرًا في استجابة المورد.

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

مثال

const getGoogleScript = require('getGoogleScript');

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

البنية

getGoogleScript(script[, options]);

المَعلمات

المَعلمة النوع الوصف
script سلسلة اسم النص البرمجي. النصوص البرمجية المتوافقة هي 'ANALYTICS' و'GTAG' و'GTM'.

يسترجع الخيار 'ANALYTICS' النص البرمجي لخدمة "إحصاءات Google" من https://www.google-analytics.com/analytics.js.

يسترجع الخيار 'GTAG' النص البرمجي لعلامة الموقع الشاملة (gtag.js) من https://www.googletagmanager.com/gtag/js.

يسترجع الخيار 'GTM' النص البرمجي لأداة "إدارة العلامات من Google" من https://www.googletagmanager.com/gtm.js.
options كائن خيارات الطلب الاختيارية. انظر أدناه للاطّلاع على الخيارات المتاحة.

الخيارات

Option النوع الوصف
id سلسلة تسري هذه السياسات على 'GTAG' مع رقم تعريف قياس gtag و'GTM' مع رقم تعريف حاوية الويب (مثل GTM-XXXX).
debug أيّ في حال المصداقية، تطلب وتعرِض نسخة تصحيح الأخطاء من النص البرمجي للقياس.
timeout رقم انتهت مهلة الطلب بالمللي ثانية، ويتم تجاهل القيم غير الموجبة. إذا انتهت مهلة الطلب، سيتم استدعاء الاستدعاء باستخدام undefined لقيمة النص البرمجي و{} لعنصر البيانات الوصفية.

ويتم تجاهل مفاتيح الخيارات غير المعروفة.

الأذونات المرتبطة

يجب الحصول على إذن send_http. يجب ضبط الإذن للسماح بالوصول إلى ما يلي على الأقل:

  • السماح بخدمة Google Domains

getRemoteAddress

لعرض تمثيل سلسلة لعنوان IP الذي أنشأ فيه الطلب، مثل 12.345.67.890 لبروتوكول IPv4 أو 2001:0db8:85a3:0:0:8a2e:0370:7334 لبروتوكول IPv6، من خلال قراءة عناوين الطلبات مثل Redirected وX-Reseted-For. ملاحظة: تبذل واجهة برمجة التطبيقات هذه قصارى جهدها لاكتشاف عنوان IP الأصلي، ولكنها لا تضمن دقة النتيجة.

البنية

getRemoteAddress();

الأذونات المرتبطة

يجب الحصول على إذن read_request. يجب ضبط الإذن للسماح بالوصول إلى ما يلي على الأقل:

  • العنوانان Forwarded وX-Forwarded-For
  • عنوان IP البعيد

getRequestBody

لعرض نص الطلب على هيئة سلسلة، في حال توفّره، أو على شكل undefined بخلاف ذلك.

البنية

getRequestBody();

الأذونات المرتبطة

read_request

getRequestHeader

تعرض قيمة عنوان الطلب المُسمّى سلسلة في حال توفّرها أو على شكل undefined. وفي حال تكرار العنوان، يتم ضم القيم المعروضة مع ', '.

مثال

const getRequestHeader = require('getRequestHeader');

const host = getRequestHeader('host');

البنية

getRequestHeader(headerName);

المَعلمات

المَعلمة النوع الوصف
headerName سلسلة اسم العنوان. هذه القيمة غير حساسة لحالة الأحرف.

الأذونات المرتبطة

read_request

getRequestMethod

عرض طريقة الطلب، مثل 'GET' أو 'POST'، في صورة سلسلة

مثال

const getRequestMethod = require('getRequestMethod');

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

البنية

getRequestMethod();

الأذونات المرتبطة

بلا عُري

getRequestPath

تعرض مسار الطلب بدون سلسلة طلب البحث. على سبيل المثال، إذا كان عنوان URL هو '/foo?id=123'، سيؤدي ذلك إلى عرض '/foo'. يؤدي ذلك إلى إزالة بادئة عنوان URL لحاوية الخادم تلقائيًا من المسار. على سبيل المثال، إذا كان عنوان URL لحاوية الخادم هو https://example.com/analytics وكان مسار الطلب هو '/analytics/foo'، سيعرض هذا '/foo'.

مثال

const getRequestPath = require('getRequestPath');

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

البنية

getRequestPath();

الأذونات المرتبطة

read_request

getRequestQueryParameter

تعرض القيمة المفكوك ترميزها لمعلَمة سلسلة طلب البحث المسماة على أنّها سلسلة أو undefined في حال عدم توفّر المَعلمة. في حال تكرار المعلمة في سلسلة طلب البحث، سيتم عرض القيمة الأولى التي تظهر في سلسلة طلب البحث.

مثال

const getRequestQueryParameter = require('getRequestQueryParameter');

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

البنية

getRequestQueryParameter(name);

المَعلمات

المَعلمة النوع الوصف
name سلسلة اسم مَعلمة طلب البحث

الأذونات المرتبطة

read_request

getRequestQueryParameters

تعرض مَعلمات طلب البحث الواردة لطلب HTTP ككائن يحدد أسماء مَعلمات طلب البحث بالقيمة أو القيم المقابلة. يتم فك ترميز أسماء المعلمات وقيمها.

مثال

const getRequestQueryParameters = require('getRequestQueryParameters');

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

البنية

getRequestQueryParameters();

الأذونات المرتبطة

read_request

getRequestQueryString

يعرض طلب بحث الطلب كسلسلة، أو بدون علامة استفهام سابقة، أو سلسلة فارغة إذا كان عنوان URL للطلب لا يتضمّن سلسلة طلب بحث.

مثال

const getRequestQueryString = require('getRequestQueryString');

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

البنية

getRequestQueryString();

الأذونات المرتبطة

read_request

getTimestamp

تمّت إزالة هذا العمود. أفضِّل getTimestampMillis.

لعرض رقم يمثل الوقت الحالي بالمللي ثانية منذ حقبة يونكس، كما يعرضه Date.now().

البنية

getTimestamp();

الأذونات المرتبطة

بلا عُري

getTimestampMillis

لعرض رقم يمثل الوقت الحالي بالمللي ثانية منذ حقبة يونكس، كما يعرضه Date.now().

البنية

getTimestampMillis();

الأذونات المرتبطة

بلا عُري

getType

تعرض سلسلة تصف نوع القيمة المحددة.

نوع الإدخال القيمة المعروضة
سلسلة 'string'
رقم 'number'
boolean 'boolean'
null 'null'
غير محدّدة 'undefined'
مصفوفة 'array'
كائن 'object'
الوظيفة 'function'

مثال

const getType = require('getType');

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

البنية

getType(value);

المَعلمات

المَعلمة النوع الوصف
value أيّ قيمة الإدخال

الأذونات المرتبطة

بلا عُري

hmacSha256

تحسب توقيعًا مُشفَّرًا باستخدام رمز مصادقة الرسائل المستند إلى التجزئة (HMAC) مع SHA-256. يتم ضبط الإعدادات التلقائية على ترميز base64url.

لاستخدام واجهة برمجة التطبيقات هذه، يجب ضبط متغيِّر بيئة SGTM_CREDENTIALS على الخادم على مسار ملف مفتاح JSON بالترميز UTF-8 بالتنسيق التالي:

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

وتكون القيم هي مفاتيح HMAC بترميز base64.

مثال

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

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

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

البنية

hmacSha256(data, keyId, options)

المَعلمات

المَعلمة النوع الوصف
data سلسلة يشير ذلك المصطلح إلى البيانات اللازمة لحساب قيمة بروتوكول HMAC.
keyId سلسلة معرِّف مفتاح من ملف مفتاح JSON يشير إلى المفتاح المطلوب استخدامه.
options كائن ضبط واجهة برمجة التطبيقات الاختياري: (راجِع الخيارات أدناه.)

الخيارات

Option النوع الوصف
outputEncoding سلسلة تحدد تنسيق الترميز للقيمة المعروضة. التنسيقات المتوافقة هي hex أو base64 أو base64url. ويتم ضبط القيمة التلقائية على base64url إذا لم يتم تحديدها.

الأذونات المرتبطة

use_custom_private_keys

الحد الأدنى لإصدار الصورة

1.0.0

isRequestMpv1

تعرض true إذا كان الطلب الوارد هو طلب الإصدار 1 من Measurement Protocol، أو false غير ذلك.

مثال

const isRequestMpv1 = require('isRequestMpv1');

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

البنية

isRequestMpv1();

الأذونات المرتبطة

بلا عُري

isRequestMpv2

تعرض true إذا كان الطلب الوارد هو طلب الإصدار 2 من Measurement Protocol، أو false غير ذلك.

مثال

const isRequestMpv2 = require('isRequestMpv2');

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

البنية

isRequestMpv2();

الأذونات المرتبطة

بلا عُري

logToConsole

تسجيل الوسيطة الخاصة بها(وسيطاتها) في وحدة التحكم.

تظهر هذه السجلات في مستكشف السجلات في Google Cloud Console. من "مستكشف السجلات"، شغِّل الطلب logName =~ "stdout" للاطّلاع على إدخالات السجلّ التي تم إنشاؤها بواسطة واجهة برمجة التطبيقات هذه.

مثال

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

لعرض القيمة المحددة على شكل string.

البنية

makeString(value);

المَعلمات

المَعلمة النوع الوصف
value أي نوع القيمة المطلوب تحويلها.

الأذونات المرتبطة

بلا عُري

makeTableMap

لتحويل كائن جدول بسيط يحتوي على عمودين إلى Map. تُستخدَم هذه الخطوة لتغيير حقل نموذج SIMPLE_TABLE باستخدام عمودَين إلى تنسيق يمكن إدارته بسهولة أكبر.

على سبيل المثال، يمكن لهذه الدالة تحويل كائن جدول:

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

إلى خريطة:

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

عرض كائن: تمت إضافة Map المحوَّلة لأزواج المفتاح/القيمة إليه، أو null.

البنية

makeTableMap(tableObj, keyColumnName, valueColumnName);

المَعلمات

المَعلمة النوع الوصف
tableObj قائمة كائن الجدول المطلوب تحويله. إنها قائمة بخرائط يمثّل فيها كل Map صفًا في الجدول. يكون اسم كل سمة في عنصر الصف هو اسم العمود، وقيمة السمة هي قيمة العمود في الصف.
keyColumnName سلسلة اسم العمود الذي ستصبح قيمه مفاتيح في عمود Map المحوَّل.
valueColumnName سلسلة اسم العمود الذي ستصبح قيمه قيمًا في عمود Map المحوَّل.

الأذونات المرتبطة

بلا عُري

parseUrl

تعرض كائنًا يحتوي على جميع الأجزاء المكوّنة لعنوان URL معيّن، على غرار الكائن URL.

ستعرض واجهة برمجة التطبيقات هذه الحالة undefined لأي عنوان URL مكتوب بشكلٍ غير صحيح. بالنسبة إلى عناوين URL المنسَّقة بشكل صحيح، ستحتوي الحقول غير المتوفّرة في سلسلة عنوان URL على قيمة سلسلة فارغة، أو في حالة searchParams، تمثّل هذه السمة كائنًا فارغًا.

وسيحتوي الكائن الذي تمّ عرضه على الحقول التالية:

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

مثال

const parseUrl = require('parseUrl');

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

البنية

parseUrl(url);

المَعلمات

المَعلمة النوع الوصف
url سلسلة عنوان URL الكامل الذي سيتم تحليله

الأذونات المرتبطة

بلا عُري

returnResponse

محو الرد الذي سبق ضبطه من خلال نماذج أخرى باستخدام واجهات برمجة التطبيقات التي تعدِّل الاستجابة، بما في ذلك setCookie وsetPixelResponse وsetResponseBody وsetResponseHeader وsetResponseStatus. يتم ضبط الإعدادات التلقائية على رمز حالة HTTP 200، ونص فارغ، وبدون عناوين.

ننصح باستخدام واجهة برمجة التطبيقات هذه من نموذج عميل.

البنية

returnResponse();

مثال

اطّلِع على مثال runContainer.

الأذونات المرتبطة

return_response

runContainer

تقوم بتشغيل منطق الحاوية (المتغيرات وعوامل التشغيل والعلامات) في نطاق الحدث. في حال طلب واجهة برمجة التطبيقات هذه أثناء تنفيذ الحاوية، سيتم تشغيل الحاوية مرة أخرى.

تتلقى استدعاءات onComplete وonStart دالة تُسمى bindToEvent. استخدِم bindToEvent لتشغيل واجهة برمجة التطبيقات في سياق الحدث. اطّلِع على مثال على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" مع عرض واعد يتم حلّه إلى كائن باستخدام مفتاح location أو يتم رفضه إلى كائن باستخدام مفتاح reason. تستند الوجهة، Universal Analytics أو "إحصاءات Google 4"، إلى رقم تعريف القياس في بيانات الأحداث.

ويتم ضبط الحقل location على عنوان location في حال توفّره.

مثال

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

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

البنية

sendEventToGoogleAnalytics(event);

المَعلمات

المَعلمة النوع الوصف
event كائن الحدث بتنسيق المخطط الموحّد

الأذونات المرتبطة

يجب الحصول على إذن send_http. يجب ضبط الإذن للسماح بالوصول إلى ما يلي على الأقل:

  • السماح بخدمة Google Domains

sendHttpGet

يقدّم طلب HTTP GET إلى عنوان URL المحدّد، ويعرض واعدًا يتم حله مع النتيجة بعد اكتمال الطلب أو انتهاء مهلته.

النتيجة التي تم حلها هي كائن يحتوي على ثلاثة مفاتيح: statusCode وheaders وbody. في حال تعذّر الطلب (على سبيل المثال، عنوان URL غير صالح أو عدم توفّر مسار إلى المضيف أو تعذّر تفاوض طبقة المقابس الآمنة وما إلى ذلك)، سيتم رفض الوعد من خلال: {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 سلسلة عنوان URL المطلوب.
options كائن خيارات الطلب الاختيارية (راجِع الخيارات أدناه.)

الخيارات

Option النوع الوصف
headers سلسلة عناوين الطلبات الإضافية
timeout رقم المهلة بالمللي ثانية قبل إلغاء الطلب وتكون الإعدادات التلقائية 15000.
authorization كائن كائن تفويض اختياري من الاستدعاء إلى getGoogleAuth لتضمين رؤوس التفويض عند إرسال طلبات إلى googleapis.com.

الأذونات المرتبطة

send_http

sendHttpRequest

يقدّم طلب HTTP إلى عنوان URL المحدَّد، ويعرض وعدًا يتم التعامل معه بالاستجابة عند اكتمال الطلب أو انتهاء المهلة المحدّدة.

النتيجة التي تم حلها هي كائن يحتوي على ثلاثة مفاتيح: statusCode وheaders وbody. في حال تعذّر الطلب (على سبيل المثال، عنوان URL غير صالح أو عدم توفّر مسار إلى المضيف أو تعذّر تفاوض طبقة المقابس الآمنة وما إلى ذلك)، سيتم رفض الوعد من خلال: {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 سلسلة عنوان URL المطلوب.
options كائن خيارات الطلب الاختيارية (راجِع الخيارات أدناه.)
body سلسلة نص الطلب اختياري.

الخيارات

Option النوع الوصف
headers سلسلة عناوين الطلبات الإضافية
method كائن طريقة الطلب. وتكون الإعدادات التلقائية GET.
timeout رقم المهلة بالمللي ثانية قبل إلغاء الطلب وتكون الإعدادات التلقائية 15000.
authorization كائن كائن تفويض اختياري من الاستدعاء إلى getGoogleAuth لتضمين رؤوس التفويض عند إرسال طلبات إلى googleapis.com.

الأذونات المرتبطة

send_http

sendPixelFromBrowser

يرسل هذا النموذج طلبًا إلى المتصفّح لتحميل عنوان URL المقدَّم كعلامة <img>. يكون بروتوكول الأوامر هذا متوافقًا مع علامة Google لعلامات الويب على "إحصاءات Google 4" و"إحصاءات Google": حدث "إحصاءات Google". يجب ضبط عنوان URL لحاوية الخادم. راجِع التعليمات للاطّلاع على مزيد من التفاصيل.

تعرض واجهة برمجة التطبيقات هذه false إذا كان الطلب الوارد لا يتوافق مع بروتوكول الأوامر أو إذا تم محو بيانات الاستجابة. وبخلاف ذلك، ستعرض واجهة واجهة برمجة التطبيقات هذه true.

مثال:

const sendPixelFromBrowser = require('sendPixelFromBrowser');

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

البنية

sendPixelFromBrowser(url)

المَعلمات

المَعلمة النوع الوصف
url سلسلة عنوان URL المطلوب إرساله إلى المتصفِّح

الأذونات المرتبطة

send_pixel_from_browser

setCookie

لضبط ملف تعريف ارتباط أو حذفه باستخدام الخيارات المحدّدة.

لحذف ملف تعريف ارتباط، يجب ضبط ملف تعريف ارتباط باستخدام المسار والنطاق نفسيهما اللذَين تم إنشاء ملف تعريف الارتباط باستخدامهما، وتعيين قيمة لانتهاء الصلاحية تقع في الماضي، مثل "Thu, 01 Jan 1970 00:00:00 GMT".

تجدر الإشارة إلى أنّه يجب طلب returnResponse لإرسال الردّ إلى العميل.

مثال

const setCookie = require('setCookie');

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

البنية

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

المَعلمات

المَعلمة النوع الوصف
name سلسلة اسم ملف تعريف الارتباط. الاسم غير حساس لحالة الأحرف.
value سلسلة قيمة ملف تعريف الارتباط.
options كائن السمات الاختيارية لملفات تعريف الارتباط:domain وexpires وfallbackDomain وhttpOnly وmax- age وpath وsecure وsameSite. (اطّلِع على الخيارات أدناه.)
noEncode boolean إذا كانت القيمة true، لن يتم ترميز قيمة ملف تعريف الارتباط. وتكون الإعدادات التلقائية false.

  • domain: المضيف الذي سيتم إرسال ملف تعريف الارتباط إليه. في حال ضبط هذه السياسة على القيمة الخاصة "auto" (تلقائي)، سيتم احتساب المضيف تلقائيًا باستخدام الاستراتيجية التالية:

    • eTLD+1 لعنوان Forwarded، إن توفّر
    • eTLD+1 لعنوان X-Forwarded-Host، إن توفّر
    • eTLD+1 لعنوان Host

  • انتهاء الصلاحية: الحد الأقصى لمدة صلاحية ملف تعريف الارتباط. ويجب أن تكون سلسلة التاريخ هذه بتنسيق التوقيت العالمي المتفق عليه (UTC)، مثل "السبت، 26 تشرين الأول (أكتوبر) 1985 08:21:00 بتوقيت غرينيتش". إذا تم ضبط كل من expires وmax-age، تكون الأولوية للحقل max-age.

  • httpOnly: تحظر JavaScript من الوصول إلى ملف تعريف الارتباط في حال true.

  • max-age: عدد الثواني المتبقية حتى انتهاء صلاحية ملف تعريف الارتباط. ستنتهي صلاحية ملف تعريف الارتباط إذا كان الرقم صفرًا أو سالبًا على الفور. إذا تم ضبط كل من expires وmax-age، ستكون الأولوية للحقل max-age.

  • path: مسار يجب أن يكون متوفّرًا في عنوان URL المطلوب، وإلا لن يرسل المتصفّح عنوان ملف تعريف الارتباط.

  • آمن: في حال ضبط السياسة على true، لا يتم إرسال ملف تعريف الارتباط إلى الخادم إلا عند تقديم طلب من نقطة نهاية https:.

  • sameSite: تؤكد أنّه يجب عدم إرسال ملف تعريف ارتباط من خلال طلبات من مصادر متعددة. يجب أن يكون 'strict' أو 'lax' أو 'none'.

الأذونات المرتبطة

set_cookie

setPixelResponse

لتعيين نص الاستجابة على ملف GIF 1x1، وتعيين العنوان Content-Type على "image/gif"، وضبط عناوين التخزين المؤقت بحيث لا يخزّن برامج وكيل المستخدم الاستجابة مؤقتًا، ويضبط حالة الاستجابة على 200.

تجدر الإشارة إلى أنّه يجب طلب returnResponse لإرسال الردّ إلى العميل.

البنية

setPixelResponse();

الأذونات المرتبطة

يجب الحصول على إذن access_response. يجب ضبط الإذن للسماح بالوصول إلى ما يلي على الأقل:

  • headers - يجب أن يسمح بالمفاتيح التالية:
    • content-type
    • cache-control
    • expires
    • pragma
  • body
  • status

setResponseBody

لضبط نص الاستجابة على الوسيطة.

تجدر الإشارة إلى أنّه يجب طلب returnResponse لإرسال الردّ إلى العميل.

البنية

setResponseBody(body[, encoding]);

المَعلمات

المَعلمة النوع الوصف
body سلسلة القيمة المطلوب ضبطها كنص الاستجابة
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 رقم رمز حالة 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 للإدخال ويعرضها بترميز base64، ما لم يحدد الكائن options ترميزًا مختلفًا للإخراج.

مثال

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

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

البنية

sha256Sync(input, options = undefined);

المَعلمات

المَعلمة النوع الوصف
input سلسلة السلسلة المطلوب تجزئتها.
options كائن كائن الخيارات الاختياري لتحديد ترميز الإخراج. وفي حال تحديدها، يجب أن يحتوي الكائن على المفتاح outputEncoding مع قيمة واحدة من base64 أو hex.

الأذونات المرتبطة

بلا عُري

templateDataStorage

لعرض كائن مع طرق للوصول إلى تخزين بيانات النموذج. يسمح تخزين بيانات النموذج بمشاركة البيانات عبر عمليات تنفيذ نموذج واحد. تظل البيانات المخزنة في تخزين بيانات النموذج على الخادم الذي يقوم بتشغيل الحاوية. في معظم الحالات، هناك خوادم متعددة تشغل الحاوية، لذا لا يضمن تخزين البيانات في تخزين بيانات النموذج حصول كل طلب لاحق على إمكانية الوصول إلى البيانات.

تشير "البيانات" في اسم "templateDataStorage" إلى حقيقة أنه يمكن تخزين أنواع البيانات العادية وغير الوظيفية فقط باستخدام واجهة برمجة التطبيقات هذه. وسيتم تخزين أي دوال أو إشارات إلى الدوال التي تم تمريرها إلى واجهة برمجة التطبيقات على أنّها 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);

المَعلمات

المَعلمة النوع الوصف
regex كائن التعبير العادي المطلوب اختباره، والذي يتم عرضه من createRegex API
string سلسلة سلسلة الاختبار المطلوب اختبارها.

الأذونات المرتبطة

بلا عُري

toBase64

لترميز سلسلة بالشكل base64 أو base64url. يتم ضبط التشفير تلقائيًا على ترميز base64.

البنية

toBase64(input, options);

المَعلمات

المَعلمة النوع الوصف
input سلسلة سلسلة مطلوب ترميزها
options كائن ضبط واجهة برمجة التطبيقات الاختياري: (راجِع الخيارات أدناه.)

الخيارات

Option النوع الوصف الحد الأدنى للإصدار
urlEncoding boolean إذا كانت القيمة "صحيح"، سيتم ترميز النتيجة باستخدام تنسيق base64url. 1.0.0

مثال

const toBase64 = require('toBase64');

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

الأذونات المرتبطة

بلا عُري

BigQuery

تعرض كائنًا يوفر دوال BigQuery.

تسمح الدالة BigQuery.insert بكتابة البيانات في جدول BigQuery. ويعرض وعدًا يتم حلّه عند إجراء إدراج ناجح أو رفضه بسبب خطأ.

عندما تنجح عملية الإدراج، يتم حل الوعد بدون أي وسيطات.

عندما يتعذّر الإدراج، يتم رفض الوعد من خلال إضافة قائمة عناصر تحتوي على سبب الخطأ وربما كائن صف في حال حدوث خطأ. من الممكن إكمال جزء من الطلب بنجاح، بينما لا يتم إكمال الأجزاء الأخرى. يتم رفض الميزة في هذه الحالة من خلال إدراج قائمة بالأخطاء لكل صف يتضمّن كائن صف للمساعدة في تمييز الصفوف التي تم إدراجها (يمكنك الاطّلاع على أمثلة عن الأخطاء أدناه). راجِع وثائق BigQuery بشأن رسائل الخطأ للحصول على مزيد من المعلومات.

البنية

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

المَعلمة النوع الوصف
connectionInfo كائن تحدِّد المعلومات المطلوبة للربط بجدول BigQuery. ثمة معلَمة اختيارية واحدة ومَعلمتَين مطلوبتَين:
  • projectId - رقم تعريف مشروع Google Cloud Platform الاختياري. في حال حذفه، يتم استرداد projectId من متغيّر البيئة GOOGLE_CLOUD_PROJECT طالما تم ضبط إعداد الإذن access_bigquery لرقم تعريف المشروع على * أو GOOGLE_CLOUD_PROJECT. إذا كانت حاوية الخادم قيد التشغيل على Google Cloud، سيكون قد تم ضبط GOOGLE_CLOUD_PROJECT على رقم تعريف مشروع Google Cloud.
  • datasetId - رقم تعريف مجموعة بيانات BigQuery
  • tableId - رقم تعريف جدول BigQuery
rows مصفوفة الصفوف المطلوب إدراجها في الجدول.
options كائن خيارات الطلب الاختيارية. والخيارات المتاحة هي: ignoreUnknownValues وskipInvalidRows. يتم تجاهل مفاتيح الخيارات غير المعروفة. (اطّلِع على الخيارات أدناه.)

المَعلمة النوع الوصف
ignoreUnknownValues boolean في حال ضبطها على true، اقبل الصفوف التي تحتوي على قيم لا تتطابق مع المخطط. ويتم تجاهل القيم غير المعروفة. ويكون الإعداد التلقائي على false.
skipInvalidRows boolean في حال ضبط السياسة على true، أدرِج جميع الصفوف الصالحة في الطلب، حتى في حال توفُّر صفوف غير صالحة. وتكون الإعدادات التلقائية false.

أمثلة على الأخطاء

يعني الخطأ "لم يتم العثور على الوحدة" أنه من المحتمل أن تستخدم حاوية الخادم لديك إصدارًا قديمًا من الصورة لم يتضمن وحدة BigQuery بعد. يُرجى إعادة نشر حاوية الخادم باستخدام الإعدادات نفسها باستخدام النص البرمجي للنشر. سيتم تضمين الوحدة تلقائيًا بعد اكتمال العملية.

يتضمن الخطأ غير المتعلق بالإدراج عادةً كائن خطأ واحدًا مع مفتاح reason:

[{reason: 'invalid'}]

يمكن أن يحتوي خطأ الإدراج على عناصر أخطاء متعددة مع مصفوفة errors وكائن row. فيما يلي مثال على استجابة خطأ من إدراج صفين حيث يحتوي صف واحد فقط على خطأ:

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

مثال

const BigQuery = require('BigQuery');

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

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

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

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

الأذونات المرتبطة

access_bigquery

Firestore

لعرض كائن يوفر دوال Firestore.

تتوافق واجهة برمجة التطبيقات هذه مع Firestore في الوضع الأصلي فقط، وليس Firestore في وضع تخزين البيانات.

Firestore.read

تقرأ الدالة Firestore.read البيانات من مستند Firestore وتعرض وعدًا يؤدي إلى كائن يحتوي على مفتاحَين: id وdata. في حال عدم توفّر المستند، يتم رفض الوعد إذا كان هناك عنصر يحتوي على مفتاح reason يساوي not_found.

البنية

Firestore.read(path[, options]);

المَعلمة النوع الوصف
path سلسلة المسار إلى المستند أو المجموعة يجب ألا يبدأ أو ينتهي بالعلامة "/".
options كائن خيارات الطلب الاختيارية وتشمل الخيارات المتاحة: projectId وdisableCache، وtransaction. ويتم تجاهل مفاتيح الخيارات غير المعروفة. (اطّلِع على الخيارات أدناه.)

المَعلمة النوع الوصف
projectId سلسلة Optional. رقم تعريف مشروع Google Cloud Platform في حال حذفه، يتم استرداد projectId من متغيّر البيئة GOOGLE_CLOUD_PROJECT طالما تم ضبط إعداد إذن access_firestore لرقم تعريف المشروع على * أو GOOGLE_CLOUD_PROJECT. إذا كانت حاوية الخادم قيد التشغيل على Google Cloud، سيكون GOOGLE_CLOUD_PROJECT قد سبق ضبطه على رقم تعريف مشروع Google Cloud.
disableCache boolean Optional. يحدد ما إذا كان سيتم إيقاف ذاكرة التخزين المؤقت أم لا. يكون التخزين المؤقت مفعَّلاً تلقائيًا، ما يؤدي إلى تخزين النتائج مؤقتًا طوال مدة الطلب.
transaction سلسلة Optional. القيمة التي تم استردادها من 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. إذا كان المسار إلى مجموعة، سيتم إنشاء مستند برقم تعريف يتم إنشاؤه عشوائيًا. إذا كان المسار إلى مستند ولم يكن موجودًا، فسيتم إنشاؤه. تعرض واجهة برمجة التطبيقات هذه وعدًا يفي بمعرّف المستند الذي تمت إضافته أو تعديله. إذا تم استخدام خيار المعاملة، تستمر واجهة برمجة التطبيقات في عرض الوعد، ولكنها لن تحتوي على المعرف لأنه يتم تجميع البيانات.

البنية

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

المَعلمات

المَعلمة النوع الوصف
path سلسلة المسار إلى المستند أو المجموعة يجب ألا يبدأ أو ينتهي بالعلامة "/".
input كائن القيمة المطلوب كتابتها في المستند. إذا تم ضبط خيار الدمج، ستدمج واجهة برمجة التطبيقات المفاتيح من الإدخال في المستند.
options كائن خيارات الطلب الاختيارية وتشمل الخيارات المتاحة: projectId وmerge وtransaction. يتم تجاهل مفاتيح الخيارات غير المعروفة. (اطّلِع على الخيارات أدناه.)

المَعلمة النوع الوصف
projectId سلسلة Optional. رقم تعريف مشروع Google Cloud Platform في حال حذفه، يتم استرداد projectId من متغيّر البيئة GOOGLE_CLOUD_PROJECT طالما تم ضبط إعداد إذن access_firestore لرقم تعريف المشروع على * أو GOOGLE_CLOUD_PROJECT. إذا كانت حاوية الخادم قيد التشغيل على Google Cloud، سيكون GOOGLE_CLOUD_PROJECT قد سبق ضبطه على رقم تعريف مشروع Google Cloud.
merge boolean Optional. في حال ضبط هذه السياسة على true، يتم دمج المفاتيح من مصدر الإدخال في المستند، وإلا ستلغي الطريقة المستند بأكمله. وتكون الإعدادات التلقائية false.
transaction سلسلة Optional. القيمة التي تم استردادها من 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 مصفوفة مصفوفة من شروط الاستعلام. ويأتي كل طلب بحث في شكل مصفوفة مكونة من ثلاث قيم: key وoperator وdigitalValue. E.g.: [[‘id’, ‘<’, ‘5’], [‘state’, ‘==’, ‘CA’]].

يتم ربط الشروط معًا لإنشاء نتيجة طلب البحث. يُرجى الرجوع إلى عوامل تشغيل طلبات البحث في Firestore للاطّلاع على قائمة بعوامل تشغيل طلبات البحث المتوافقة.
options كائن خيارات الطلب الاختيارية وتشمل الخيارات المتاحة: projectId وdisablecache وlimit وtransaction. ويتم تجاهل مفاتيح الخيارات غير المعروفة. (اطّلِع على الخيارات أدناه.)

المَعلمة النوع الوصف
projectId سلسلة Optional. رقم تعريف مشروع Google Cloud Platform في حال حذفه، يتم استرداد projectId من متغيّر البيئة GOOGLE_CLOUD_PROJECT طالما تم ضبط إعداد إذن access_firestore لرقم تعريف المشروع على * أو GOOGLE_CLOUD_PROJECT. إذا كانت حاوية الخادم قيد التشغيل على Google Cloud، سيكون GOOGLE_CLOUD_PROJECT قد سبق ضبطه على رقم تعريف مشروع Google Cloud.
disableCache boolean Optional. يحدد ما إذا كان سيتم إيقاف ذاكرة التخزين المؤقت أم لا. يكون التخزين المؤقت مفعَّلاً تلقائيًا، ما يؤدي إلى تخزين النتائج مؤقتًا طوال مدة الطلب.
limit رقم Optional. لتغيير الحد الأقصى لعدد النتائج التي يعرضها طلب البحث، ويكون الإعداد التلقائي هو 5.
transaction سلسلة Optional. القيمة التي تم استردادها من 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 بشكل ذري. في حال حدوث عملية كتابة متزامنة أو حدوث تضارب في معاملة أخرى، ستتم إعادة محاولة إجراء المعاملة مرتين. وإذا فشلت بعد ثلاث محاولات إجمالاً، سيتم رفض واجهة برمجة التطبيقات مع ظهور خطأ. تعرض واجهة برمجة التطبيقات هذه وعدًا يحلّ مجموعة من معرّفات المستندات لكل عملية كتابة إذا تمت العملية بنجاح، وسيتم رفضه مع ظهور الخطأ إذا تعذّر ذلك.

البنية

Firestore.runTransaction(callback[, options]);

المَعلمات

المَعلمة النوع الوصف
callback الوظيفة معاودة الاتصال التي يتم استدعاؤها باستخدام معرِّف معاملة سلسلة. يمكن تمرير معرِّف المعاملة إلى طلبات البيانات من واجهة برمجة التطبيقات للقراءة/الكتابة/الاستعلام. يجب أن تعرض دالة رد الاتصال هذه وعدًا. قد يتم تنفيذ معاودة الاتصال حتى ثلاث مرات قبل أن يتعذّر إتمام العملية.
options كائن خيارات الطلب الاختيارية الخيار المتوافق فقط هو projectId. يتم تجاهل مفاتيح الخيارات غير المعروفة. (اطّلِع على الخيارات أدناه.)

المَعلمة النوع الوصف
projectId سلسلة Optional. رقم تعريف مشروع 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.

الأذونات المرتبطة

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

المَعلمات

المَعلمة النوع الوصف
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

يتم إرجاع القيمة "صحيح" إذا تمت إضافة مستمع للرسالة لنوع الرسالة المحدّد. وتعرض القيمة false في الحالات الأخرى.

البنية

const hasMessageListener = require('hasMessageListener');

hasMessageListener('send_pixel');

الأذونات المرتبطة

بلا عُري

sendMessage

لإرسال رسالة من النوع المحدّد إلى مستمع مسجَّل يمكن استخدام ذلك لإرسال الرسائل من علامة معيّنة إلى العميل الذي شغّل الحاوية.

البنية

const sendMessage = require('sendMessage');

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

المَعلمات

المَعلمة النوع الوصف
messageType سلسلة نوع الرسالة المطلوب إرسالها إذا لم تكن القيمة سلسلة، سيتم فرضها على سلسلة.
message كائن الرسالة المطلوب إرسالها. إذا لم تكن الرسالة كائنًا، لن تفعل واجهة برمجة التطبيقات أي شيء.

الأذونات المرتبطة

يجب الحصول على إذن 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() سلوك عامل التشغيل للمكتبة العادية. تزيل المفتاح المحدد من الكائن ما لم يتم تجميد الكائن. وعلى غرار عامل التشغيل حذف "المكتبة العادية"، فإنه يعرض true إذا كانت قيمة الإدخال الأولى (objectInput) كائنًا لم يتم تجميده حتى إذا كانت قيمة الإدخال الثانية (keyToDelete) تحدّد مفتاحًا غير موجود. تعرض القيمة false في جميع الحالات الأخرى. ومع ذلك، فإنه يختلف عن عامل حذف حذف "المكتبة القياسية" في الطرق التالية:

  • لا يمكن أن يكون الحقل "keyToDelete" سلسلة محدّدة بنقاط محدَّدة وتحدّد مفتاحًا مدمجًا.
  • لا يمكن استخدام delete() لإزالة عناصر من مصفوفة.
  • لا يمكن استخدام delete() لإزالة أي مواقع من النطاق العمومي.

البنية

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

المَعلمات

Object.keys

المَعلمة النوع الوصف
objectInput أيّ تمثّل هذه السمة الكائن المطلوب تعداد مفاتيحه. إذا لم يكن الإدخال كائنًا، سيتم فرضه على كائن.

Object.values

المَعلمة النوع الوصف
objectInput أيّ يشير ذلك المصطلح إلى الكائن المطلوب تعداد قيمه. إذا لم يكن الإدخال كائنًا، سيتم فرضه على كائن.

Object.entries

المَعلمة النوع الوصف
objectInput أيّ يشير ذلك المصطلح إلى الكائن المطلوب تعداده من خلال أزواج المفتاح/القيمة. إذا لم يكن الإدخال كائنًا، سيتم فرضه على كائن.

Object.freeze

المَعلمة النوع الوصف
objectInput أيّ الكائن المراد تجميده. إذا لم يكن المُدخل كائنًا، سيتم التعامل معه على أنّه كائن مجمّد.

Object.delete

المَعلمة النوع الوصف
objectInput أيّ تمثّل هذه السمة الكائن المطلوب حذف مفتاحه.
keyToDelete سلسلة مفتاح المستوى الأعلى الذي تريد حذفه.

مثال

const Object = require('Object');

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

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

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

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

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

Promise

تعرض كائنًا يوفر طرقًا للتفاعل مع الوعود.

تتشابه الوعود من الناحية العملية مع وعود JavaScript. كل مثال له ثلاث طرق تعرض الوعد الذي يسمح بإجراء إضافي عندما يوافق الوعد:

  • .then(): يعالج كل من الطلبات التي تم حلّها ورفضها. لذلك، يتطلب الأمر عمليتي معاودة الاتصال كمعلمة: واحدة لحالة النجاح والأخرى لحالة الفشل.
  • .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);

المَعلمات

المَعلمة النوع الوصف
inputs مصفوفة يشير ذلك المصطلح إلى مصفوفة من القيم أو الوعود. إذا لم يكن الإدخال عبارة عن وعود، يتم تمرير الإدخال كما لو كان قيمة الوعد التي تم حلّها. تعرض هذه الدالة خطأ إذا لم يكن الإدخال مصفوفة.

مثال

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

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

الأذونات المرتبطة

بلا عُري

Promise.create

تنشئ وعدًا يكافئ عمليًا بوعد JavaScript.

البنية

Promise.create(resolver);

المَعلمات

المَعلمة النوع الوصف
resolver الوظيفة دالة يتم استدعاؤها بدالتَين -- الحل والرفض. سيتم التعامل مع الوعد الذي يتم عرضه مرة أخرى أو رفضه عند استدعاء المَعلمة المناظِرة. تعرض رسالة خطأ إذا لم يكن برنامج التعيين وظيفة.

مثال

const Promise = require('Promise');

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

الأذونات المرتبطة

بلا عُري

اختبار واجهات برمجة التطبيقات

تعمل واجهات برمجة التطبيقات هذه مع اختبارات JavaScript في وضع الحماية لإنشاء اختبارات للنماذج المخصّصة في أداة "إدارة العلامات من Google". لا تحتاج واجهات برمجة التطبيقات الاختبارية هذه إلى عبارة require(). [مزيد من المعلومات عن اختبارات النماذج المخصّصة]

assertApi

تعرض كائن مطابقة يمكن استخدامه لتقديم تأكيدات بطلاقة حول واجهة برمجة التطبيقات المذكورة.

البنية

assertApi(apiName)

المَعلمات

المَعلمة النوع الوصف
apiName سلسلة اسم واجهة برمجة التطبيقات المطلوب التحقّق منها، والسلسلة نفسها التي تم تمريرها إلى 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 استنادًا إلى مكتبة [Truth] في Google. فهي تعرض كائنًا يمكن استخدامه لتقديم تأكيدات بطلاقة حول قيمة الموضوع. ويؤدي إخفاق التأكيد إلى إيقاف الاختبار على الفور ووضع علامة عليه كفشل. ومع ذلك، فإن الفشل في اختبار واحد لن يؤثر على حالات الاختبار الأخرى.

البنية

assertThat(actual, opt_message)

المَعلمات

المَعلمة النوع الوصف
actual أيّ القيمة المطلوب استخدامها في عمليات التحقّق بطلاقة.
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() التأكيد على أن الموضوع هو مصفوفة أو سلسلة فارغة (الطول = 0). يتعذّر التأكيد دائمًا إذا لم تكن القيمة صفيفًا أو سلسلة.
isNotEmpty() تؤكد أن الموضوع هو مصفوفة أو سلسلة غير فارغة (الطول > 0). يتعذّر التأكيد دائمًا إذا لم تكن القيمة صفيفًا أو سلسلة.
isArray() تؤكد أن نوع الموضوع هو صفيف.
isBoolean() تؤكد أن نوع الموضوع منطقي.
isFunction() تؤكد على أن نوع الموضوع هو دالة.
isNumber() تأكيد أن نوع الموضوع هو رقم.
isObject() تأكيد أن نوع الموضوع هو كائن.
isString() تؤكد أن نوع الموضوع هو سلسلة.

أمثلة

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

fail

تعذّر الاختبار الحالي على الفور وتُطبع الرسالة المحددة، إذا تم توفيرها.

البنية

fail(opt_message);

المَعلمات

المَعلمة النوع الوصف
opt_message سلسلة نص اختياري لرسالة خطأ.

مثال

fail('This test has failed.');

mock

تسمح لك واجهة برمجة التطبيقات mock بتجاهل سلوك واجهات برمجة التطبيقات التي تم وضع الحماية لها. تعتبر واجهة برمجة التطبيقات الوهمية آمنة للاستخدام في التعليمات البرمجية للقالب، ولكنها لا تعمل عندما لا تكون في وضع الاختبار. وتتم إعادة ضبط النماذج قبل إجراء كل اختبار.

البنية

mock(apiName, returnValue);

المَعلمات

المَعلمة النوع الوصف
apiName سلسلة اسم واجهة برمجة التطبيقات المطلوب اختبارها، والسلسلة نفسها التي تم تمريرها إلى require()
returnValue أيّ القيمة التي يتم عرضها لواجهة برمجة التطبيقات أو دالة يتم استدعاءها بدلاً من واجهة برمجة التطبيقات. إذا كانت returnValue دالة، يتم استدعاء هذه الدالة بدلاً من Sandboxed API. أما إذا كانت returnValue غير دالة، فسيتم عرض هذه القيمة بدلاً من Sandbox API.

أمثلة

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

runCode

تنفيذ رمز النموذج، أي محتوى علامة التبويب الرمز، في بيئة الاختبار الحالية باستخدام عنصر بيانات إدخال معيّن.

البنية

runCode(data)

المَعلمات

المَعلمة النوع الوصف
data كائن كائن البيانات المراد استخدامه في الاختبار.

قيمة الإرجاع

تعرض قيمة متغير للنماذج المتغيرة، وتعرض undefined لجميع أنواع النماذج الأخرى.

مثال

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