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

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

addEventCallback

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

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

البنية

const addEventCallback = require('addEventCallback');

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

المعلّمات

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

يحتوي العنصر eventData على البيانات التالية:

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

في البرنامج:

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

claimRequest();

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

في علامة:

const addEventCallback = require('addEventCallback');

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

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

read_event_metadata

callLater

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

مثال

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

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

البنية

callLater(function)

المعلّمات

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

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

بلا عُري

claimRequest

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

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

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

مثال

const claimRequest = require('claimRequest');

claimRequest();

البنية

claimRequest();

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

بلا عُري

computeEffectiveTldPlusOne

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

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

مثال

const computeEffectiveTldPlusOne = require('computeEffectiveTldPlusOne');

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

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

البنية

computeEffectiveTldPlusOne(domainOrUrl);

المعلّمات

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

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

بلا عُري

createRegex

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

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

بلا عُري

decodeUriComponent

فك ترميز أي أحرف مشفرة في مكوّن معرّف الموارد المنتظم (URI) المقدَّم. تؤدي إلى إرجاع string التي تمثل مكوّن 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 منطقية إذا كانت 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 مصفوفة مصفوفة من نطاقات واجهة برمجة تطبيقات Google 2.0 OAuth طلب الوصول إليه.

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

يجب الحصول على إذن 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 Analytics من 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'
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 تستند "إحصاءات Google" أو "إحصاءات 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- العمر، المسار، آمن، وsameSite. (راجع الخيارات، أدناه).
noEncode منطقية في حال اختيار القيمة "true"، لن يتم ترميز قيمة ملف تعريف الارتباط. الإعدادات التلقائية على false

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

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

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

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

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

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

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

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

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

set_cookie

setPixelResponse

لضبط نص الاستجابة على ملف GIF 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 سلسلة القيمة المطلوب ضبطها كنص للاستجابة.
encoding سلسلة ترميز الأحرف لنص الاستجابة (القيمة التلقائية 'utf8'). وتشمل القيم المسموح بها 'ascii'، 'utf8'، 'utf16le'، 'ucs2'، 'base64'، 'latin1'، 'binary'، و'hex'.

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

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

  • body

setResponseHeader

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

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

البنية

setResponseHeader(name, value);

المعلّمات

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

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

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

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

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

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

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

[{reason: 'invalid'}]

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

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

مثال

const BigQuery = require('BigQuery');

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

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

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

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

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

access_bigquery

Firestore

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

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

Firestore.read

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

البنية

Firestore.read(path[, options]);

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

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

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

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

المعلمة النوع الوصف
projectId سلسلة Optional. رقم تعريف مشروع Google Cloud Platform في حال حذفها، تم استرداد projectId من متغيّر البيئة. وGOOGLE_CLOUD_PROJECT طالما أن access_firestore تم ضبط إعداد الإذن لرقم تعريف المشروع على * أو GOOGLE_CLOUD_PROJECT إذا كانت حاوية الخادم قيد التشغيل على Google Cloud، سبق أن تم ضبط GOOGLE_CLOUD_PROJECT على معرّف مشروع Google Cloud.
disableCache منطقية Optional. تحدِّد هذه السياسة ما إذا كان سيتم إيقاف ذاكرة التخزين المؤقت. يتم تمكين التخزين المؤقت افتراضيًا، والذي سيقوم بتخزين نتائج مدة الطلب.
limit الرقم Optional. تغير الحد الأقصى لعدد النتائج التي يتم عرضها بواسطة طلب البحث، تكون القيمة التلقائية هي 5.
transaction سلسلة Optional. القيمة المستردة من Firestore.runTransaction(). وضع علامة على العملية المطلوب استخدامها داخل معاملة.

مثال

const Firestore = require('Firestore');

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

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

Firestore.runTransaction

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

البنية

Firestore.runTransaction(callback[, options]);

المعلّمات

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

المعلمة النوع الوصف
projectId سلسلة Optional. رقم تعريف مشروع Google Cloud Platform في حال حذفها، تم استرداد projectId من متغيّر البيئة. وGOOGLE_CLOUD_PROJECT طالما أن access_firestore تم ضبط إعداد الإذن لرقم تعريف المشروع على * أو GOOGLE_CLOUD_PROJECT إذا كانت حاوية الخادم قيد التشغيل على Google Cloud، سبق أن تم ضبط GOOGLE_CLOUD_PROJECT على معرّف مشروع Google Cloud.

مثال

const Firestore = require('Firestore');

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

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

مثال على خطأ

الأخطاء المتوفّرة في كل وظيفة من وظائف Firestore سيتم رفضها باستخدام أحد العناصر تحتوي على مفتاح reason:

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

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

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

access_firestore

JSON

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

تحلّل الدالة parse() سلسلة JSON لإنشاء القيمة أو العنصر. موصوفة بالسلسلة. وإذا تعذّر تحليل القيمة (على سبيل المثال، تنسيق JSON غير صحيح)، فستُرجع الدالة undefined. إذا لم تكن قيمة الإدخال سلسلة، فإن قيمة سيتم فرض الإدخال إلى سلسلة.

تحوّل الدالة stringify() الإدخال إلى سلسلة JSON. إذا كانت القيمة تحليله (على سبيل المثال، للكائن دورة)، فستُرجع الطريقة undefined

مثال

const JSON = require('JSON');

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

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

البنية

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

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

بلا عُري

Math

كائن يوفّر دوال Math.

البنية

const Math = require('Math');

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

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

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

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

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

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

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

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

المعلّمات

يتم تحويل معلمات دالة الرياضيات إلى أرقام.

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

بلا عُري

Messages

تعمل واجهات برمجة التطبيقات التالية معًا للسماح بتمرير الرسائل بين الأجزاء من الحاوية.

addMessageListener

إضافة دالة تستجيب لرسالة من نوع معين. عندما تظهر رسالة من هذا النوع يتم إرساله باستخدام واجهة برمجة التطبيقات sendMessage (عادةً بواسطة علامة)، فسيتم تشغيل رد الاتصال بشكل متزامن. يتم تشغيل عملية رد الاتصال بمعلمتين:

  1. messageType:string
  2. message:Object

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

البنية

const addMessageListener = require('addMessageListener');

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

المعلّمات

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

مثال

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

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

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

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

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

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

hasMessageListener

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

أمثلة

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

mockObject

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

البنية

mockObject(apiName, objectMock);

المعلّمات

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

أمثلة

const storage = {};
let firestoreId = 1;

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

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

runCode

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

البنية

runCode(data)

المعلّمات

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

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

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

مثال

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