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

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

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 أو runContainer onComplete).

يجب أن يطالب العميل بالطلب باستخدام واجهة برمجة التطبيقات هذه قبل طلب واجهة برمجة تطبيقات 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

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

مثال

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

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

البنية

extractEventsFromMpv1();

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

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

  • body
  • query parameters

extractEventsFromMpv2

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

مثال

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

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

البنية

extractEventsFromMpv2();

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

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

  • body
  • query parameters

fromBase64

فك ترميز سلسلة base64 المرمّزة. تعرض undefined إذا كان الإدخال غير صالح.

البنية

fromBase64(base64EncodedString);

المَعلمات

المَعلمة النوع الوصف
base64EncodedString سلسلة سلسلة Base64 مرمّزة.

مثال

const fromBase64 = require('fromBase64');

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

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

بلا عُري

generateRandom

تعرض رقمًا عشوائيًا (عدد صحيح) ضمن النطاق المحدّد.

مثال

const generateRandom = require('generateRandom');

const randomValue = generateRandom(0, 10000000);

البنية

generateRandom(min, max);

المَعلمات

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

مثال

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

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

البنية

getRemoteAddress();

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

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

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

getRequestBody

عرض نص الطلب كـ string، في حال توفّره، أو 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.

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

البنية

getTimestamp();

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

بلا عُري

getTimestampMillis

لعرض رقم يمثل الوقت الحالي بالمللي ثانية منذ حقبة Unix، على النحو الذي يتم عرضه بواسطة 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 إذا كان الطلب الوارد عبارة عن طلب Measurement Protocol V1، أو false غير ذلك.

مثال

const isRequestMpv1 = require('isRequestMpv1');

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

البنية

isRequestMpv1();

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

بلا عُري

isRequestMpv2

تعرض true إذا كان الطلب الوارد عبارة عن طلب Measurement Protocol V2، أو false غير ذلك.

مثال

const isRequestMpv2 = require('isRequestMpv2');

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

البنية

isRequestMpv2();

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

بلا عُري

logToConsole

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

تظهر هذه السجلّات ضمن مستكشف السجلات في 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 logToConsole = require('logToConsole');
const sendEventToGoogleAnalytics = require('sendEventToGoogleAnalytics');
const setResponseHeader = require('setResponseHeader');
const setResponseStatus = require('setResponseStatus');

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

البنية

sendEventToGoogleAnalytics(event);

المَعلمات

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

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

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

  • السماح بنطاقات Google Domains

sendHttpGet

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

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

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

    • eTLD+1 لعنوان Forwarded، في حال توفّره
    • eTLD+1 لعنوان X-Forwarded-Host، في حال توفّره
    • eTLD+1 من عنوان Host.

  • expires: الحد الأقصى لمدة صلاحية ملف تعريف الارتباط. ويجب أن تكون سلسلة التاريخ بالتنسيق العالمي هي مثل "السبت، 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.
string سلسلة سلسلة تجريبية لاختبارها.

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

بلا عُري

toBase64

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

البنية

toBase64(input, options);

المَعلمات

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

الخيارات

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

مثال

const toBase64 = require('toBase64');

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

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

بلا عُري

BigQuery

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

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

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

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

البنية

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

المَعلمة النوع الوصف
connectionInfo كائن تحدد المعلومات المطلوبة للربط بجدول BigQuery. هناك مَعلمة اختيارية واحدة ومعلمتَين مطلوبتَين:
  • projectId - Optional Google Cloud Platform project ID. If omitted, the projectId is retrieved from the environment variable GOOGLE_CLOUD_PROJECT as long as the access_bigquery permission setting for the project ID is set to * or GOOGLE_CLOUD_PROJECT. If the server container is running on Google Cloud, GOOGLE_CLOUD_PROJECT will already be set to the Google Cloud project's ID.
  • datasetId - رقم تعريف مجموعة بيانات BigQuery.
  • tableId - رقم تعريف جدول BigQuery.
rows مصفوفة الصفوف المراد إدراجها في الجدول.
options كائن خيارات الطلب الاختيارية. تشمل الخيارات المتاحة ما يلي: ignoreUnknownValues و skipInappropriateROWS يتم تجاهل مفاتيح الخيارات غير المعروفة. (اطّلِع على الخيارات أدناه.)

المَعلمة النوع الوصف
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 و AdMobValue. 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 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 API. اطّلِع على المثال.

البنية

const addMessageListener = require('addMessageListener');

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

المَعلمات

المَعلمة النوع الوصف
messageType سلسلة نوع الرسالة المطلوب الاستماع إليها إذا لم تكن القيمة سلسلة، سيتم فرضها كسلسلة.
callback الوظيفة عملية معاودة الاتصال التي يتم تشغيلها عند إرسال رسالة من نوع الرسالة الساري. إذا لم تكن عملية معاودة الاتصال دالة، فلن تفعل واجهة برمجة التطبيقات أي شيء.

مثال

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

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

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

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

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

  • نوع الرسالة مع Usage من listen أو listen_and_send.

hasMessageListener

يتم عرض true إذا تمت إضافة مستمع رسالة لنوع معين من الرسائل. تعرِض القيمة "خطأ" في الحالات الأخرى.

البنية

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() يؤكد أن الموضوع عبارة عن مصفوفة أو سلسلة غير فارغة (length > 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 هي أي قيمة بخلاف الدالة، يتم عرض هذه القيمة بدلاً من Sandboxed 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'});