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

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

addEventCallback

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

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

البنية

const addEventCallback = require('addEventCallback');

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

المعلّمات

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

يحتوي عنصر 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 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 string نطاق أو عنوان URL لاحتساب eTLD+1

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

بلا عُري

createRegex

تُنشئ مثيلًا جديدًا للتعبير العادي وتُعيده ملفوفًا في عنصر. لا يمكنك الوصول إلى التعبير العادي مباشرةً. ومع ذلك، يمكنك تمريرها إلى واجهة برمجة التطبيقات testRegex، 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 string نص التعبير العادي
flags string سلسلة اختيارية تحتوي على علامات التعبير العادي الذي يتم إنشاؤه يمكن استخدام الخيارَين 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 string عنوان URL تم ترميزه باستخدام encodeUri() أو بوسائل أخرى

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

بلا عُري

decodeUriComponent

فك ترميز أي أحرف مُشفَّرة في مكوّن معرّف الموارد المنتظم (URI) المقدَّم. لعرض سلسلة تمثّل مكوّن معرّف الموارد المنتظم (URI) الذي تم فك ترميزه. تعرِض القيمة undefined عند إدخال قيمة غير صالحة.

مثال

const decodeUriComponent = require('decodeUriComponent');

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

البنية

decodeUriComponent(encoded_uri_component);

المعلّمات

المَعلمة النوع الوصف
encoded_uri_component string عنصر معرّف الموارد المنتظم (URI) الذي تم ترميزه باستخدام encodeUriComponent() أو بوسائل أخرى

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

بلا عُري

encodeUri

عرض معرّف موارد منتظم (URI) مُشفَّر من خلال ترميز الأحرف الخاصة عرض سلسلة تم ترميزها كمعرّف موارد منتظم (URI) وتمثل السلسلة المقدَّمة

مثال

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

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

البنية

encodeUri(uri);

المعلّمات

المَعلمة النوع الوصف
uri string عنوان URI كامل

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

بلا عُري

encodeUriComponent

عرض معرّف موارد منتظم (URI) مُشفَّر من خلال ترميز الأحرف الخاصة تعرِض هذه الدالة سلسلة تمثّل السلسلة المقدَّمة التي تم ترميزها على أنّها معرّف موارد منتظم (URI).

مثال

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

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

البنية

encodeUriComponent(str);

المعلّمات

المَعلمة النوع الوصف
str string مكوّن من معرّف الموارد المنتظم (URI)

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

بلا عُري

extractEventsFromMpv1

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

مثال

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

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

البنية

extractEventsFromMpv1();

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

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

  • body
  • query parameters

extractEventsFromMpv2

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

مثال

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

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

البنية

extractEventsFromMpv2();

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

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

  • body
  • query parameters

fromBase64

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

البنية

fromBase64(base64EncodedString);

المعلّمات

المَعلمة النوع الوصف
base64EncodedString string سلسلة مشفّرة بترميز Base64

مثال

const fromBase64 = require('fromBase64');

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

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

بلا عُري

generateRandom

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

مثال

const generateRandom = require('generateRandom');

const randomValue = generateRandom(0, 10000000);

البنية

generateRandom(min, max);

المعلّمات

المَعلمة النوع الوصف
min number الحد الأدنى للقيمة المحتمَلة للرقم الصحيح المعروض (شاملة).
max number الحد الأقصى للقيمة المحتمَلة للرقم الصحيح الذي يتم إرجاعه (شاملاً)

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

بلا عُري

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 string اسم ملف تعريف الارتباط
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 لطلب الوصول إليها

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

يتطلب إذن use_google_credentials. يجب أن يكون الإذن مُعدًّا بنطاق واحد أو أكثر من النطاقات المسموح بها.

getGoogleScript

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

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

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

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

مثال

const getGoogleScript = require('getGoogleScript');

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

البنية

getGoogleScript(script[, options]);

المعلّمات

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

يُستخدَم الخيار 'ANALYTICS' لجلب نص برمجي في "إحصاءات Google" من 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 object خيارات الطلب الاختيارية يمكنك الاطّلاع أدناه على الخيارات المتاحة.

الخيارات

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

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

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

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

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

getRemoteAddress

تعرِض هذه السمة سلسلة تمثّل عنوان IP الذي نشأ منه الطلب، مثل 12.345.67.890 لعنوان IPv4 أو 2001:0db8:85a3:0:0:8a2e:0370:7334 لعنوان IPv6، وذلك من خلال قراءة عناوين الطلبات، مثل Forwarded وX-Forwarded-For. ملاحظة: تبذل واجهة برمجة التطبيقات هذه قصارى جهدها لاكتشاف عنوان 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 string اسم العنوان هذه القيمة غير حسّاسة لحالة الأحرف.

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

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 string اسم مَعلمة طلب البحث

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

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 'string'
number 'number'
boolean 'boolean'
null 'null'
undefined 'undefined'
صفيف 'array'
العنصر 'object'
الوظيفة 'function'

مثال

const getType = require('getType');

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

البنية

getType(value);

المعلّمات

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

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

بلا عُري

hmacSha256

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

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

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

القيم هي مفاتيح HMAC بترميز base64. يجب ألّا يبدأ نص JSON بعلامة ترتيب ملف برمجي.

مثال

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

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

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

البنية

hmacSha256(data, keyId, options)

المعلّمات

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

الخيارات

Option النوع الوصف
outputEncoding string تُحدِّد تنسيق ترميز القيمة المعروضة. التنسيقات المتوافقة هي 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

لعرض القيمة المحدّدة كـ سلسلة.

البنية

makeString(value);

المعلّمات

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

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

بلا عُري

makeTableMap

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

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

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

في خريطة:

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

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

البنية

makeTableMap(tableObj, keyColumnName, valueColumnName);

المعلّمات

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

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

بلا عُري

parseUrl

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

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

سيتضمّن العنصر المعروض الحقول التالية:

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

مثال

const parseUrl = require('parseUrl');

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

البنية

parseUrl(url);

المعلّمات

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

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

بلا عُري

returnResponse

تُفرِغ هذه الوظيفة الردّ الذي تم ضبطه سابقًا بواسطة نماذج أخرى باستخدام واجهات برمجة التطبيقات التي تعدّل الردّ، بما في ذلك 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 object مَعلمات الحدث
onComplete function دالة استدعاء يتمّ تنفيذها بعد انتهاء تنشيط جميع العلامات.
onStart function طلب إعادة اتصال يتمّ استدعاؤه على الفور، قبل بدء تنشيط العلامات.

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

run_container

sendEventToGoogleAnalytics

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

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

يتطلب إذن 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 string عنوان URL المطلوب
options object خيارات الطلب الاختيارية (اطّلِع على الخيارات أدناه).

الخيارات

Option النوع الوصف
headers string عناوين طلبات إضافية
timeout number المهلة، بالمللي ثانية، قبل إيقاف الطلب الإعداد التلقائي هو 15000.
authorization object عنصر التفويض الاختياري من الطلب إلى 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 string عنوان URL المطلوب
options object خيارات الطلب الاختيارية (اطّلِع على الخيارات أدناه).
body string نص الطلب اختياري

الخيارات

Option النوع الوصف
headers string عناوين طلبات إضافية
method object طريقة الطلب الإعداد التلقائي هو GET.
timeout number المهلة، بالمللي ثانية، قبل إيقاف الطلب الإعداد التلقائي هو 15000.
authorization object عنصر التفويض الاختياري من الطلب إلى 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 string عنوان 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 string اسم ملفّ تعريف الارتباط يكون الاسم غير حسّاس لحالة الأحرف.
value string قيمة ملفّ تعريف الارتباط.
options object سمات ملفات تعريف الارتباط الاختيارية:domain، expires، fallbackDomain،httpOnly، max- age، path، secure، وsameSite. (اطّلِع على الخيارات أدناه).
noEncode boolean إذا كانت القيمة صحيحة، لن يتم ترميز قيمة ملف تعريف الارتباط. الإعداد التلقائي هو false.

الخيارات

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

    • النطاق في المستوى الأعلى مسبوقًا باسم (eTLD+1) لعنوان Forwarded، إن توفّر
    • النطاق في المستوى الأعلى مسبوقًا باسم (eTLD+1) لعنوان X-Forwarded-Host، إن توفّر
    • النطاق في المستوى الأعلى مسبوقًا باسم (eTLD+1) لعنوان Host

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

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

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

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

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

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

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

set_cookie

setPixelResponse

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

يُرجى العِلم أنّه يجب استدعاء returnResponse لكي يتم إرسال الردّ مجددًا إلى العميل.

البنية

setPixelResponse();

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

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

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

setResponseBody

تضبط نص الردّ على الوسيطة.

يُرجى العِلم أنّه يجب استدعاء returnResponse لكي يتم إرسال الردّ مجددًا إلى العميل.

البنية

setResponseBody(body[, encoding]);

المعلّمات

المَعلمة النوع الوصف
body string القيمة التي سيتم ضبطها كجسم الاستجابة.
encoding string ترميز الأحرف لنص الاستجابة (الإعداد التلقائي هو 'utf8'). تشمل القيم المسموح بها 'ascii'، 'utf8'، 'utf16le'، 'ucs2'، 'base64'، 'latin1'، 'binary'، و'hex'.

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

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

  • body

setResponseHeader

تُستخدَم لضبط عنوان في الاستجابة التي سيتم عرضها. إذا سبق أن تم ضبط عنوان بهذا الاسم (لا يراعي حالة الأحرف) من خلال واجهة برمجة التطبيقات هذه، سيؤدي الطلب الأخير إلى استبدال القيمة التي ضبطها المُتصل السابق أو محوها.

يُرجى العِلم أنّه يجب استدعاء returnResponse لكي يتم إرسال الردّ مجددًا إلى العميل.

البنية

setResponseHeader(name, value);

المعلّمات

المَعلمة النوع الوصف
name string اسم العنوان تكون أسماء رؤوس HTTP غير حسّاسة لحالة الأحرف، لذا سيتم استخدام الأحرف الصغيرة في اسم الرأس.
value string undefined قيمة العنوان إذا كان الرأس فارغًا أو غير محدّد، يؤدي ذلك إلى محو العنوان المُعنوَن من الاستجابة التي ستتم إعادتها.

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

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

  • headers

setResponseStatus

تُستخدَم لضبط رمز حالة HTTP للردّ الذي سيتم إرجاعه.

يُرجى العِلم أنّه يجب استدعاء returnResponse لكي يتم إرسال الردّ مجددًا إلى العميل.

البنية

setResponseStatus(statusCode);

المعلّمات

المَعلمة النوع الوصف
statusCode number رمز حالة HTTP المطلوب إرجاعه

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

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

  • status

sha256

تُحسِب هذه الدالة تجزئة SHA-256 للإدخال وتستدعي دالة استدعاء مع تجزئة بترميز base64، ما لم يحدِّد عنصر options ترميزًا مختلفًا للإدخال.

يتطابق توقيع واجهة برمجة التطبيقات وسلوكها مع واجهة برمجة التطبيقات sha256 لحاويات الويب، ومع ذلك، يجب أن تستخدم "النماذج المخصّصة" في حاويات الخادم واجهة برمجة التطبيقات sha256Sync للحصول على رمز أبسط.

مثال

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

sha256('inputString', (digest) => {
  sendHttpGet('https://example.com/collect?id=' + encodeUriComponent(digest));
});

sha256('inputString', (digest) => {
  sendHttpGet('https://example.com/collect?id=' + encodeUriComponent(digest));
}, {outputEncoding: 'hex'});

البنية

sha256(input, onSuccess, options = undefined);

المعلّمات

المَعلمة النوع الوصف
input string السلسلة المطلوب تجزئتها
onSuccess function يتمّ استدعاؤه باستخدام الملخّص الناتج، الذي يتم تشفيره بترميز base64، ما لم يحدّد options ترميزًا مختلفًا للإخراج.
options object عنصر خيارات اختياري لتحديد ترميز الإخراج في حال تحديده، يجب أن يحتوي الكائن على المفتاح outputEncoding مع قيمة base64 أو hex.

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

بلا عُري

sha256Sync

تُحسِب هذه الدالة تجزئة SHA-256 للإدخال وتُعرِضها، وهي مُشفَّرة بترميز base64، ما لم يحدِّد عنصر options ترميزًا مختلفًا للإخراج.

مثال

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

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

البنية

sha256Sync(input, options = undefined);

المعلّمات

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

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

بلا عُري

templateDataStorage

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

تشير كلمة "data" في الاسم "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. تعرِض هذه الدالة القيمة true إذا تطابق التعبير العادي. تعرِض false بخلاف ذلك.

يكون التعبير العادي الذي تم إنشاؤه باستخدام العلامة الشاملة مستندًا إلى الحالة. اطّلِع على مستندات RegExp للحصول على التفاصيل.

مثال

const createRegex = require('createRegex');
const testRegex = require('testRegex');

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

// createRegex returns null if the regex is invalid or Re2 is not available.
if (domainRegex === null) return;

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

البنية

testRegex(regex, string);

المعلّمات

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

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

بلا عُري

toBase64

تشفير سلسلة بترميز base64 أو base64url الإعداد التلقائي هو ترميز base64.

البنية

toBase64(input, options);

المعلّمات

المَعلمة النوع الوصف
input string السلسلة المطلوب تشفيرها
options object إعدادات اختيارية لواجهة برمجة التطبيقات (اطّلِع على الخيارات أدناه).

الخيارات

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 object تحدِّد المعلومات المطلوبة للربط بجدول 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 object خيارات الطلب الاختيارية الخيارات المتوافقة هي: 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

تعرِض دالة Firebase هذه عنصرًا يقدّم دوال Firestore.

لا تتوافق واجهة برمجة التطبيقات هذه إلا مع Firestore في الوضع الأصلي، وليس Firestore في وضع Datastore. لا تتيح واجهة برمجة التطبيقات أيضًا استخدام سوى قاعدة البيانات التلقائية.

Firestore.read

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

البنية

Firestore.read(path[, options]);

المَعلمات

المَعلمة النوع الوصف
path string مسار المستند أو المجموعة يجب ألّا يبدأ أو ينتهي بعلامة '/'.
options object خيارات الطلب الاختيارية الخيارات المتوافقة هي: projectId وdisableCache و transaction. يتم تجاهل مفاتيح الخيار غير المعروفة. (اطّلِع على الخيارات أدناه).

الخيارات

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

الخيارات

المَعلمة النوع الوصف
projectId string 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 string 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 string المسار إلى المجموعة يجب ألّا يبدأ أو ينتهي بعلامة '/'.
queryConditions صفيف مصفوفة من شروط طلبات البحث يأتي كل طلب بحث على شكل مصفوفة تحتوي على ثلاث قيم: المفتاح، عامل التشغيل، والقيمة المتوقّعة. مثلاً: [[‘id’, ‘<’, ‘5’], [‘state’, ‘==’, ‘CA’]].

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

الخيارات

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

الخيارات

المَعلمة النوع الوصف
projectId string 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.
  }
});

يمكن أن تتضمّن أسباب الأخطاء، على سبيل المثال لا الحصر، رموز أخطاء واجهة برمجة التطبيقات REST API في Firestore.

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

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 (عادةً من خلال علامة)، سيتم تنفيذ callback بشكل متزامن. يتم تشغيل دالة ردّ الاتصال بمَعلمتَين:

  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 string نوع الرسالة المطلوب الاستماع إليها. إذا لم تكن القيمة سلسلة، سيتم إجبارها على أن تكون سلسلة.
callback function دالة الاستدعاء التي سيتم تنفيذها عند إرسال رسالة من نوع الرسالة الساري إذا لم تكن دالة ردّ الاتصال، لن تُجري واجهة برمجة التطبيقات أيّ إجراء.

مثال

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 string نوع الرسالة المطلوب إرسالها. إذا لم تكن القيمة سلسلة، سيتم تحويلها إلى سلسلة.
message object الرسالة المطلوب إرسالها إذا لم تكن الرسالة عنصرًا، لن تتخذ واجهة برمجة التطبيقات أي إجراء.

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

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

  • نوع رسالة يتضمّن Usage من listen_and_send أو send

Object

لعرض عنصر يقدّم طرق Object.

توفّر الطريقة keys() سلوك Object.keys() المكتبة العادية. ويعرِض صفيفًا من أسماء سمات for...in... التي يمكن عدّها للكائن المحدَّد بالترتيب نفسه الذي ستُعرِضه حلقة for...in.... إذا كانت قيمة الإدخال ليست عنصرًا، سيتم تحويلها إلى عنصر.

توفّر الطريقة values() سلوك Object.values() المتوفّر في المكتبة العادية. تعرض هذه الدالة صفيفًا من قيم السمات التي يمكن عدّها للكائن المحدّد بالترتيب نفسه الذي ستستخدمه حلقة for...in.... إذا لم تكن قيمة الإدخال عنصرًا، سيتم تحويلها إلى عنصر.

توفّر الطريقة entries() سلوك Object.entries() المكتبة العادية. ويعرِض صفيفًا من أزواج سمة [key, value] التي يمكن عدّها للكائن المحدَّد بالترتيب نفسه الذي ستتبعه حلقة for...in.... إذا كانت قيمة الإدخال ليست عنصرًا، سيتم تحويلها إلى عنصر.

توفّر الطريقة freeze() سلوك Object.freeze() المتوفّر في المكتبة العادية. لا يمكن تغيير كائن مجمّد بعد الآن، لأنّ تجميد الكائن يمنع إضافة خصائص جديدة إليه، وإزالة الخصائص الحالية، وتغيير قيم الخصائص الحالية. تعرِض freeze() العنصر نفسه الذي تم تمريره. سيتم التعامل مع الوسيطة البدائية أو الفارغة كما يلي: كما لو كانت عنصرًا مجمّدًا، وسيتم إرجاعها.

توفّر الطريقة delete() سلوك عامل الحذف في المكتبة العادية. تزيل هذه الطريقة المفتاح المحدّد من العنصر ما لم يكن العنصر مجمّدًا. مثل عامل التشغيل delete في المكتبة العادية، يعرض الرمز true إذا كانت قيمة الإدخال الأولى (objectInput) عنصرًا غير مجمّد حتى إذا كانت قيمة الإدخال الثانية (keyToDelete) تحدّد مفتاحًا غير متوفّر. ويعرض الرمز false في جميع الحالات الأخرى. ومع ذلك، يختلف عن عامل التشغيل delete في المكتبة العادية بالأساليب التالية:

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

البنية

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

المعلّمات

Object.keys

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

Object.values

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

Object.entries

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

Object.freeze

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

Object.delete

المَعلمة النوع الوصف
objectInput أي العنصر الذي تريد حذف مفتاحه
keyToDelete string مفتاح المستوى الأعلى لحذف العنصر

مثال

const Object = require('Object');

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

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

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

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

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

Promise

تُعيد عنصرًا يقدّم طرقًا للتفاعل مع الوعود.

التعهدات متكافئة من الناحية الوظيفية مع تعهدات JavaScript. يحتوي كل مثيل على ثلاث طرق تُعرِض وعدًا يسمح باتخاذ إجراء إضافي عند اكتمال الوعد:

  • .then() - يعالج كلاً من الحالات التي تم حلّها والحالات المرفوضة. يأخذ المكوّن اثنَين من وظائف callback كمَعلمتَين: واحدة لحالة النجاح وأخرى لحالة الانهيار.
  • .catch() - يعالج الحالات المرفوضة فقط. تأخذ دالة ردّ الاتصال معلَمة واحدة كأحد المَعلمات.
  • ‫.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 function دالة يتمّ استدعاؤها بدالتَين: حلّ ورفض. سيتم حلّ الوعد المعروض أو رفضه عند استدعاء المَعلمة المقابلة له. يُعرِض خطأ إذا لم تكن أداة التحليل دالة.

مثال

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 string اسم واجهة برمجة التطبيقات المطلوب التحقّق منها، وهي السلسلة نفسها التي تم تمريرها إلى 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 string رسالة اختيارية للطباعة في حال تعذّر تأكيد القيمة.

المطابقون

أداة المطابقة الوصف
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 string نص رسالة الخطأ اختياري.

مثال

fail('This test has failed.');

mock

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

البنية

mock(apiName, returnValue);

المعلّمات

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

أمثلة

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

mockObject

تتيح لك واجهة برمجة التطبيقات mockObject إلغاء سلوك واجهات برمجة التطبيقات في وضع الحماية التي تُعرِض عنصرًا. إنّ واجهة برمجة التطبيقات آمنة للاستخدام في رمز النموذج، ولكنّها تعمل فقط في وضع الاختبار. تتم إعادة ضبط النماذج الاختبارية قبل إجراء كل اختبار.

البنية

mockObject(apiName, objectMock);

المعلّمات

المَعلمة النوع الوصف
apiName string اسم واجهة برمجة التطبيقات التي سيتم محاكاتها، وهي السلسلة نفسها التي تم تمريرها إلى require()
objectMock object القيمة التي سيتم عرضها لواجهة برمجة التطبيقات أو دالة يتم استدعاؤها بدلاً من واجهة برمجة التطبيقات يجب أن يكون عنصرًا.

أمثلة

const storage = {};
let firestoreId = 1;

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

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

runCode

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

البنية

runCode(data)

المعلّمات

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

القيمة المعروضة

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

مثال

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