يوضح هذا المستند واجهات برمجة التطبيقات لوضع العلامات من جهة الخادم.
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.
});
الأذونات المرتبطة
callLater
تعمل هذه السياسة على جدولة استدعاء دالة ليظهر بشكل غير متزامن. سيتم استدعاء الدالة بعد
إرجاع التعليمة البرمجية الحالية. يعادل ذلك setTimeout(<function>, 0)
.
مثال
const callLater = require('callLater');
const logToConsole = require('logToConsole');
callLater(() => {
logToConsole('Logged asynchronously');
});
البنية
callLater(function)
المَعلمات
المَعلمة | النوع | الوصف |
---|---|---|
function |
الوظيفة | الدالة المطلوب استدعاءها. |
الأذونات المرتبطة
بلا عُري
claimRequest
استخدام واجهة برمجة التطبيقات هذه في العميل للمطالبة بالطلب. بعد المطالبة بأحد الطلبات، لا تقوم الحاوية بتشغيل عملاء إضافيين.
تعرِض واجهة برمجة التطبيقات هذه استثناءً إذا تم طلبها في علامة أو متغيّر. وتطرح واجهة برمجة التطبيقات هذه استثناءً في حال استدعائها بعد رجوع العميل إلى الموقع الإلكتروني (مثلاً، في حال استدعائها في استدعاء غير متزامن، كما في callLater
أو دالة onComplete
لبرامج runContainer
).
على العميل المطالبة بالطلب باستخدام واجهة برمجة التطبيقات هذه قبل طلب
واجهة برمجة تطبيقات runContainer
.
مثال
const claimRequest = require('claimRequest');
claimRequest();
البنية
claimRequest();
الأذونات المرتبطة
بلا عُري
computeEffectiveTldPlusOne
لعرض نطاق المستوى الأعلى الفعّال + 1 (eTLD+1) للنطاق أو عنوان URL المحدَّد. يتم احتساب نطاق eTLD+1 من خلال تقييم النطاق مقابل قواعد قائمة اللاحقة العامة. يكون عادةً eTLD+1 هو النطاق الأعلى مستوى الذي يمكنك إعداد ملف تعريف ارتباط عليه.
إذا كانت الوسيطة فارغة أو غير معرَّفة، فسيتم إرجاع قيمة الوسيطة بدون تغيير. بخلاف ذلك، يتم فرض الوسيطة على سلسلة. إذا لم تكن الوسيطة نطاقًا أو عنوان URL صالحًا، فسيتم عرض سلسلة فارغة. إذا لم يتمكن الخادم من استرجاع قائمة اللاحقات العامة، فسيتم عرض قيمة الوسيطة بدون تغيير.
مثال
const computeEffectiveTldPlusOne = require('computeEffectiveTldPlusOne');
// Returns 'example.co.uk'
computeEffectiveTldPlusOne('analytics.example.co.uk');
// Returns 'example.co.uk'
computeEffectiveTldPlusOne('https://analytics.example.co.uk/path');
البنية
computeEffectiveTldPlusOne(domainOrUrl);
المَعلمات
المَعلمة | النوع | الوصف |
---|---|---|
domainOrUrl |
سلسلة | هو نطاق أو عنوان URL يتم استخدامه لحساب eTLD+1. |
الأذونات المرتبطة
بلا عُري
createRegex
تنشئ مثيلاً جديدًا من تعبيرات عادية وتعيده ملفوفًا في كائن. ولا يمكنك الوصول إلى
التعبير العادي مباشرةً. ويمكنك تمريره إلى testRegex
API وString.replace()
وString.match()
وString.search()
.
تعرض null
في حال كان التعبير العادي غير صالح أو عدم توفّر Re2 على الخادم.
تستخدم واجهة برمجة التطبيقات هذه عملية تنفيذ Re2. يجب أن تكون صورة Docker على الخادم باستخدام الإصدار 2.0.0 أو إصدار أحدث.
مثال
const createRegex = require('createRegex');
const domainRegex = createRegex('\\w+\\.com', 'i');
// Returns '/foobar'
'example.com/foobar'.replace(domainRegex, '');
البنية
createRegex(pattern, flags);
المَعلمات
المَعلمة | النوع | الوصف |
---|---|---|
pattern |
سلسلة | نص التعبير العادي. |
flags |
سلسلة | سلسلة اختيارية تحتوي على العلامات للتعبير العادي الذي يتم إنشاؤه. يمكن استخدام `g` (عالمي) و `i` (تجاهل حالة الأحرف). ويتم تجاهل جميع الأحرف الأخرى بدون تنبيه. |
الأذونات المرتبطة
بلا عُري
الحد الأدنى لإصدار الصورة
decodeUri
تفكّ ترميز أي أحرف مرمّزة في معرّف الموارد المنتظم (URI) المُقدّم. تعرض سلسلة تمثل
معرّف الموارد المنتظم (URI) الذي تم فك ترميزه. تعرض undefined
عند توفير إدخال
غير صالح.
مثال
const decodeUri = require('decodeUri');
const decodedUrl = decodeUri(data.encodedUrl);
if (decodedUrl) {
// ...
}
البنية
decodeUri(encoded_uri);
المَعلمات
المَعلمة | النوع | الوصف |
---|---|---|
encoded_uri |
سلسلة |
معرّف الموارد المنتظم (URI) الذي تم ترميزه باستخدام
encodeUri() أو بطرق أخرى.
|
الأذونات المرتبطة
بلا عُري
decodeUriComponent
تفكّ ترميز أي أحرف مرمّزة في مكوّن معرّف الموارد المنتظم (URI) المقدَّم. تعرض سلسلة تمثل مكوِّن معرّف الموارد المنتظم (URI) الذي تم فك ترميزه. تعرض undefined
عند
منحها إدخالاً غير صالح.
مثال
const decodeUriComponent = require('decodeUriComponent');
const decodedQuery = decodeUriComponent(data.query);
if (decodedQuery) {
// ...
}
البنية
decodeUriComponent(encoded_uri_component);
المَعلمات
المَعلمة | النوع | الوصف |
---|---|---|
encoded_uri_component |
سلسلة |
مكوِّن معرّف الموارد المنتظم (URI) الذي تم ترميزه باستخدام
encodeUriComponent()
أو بطرق أخرى.
|
الأذونات المرتبطة
بلا عُري
encodeUri
تعرض معرّف موارد منتظم (URI) مُرمّز من خلال استبعاد الأحرف الخاصة. تعرض سلسلة تمثل السلسلة المقدَّمة التي تم تشفيرها باعتبارها معرّف موارد منتظم (URI).
مثال
const encodeUri = require('encodeUri');
const sendHttpGet = require('sendHttpGet');
sendHttpGet('https://www.example.com/' + encodeUri(pathInput));
البنية
encodeUri(uri);
المَعلمات
المَعلمة | النوع | الوصف |
---|---|---|
uri |
سلسلة | معرّف موارد منتظم (URI) كامل. |
الأذونات المرتبطة
بلا عُري
encodeUriComponent
تعرض معرّف موارد منتظم (URI) مُرمّز من خلال استبعاد الأحرف الخاصة. تعرض سلسلة تمثل السلسلة المقدَّمة التي تم ترميزها على أنّها معرّف موارد منتظم (URI).
مثال
const encodeUriComponent = require('encodeUriComponent');
const sendHttpGet = require('sendHttpGet');
sendHttpGet('https://www.example.com/?' + encodeUriComponent(queryInput));
البنية
encodeUriComponent(str);
المَعلمات
المَعلمة | النوع | الوصف |
---|---|---|
str |
سلسلة | يشير ذلك المصطلح إلى مكوّن لمعرّف الموارد المنتظم (URI). |
الأذونات المرتبطة
بلا عُري
extractEventsFromMpv1
يترجم طلب الإصدار 1 الوارد من Measurement Protocol إلى قائمة أحداث بتنسيق المخطط الموحّد. تعرض قائمة الأحداث المُستخرَجة. يعرض خطأ إذا لم يكن الطلب بالتنسيق الصحيح.
مثال
const extractEventsFromMpv1 = require('extractEventsFromMpv1');
const isRequestMpv1 = require('isRequestMpv1');
if (isRequestMpv1()) {
const events = extractEventsFromMpv1();
for (let i = 0; i < events.length; ++i) {
const event = events[i];
// Process event.
}
}
البنية
extractEventsFromMpv1();
الأذونات المرتبطة
يجب الحصول على إذن read_request
. يجب ضبط الإذن للسماح
بالوصول إلى ما يلي على الأقل:
body
query parameters
extractEventsFromMpv2
يترجم طلب الإصدار 2 الوارد من Measurement Protocol إلى قائمة أحداث بتنسيق المخطط الموحّد. تعرض قائمة الأحداث المُستخرَجة. يعرض خطأ إذا لم يكن الطلب بالتنسيق الصحيح.
مثال
const extractEventsFromMpv2 = require('extractEventsFromMpv2');
const isRequestMpv2 = require('isRequestMpv2');
if (isRequestMpv2()) {
const events = extractEventsFromMpv2();
for (let i = 0; i < events.length; ++i) {
const event = events[i];
// Process event.
}
}
البنية
extractEventsFromMpv2();
الأذونات المرتبطة
يجب الحصول على إذن read_request
. يجب ضبط الإذن للسماح
بالوصول إلى ما يلي على الأقل:
body
query parameters
fromBase64
تفكّ ترميز سلسلة بترميز base64. تعرض undefined
إذا كان الإدخال غير صالح.
البنية
fromBase64(base64EncodedString);
المَعلمات
المَعلمة | النوع | الوصف |
---|---|---|
base64EncodedString |
سلسلة | سلسلة Base64 المشفَّرة |
مثال
const fromBase64 = require('fromBase64');
const greeting = fromBase64('aGVsbG8=');
if (greeting === 'hello') {
// ...
}
الأذونات المرتبطة
بلا عُري
generateRandom
لعرض رقم عشوائي (عدد صحيح) ضمن نطاق معيّن.
مثال
const generateRandom = require('generateRandom');
const randomValue = generateRandom(0, 10000000);
البنية
generateRandom(min, max);
المَعلمات
المَعلمة | النوع | الوصف |
---|---|---|
min |
رقم | القيمة الصغرى المحتملة للعدد الصحيح الذي تم عرضه (شاملاً). |
max |
رقم | القيمة القصوى المحتملة للعدد الصحيح الذي تم عرضه (شاملاً). |
الأذونات المرتبطة
بلا عُري
getAllEventData
لعرض نسخة من بيانات الحدث
البنية
getAllEventData();
الأذونات المرتبطة
getClientName
عرض سلسلة تحتوي على اسم العميل الحالي
البنية
getClientName();
الأذونات المرتبطة
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();
الأذونات المرتبطة
getCookieValues
تعرض مصفوفة تحتوي على قيم جميع ملفات تعريف الارتباط التي تحمل الاسم المعني.
مثال
const getCookieValues = require('getCookieValues');
const lastVisit = getCookieValues('lastVisit')[0];
if (lastVisit) {
// ...
}
البنية
getCookieValues(name[, noDecode]);
المَعلمات
المَعلمة | النوع | الوصف |
---|---|---|
name |
سلسلة | اسم ملف تعريف الارتباط. |
noDecode |
boolean |
وفي حال true ، لن يتم فك ترميز قيم ملفات تعريف الارتباط قبل عرضها. وتكون الإعدادات التلقائية false .
|
الأذونات المرتبطة
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);
الأذونات المرتبطة
getGoogleAuth
لعرض عنصر تفويض، وعند استخدامه مع
sendHttpGet
أو sendHttpRequest
، سيتضمن
عنوان تفويض لـ Google Cloud APIs. تستخدم واجهة برمجة التطبيقات هذه بيانات الاعتماد التلقائية للتطبيق للعثور تلقائيًا على بيانات الاعتماد من بيئة الخادم.
مثال
const getGoogleAuth = require('getGoogleAuth');
const logToConsole = require('logToConsole');
const sendHttpGet = require('sendHttpGet');
const auth = getGoogleAuth({
scopes: ['https://www.googleapis.com/auth/datastore']
});
sendHttpGet(
'https://firestore.googleapis.com/v1/projects/my-project/databases/(default)/documents/collection/document',
{authorization: auth}
).then((result) => {
if (result.statusCode >= 200 && result.statusCode < 300) {
logToConsole('Result: ' + result.body);
data.gtmOnSuccess();
} else {
data.gtmOnFailure();
}
});
البنية
getGoogleAuth(scopes);
المَعلمات
المَعلمة | النوع | الوصف |
---|---|---|
scopes
|
مصفوفة | مصفوفة من نطاقات OAuth 2.0 Google API لطلب الوصول إليها. |
الأذونات المرتبطة
يجب الحصول على إذن use_google_credentials
. يجب ضبط الإذن باستخدام نطاق مسموح به واحد أو أكثر.
getGoogleScript
يسترد موردًا من مجموعة محدّدة مسبقًا من نصوص Google البرمجية وعرض واعدًا مع النص البرمجي والبيانات الوصفية للتخزين المؤقت ذات الصلة.
سيتحوّل الوعد إلى كائن يحتوي على مفتاحَين: script
وmetadata
. إذا تعذّر الطلب، سيتم رفض الوعد باستخدام مفتاح reason
.
سيحتوي الكائن metadata
على البيانات الوصفية التالية للتخزين المؤقت استنادًا إلى عناوين استجابة الموارد، ولن يتوفّر كل حقل إلا إذا كان العنوان المقابل متوفرًا في استجابة المورد.
{
'cache-control': string,
'expires': string,
'last-modified': string,
}
مثال
const getGoogleScript = require('getGoogleScript');
getGoogleScript('ANALYTICS').then((result) => {
// Operate on result.script and result.metadata here.
});
البنية
getGoogleScript(script[, options]);
المَعلمات
المَعلمة | النوع | الوصف |
---|---|---|
script |
سلسلة |
اسم النص البرمجي. النصوص البرمجية المتوافقة هي 'ANALYTICS' و'GTAG' و'GTM' .يسترجع الخيار 'ANALYTICS'
النص البرمجي لخدمة "إحصاءات Google" من
https://www.google-analytics.com/analytics.js .يسترجع الخيار 'GTAG' النص البرمجي لعلامة الموقع الشاملة (gtag.js) من https://www.googletagmanager.com/gtag/js .يسترجع الخيار 'GTM' النص البرمجي لأداة "إدارة العلامات من Google"
من https://www.googletagmanager.com/gtm.js .
|
options |
كائن | خيارات الطلب الاختيارية. انظر أدناه للاطّلاع على الخيارات المتاحة. |
الخيارات
Option | النوع | الوصف |
---|---|---|
id |
سلسلة |
تسري هذه السياسات على 'GTAG' مع رقم تعريف قياس gtag و'GTM' مع رقم تعريف حاوية الويب (مثل GTM-XXXX).
|
debug |
أيّ | في حال المصداقية، تطلب وتعرِض نسخة تصحيح الأخطاء من النص البرمجي للقياس. |
timeout |
رقم |
انتهت مهلة الطلب بالمللي ثانية، ويتم تجاهل القيم غير الموجبة. إذا انتهت مهلة الطلب، سيتم استدعاء الاستدعاء باستخدام undefined لقيمة النص البرمجي و{} لعنصر البيانات الوصفية.
|
ويتم تجاهل مفاتيح الخيارات غير المعروفة.
الأذونات المرتبطة
يجب الحصول على إذن send_http
. يجب ضبط الإذن للسماح
بالوصول إلى ما يلي على الأقل:
- السماح بخدمة Google Domains
getRemoteAddress
لعرض تمثيل سلسلة لعنوان IP الذي أنشأ فيه الطلب، مثل 12.345.67.890
لبروتوكول IPv4 أو 2001:0db8:85a3:0:0:8a2e:0370:7334
لبروتوكول IPv6، من خلال قراءة عناوين الطلبات مثل Redirected وX-Reseted-For.
ملاحظة: تبذل واجهة برمجة التطبيقات هذه قصارى جهدها لاكتشاف عنوان IP الأصلي، ولكنها لا تضمن دقة النتيجة.
البنية
getRemoteAddress();
الأذونات المرتبطة
يجب الحصول على إذن read_request
. يجب ضبط الإذن للسماح
بالوصول إلى ما يلي على الأقل:
- العنوانان
Forwarded
وX-Forwarded-For
- عنوان IP البعيد
getRequestBody
لعرض نص الطلب على هيئة سلسلة، في حال توفّره، أو على شكل undefined
بخلاف ذلك.
البنية
getRequestBody();
الأذونات المرتبطة
getRequestHeader
تعرض قيمة عنوان الطلب المُسمّى سلسلة في حال توفّرها أو على شكل
undefined
. وفي حال تكرار العنوان، يتم ضم القيم المعروضة
مع ', '
.
مثال
const getRequestHeader = require('getRequestHeader');
const host = getRequestHeader('host');
البنية
getRequestHeader(headerName);
المَعلمات
المَعلمة | النوع | الوصف |
---|---|---|
headerName |
سلسلة | اسم العنوان. هذه القيمة غير حساسة لحالة الأحرف. |
الأذونات المرتبطة
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();
الأذونات المرتبطة
getRequestQueryParameter
تعرض القيمة المفكوك ترميزها لمعلَمة سلسلة طلب البحث المسماة على أنّها سلسلة
أو undefined
في حال عدم توفّر المَعلمة. في حال تكرار المعلمة في سلسلة طلب البحث، سيتم عرض القيمة الأولى التي تظهر في سلسلة طلب البحث.
مثال
const getRequestQueryParameter = require('getRequestQueryParameter');
const query = getRequestQueryParameter('query');
if (query) {
// Process query here.
}
البنية
getRequestQueryParameter(name);
المَعلمات
المَعلمة | النوع | الوصف |
---|---|---|
name |
سلسلة | اسم مَعلمة طلب البحث |
الأذونات المرتبطة
getRequestQueryParameters
تعرض مَعلمات طلب البحث الواردة لطلب HTTP ككائن يحدد أسماء مَعلمات طلب البحث بالقيمة أو القيم المقابلة. يتم فك ترميز أسماء المعلمات وقيمها.
مثال
const getRequestQueryParameters = require('getRequestQueryParameters');
const queryParameters = getRequestQueryParameters();
if (queryParameters['search']) {
// Handle the search query here.
const maxResults = queryParameters['max_results'];
}
البنية
getRequestQueryParameters();
الأذونات المرتبطة
getRequestQueryString
يعرض طلب بحث الطلب كسلسلة، أو بدون علامة استفهام سابقة، أو سلسلة فارغة إذا كان عنوان URL للطلب لا يتضمّن سلسلة طلب بحث.
مثال
const getRequestQueryString = require('getRequestQueryString');
const queryString = getRequestQueryString();
if (queryString !== '') {
// Handle the query string.
}
البنية
getRequestQueryString();
الأذونات المرتبطة
getTimestamp
تمّت إزالة هذا العمود. أفضِّل getTimestampMillis.
لعرض رقم يمثل الوقت الحالي بالمللي ثانية منذ حقبة يونكس، كما يعرضه Date.now()
.
البنية
getTimestamp();
الأذونات المرتبطة
بلا عُري
getTimestampMillis
لعرض رقم يمثل الوقت الحالي بالمللي ثانية منذ حقبة يونكس، كما يعرضه Date.now()
.
البنية
getTimestampMillis();
الأذونات المرتبطة
بلا عُري
getType
تعرض سلسلة تصف نوع القيمة المحددة.
نوع الإدخال | القيمة المعروضة |
---|---|
سلسلة | 'string' |
رقم | 'number' |
boolean | 'boolean' |
null | 'null' |
غير محدّدة | 'undefined' |
مصفوفة | 'array' |
كائن | 'object' |
الوظيفة | 'function' |
مثال
const getType = require('getType');
const type = getType(value);
if (type === 'string') {
// Handle string input.
} else if (type === 'number') {
// Handle numeric input.
} else {
logToConsole('Unsupported input type: ', type);
}
البنية
getType(value);
المَعلمات
المَعلمة | النوع | الوصف |
---|---|---|
value |
أيّ | قيمة الإدخال |
الأذونات المرتبطة
بلا عُري
hmacSha256
تحسب توقيعًا مُشفَّرًا باستخدام رمز مصادقة الرسائل المستند إلى التجزئة (HMAC) مع SHA-256. يتم ضبط الإعدادات التلقائية على ترميز base64url
.
لاستخدام واجهة برمجة التطبيقات هذه، يجب ضبط متغيِّر بيئة SGTM_CREDENTIALS
على الخادم
على مسار ملف مفتاح JSON بالترميز UTF-8 بالتنسيق التالي:
{
"key1": "YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXowMTIzNDU2Nzg5",
"key2": "OTg3NjU0MzIxMHp5eHd2dXRzcnFwb25tbGtqaWhnZmVkY2Jh",
...
}
وتكون القيم هي مفاتيح HMAC بترميز base64.
مثال
const hmacSha256 = require('hmacSha256');
const toBase64 = require('toBase64');
const header = toBase64('{"alg":"HS256","typ":"JWT"}', {urlEncoding: true});
const claim = toBase64('{"sub":"1234567890","iat":1698164946}', {urlEncoding: true});
const signature = hmacSha256(header + '.' + claim, 'key1');
const jwt = header + "." + claim + '.' + signature;
البنية
hmacSha256(data, keyId, options)
المَعلمات
المَعلمة | النوع | الوصف |
---|---|---|
data |
سلسلة | يشير ذلك المصطلح إلى البيانات اللازمة لحساب قيمة بروتوكول HMAC. |
keyId
|
سلسلة | معرِّف مفتاح من ملف مفتاح JSON يشير إلى المفتاح المطلوب استخدامه. |
options
|
كائن | ضبط واجهة برمجة التطبيقات الاختياري: (راجِع الخيارات أدناه.) |
الخيارات
Option | النوع | الوصف |
---|---|---|
outputEncoding
|
سلسلة | تحدد تنسيق الترميز
للقيمة المعروضة. التنسيقات المتوافقة هي hex أو base64 أو base64url . ويتم ضبط القيمة التلقائية على
base64url إذا لم يتم تحديدها. |
الأذونات المرتبطة
الحد الأدنى لإصدار الصورة
isRequestMpv1
تعرض true
إذا كان الطلب الوارد هو طلب الإصدار 1 من Measurement Protocol، أو
false
غير ذلك.
مثال
const isRequestMpv1 = require('isRequestMpv1');
if (isRequestMpv1()) {
// Handle Measurement Protocol V1 request.
const events = extractEventsFromMpv1();
}
البنية
isRequestMpv1();
الأذونات المرتبطة
بلا عُري
isRequestMpv2
تعرض true
إذا كان الطلب الوارد هو طلب الإصدار 2 من Measurement Protocol، أو
false
غير ذلك.
مثال
const isRequestMpv2 = require('isRequestMpv2');
if (isRequestMpv2()) {
// Handle Measurement Protocol V2 request.
const events = extractEventsFromMpv2();
}
البنية
isRequestMpv2();
الأذونات المرتبطة
بلا عُري
logToConsole
تسجيل الوسيطة الخاصة بها(وسيطاتها) في وحدة التحكم.
تظهر هذه السجلات في مستكشف السجلات في Google Cloud Console.
من "مستكشف السجلات"، شغِّل الطلب logName =~ "stdout"
للاطّلاع على إدخالات السجلّ
التي تم إنشاؤها بواسطة واجهة برمجة التطبيقات هذه.
مثال
const logToConsole = require('logToConsole');
const that = 123;
const those = { ... };
logToConsole('that is: ', that, ' and those is: ', those);
البنية
logToConsole(argument1[, argument2, ...]);
المَعلمات
تستخدم واجهة برمجة التطبيقات وسيطة واحدة أو أكثر، ويتم تحويل كل وسيطة منها إلى سلسلة، إذا لزم الأمر، وتسجيلها في وحدة التحكّم.
الأذونات المرتبطة
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
.
الأذونات المرتبطة
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 |
الوظيفة | معاودة الاتصال التي يتم استدعاؤها على الفور، قبل بدء تنشيط العلامات. |
الأذونات المرتبطة
sendEventToGoogleAnalytics
تُرسِل حدثًا واحدًا باستخدام بيانات الأحداث الشائعة إلى "إحصاءات Google" مع عرض
واعد يتم حلّه إلى كائن باستخدام مفتاح location
أو يتم رفضه إلى كائن باستخدام مفتاح reason
. تستند الوجهة، Universal Analytics أو "إحصاءات Google 4"، إلى رقم تعريف القياس في بيانات الأحداث.
ويتم ضبط الحقل location
على عنوان location
في حال توفّره.
مثال
const sendEventToGoogleAnalytics = require('sendEventToGoogleAnalytics');
const setResponseHeader = require('setResponseHeader');
const setResponseStatus = require('setResponseStatus');
// Sends an event to Google Analytics and returns failure if the request did not
// succeed. Additionally, if the request resulted in a redirect request, the
// code nominates a redirect response to be returned.
sendEventToGoogleAnalytics(event).then((response) => {
if (response.location) {
setResponseHeader('location', response.location);
setResponseStatus(302);
} else {
setResponseStatus(200);
}
data.gtmOnSuccess();
}, (err) => {
setResponseStatus(500);
data.gtmOnFailure();
});
البنية
sendEventToGoogleAnalytics(event);
المَعلمات
المَعلمة | النوع | الوصف |
---|---|---|
event |
كائن | الحدث بتنسيق المخطط الموحّد |
الأذونات المرتبطة
يجب الحصول على إذن send_http
. يجب ضبط الإذن للسماح
بالوصول إلى ما يلي على الأقل:
- السماح بخدمة Google Domains
sendHttpGet
يقدّم طلب HTTP GET إلى عنوان URL المحدّد، ويعرض واعدًا يتم حله مع النتيجة بعد اكتمال الطلب أو انتهاء مهلته.
النتيجة التي تم حلها هي كائن يحتوي على ثلاثة مفاتيح: statusCode
وheaders
وbody
. في حال تعذّر الطلب (على سبيل المثال، عنوان URL غير صالح أو عدم توفّر مسار إلى المضيف أو تعذّر تفاوض طبقة المقابس الآمنة وما إلى ذلك)، سيتم رفض الوعد من خلال: {reason:
'failed'}
. إذا تم ضبط خيار timeout
وانتهت مهلة الطلب، سيتم رفض الوعد مع: {reason: 'timed_out'}
مثال
const sendHttpGet = require('sendHttpGet');
// Returns the response body as the value for a variable.
return sendHttpGet('https://example.com/item/' + data.itemId, {
headers: {key: 'value'},
timeout: 500,
}).then((result) => result.body, () => undefined);
البنية
sendHttpGet(url[, options]);
المَعلمات
المَعلمة | النوع | الوصف |
---|---|---|
url |
سلسلة | عنوان URL المطلوب. |
options
|
كائن | خيارات الطلب الاختيارية (راجِع الخيارات أدناه.) |
الخيارات
Option | النوع | الوصف |
---|---|---|
headers |
سلسلة | عناوين الطلبات الإضافية |
timeout
|
رقم | المهلة بالمللي ثانية قبل إلغاء الطلب وتكون الإعدادات التلقائية 15000 . |
authorization
|
كائن | كائن تفويض اختياري من
الاستدعاء إلى getGoogleAuth لتضمين
رؤوس التفويض عند إرسال طلبات
إلى googleapis.com . |
الأذونات المرتبطة
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 . |
الأذونات المرتبطة
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 المطلوب إرساله إلى المتصفِّح |
الأذونات المرتبطة
setCookie
لضبط ملف تعريف ارتباط أو حذفه باستخدام الخيارات المحدّدة.
لحذف ملف تعريف ارتباط، يجب ضبط ملف تعريف ارتباط باستخدام المسار والنطاق نفسيهما اللذَين تم إنشاء ملف تعريف الارتباط باستخدامهما، وتعيين قيمة لانتهاء الصلاحية تقع في الماضي،
مثل "Thu, 01 Jan 1970 00:00:00 GMT"
.
تجدر الإشارة إلى أنّه يجب طلب returnResponse لإرسال الردّ إلى العميل.
مثال
const setCookie = require('setCookie');
// Sets an httpOnly cookie with a max-age of 3600.
setCookie('cookieName', 'cookieValue', {'max-age': 3600, httpOnly: true});
البنية
setCookie(name, value[, options[, noEncode]]);
المَعلمات
المَعلمة | النوع | الوصف |
---|---|---|
name |
سلسلة | اسم ملف تعريف الارتباط. الاسم غير حساس لحالة الأحرف. |
value |
سلسلة | قيمة ملف تعريف الارتباط. |
options |
كائن | السمات الاختيارية لملفات تعريف الارتباط:domain وexpires وfallbackDomain وhttpOnly وmax- age وpath وsecure وsameSite. (اطّلِع على الخيارات أدناه.) |
noEncode |
boolean |
إذا كانت القيمة true، لن يتم ترميز قيمة ملف تعريف الارتباط. وتكون الإعدادات التلقائية
false .
|
domain: المضيف الذي سيتم إرسال ملف تعريف الارتباط إليه. في حال ضبط هذه السياسة على القيمة الخاصة "auto" (تلقائي)، سيتم احتساب المضيف تلقائيًا باستخدام الاستراتيجية التالية:
- eTLD+1 لعنوان
Forwarded
، إن توفّر - eTLD+1 لعنوان
X-Forwarded-Host
، إن توفّر - eTLD+1 لعنوان
Host
- eTLD+1 لعنوان
انتهاء الصلاحية: الحد الأقصى لمدة صلاحية ملف تعريف الارتباط. ويجب أن تكون سلسلة التاريخ هذه بتنسيق التوقيت العالمي المتفق عليه (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'
.
الأذونات المرتبطة
setPixelResponse
لتعيين نص الاستجابة على ملف GIF 1x1، وتعيين العنوان Content-Type على "image/gif"، وضبط عناوين التخزين المؤقت بحيث لا يخزّن برامج وكيل المستخدم الاستجابة مؤقتًا، ويضبط حالة الاستجابة على 200.
تجدر الإشارة إلى أنّه يجب طلب returnResponse لإرسال الردّ إلى العميل.
البنية
setPixelResponse();
الأذونات المرتبطة
يجب الحصول على إذن access_response
. يجب ضبط الإذن للسماح
بالوصول إلى ما يلي على الأقل:
headers
- يجب أن يسمح بالمفاتيح التالية:content-type
cache-control
expires
pragma
body
status
setResponseBody
لضبط نص الاستجابة على الوسيطة.
تجدر الإشارة إلى أنّه يجب طلب returnResponse لإرسال الردّ إلى العميل.
البنية
setResponseBody(body[, encoding]);
المَعلمات
المَعلمة | النوع | الوصف |
---|---|---|
body |
سلسلة | القيمة المطلوب ضبطها كنص الاستجابة |
encoding |
سلسلة |
ترميز الأحرف لنص الاستجابة (الإعداد التلقائي هو 'utf8' ). وتشمل القيم المسموح بها 'ascii' و'utf8' و'utf16le' و'ucs2' و'base64' و'latin1' و'binary' و'hex' .
|
الأذونات المرتبطة
يجب الحصول على إذن access_response
. يجب ضبط الإذن للسماح
بالوصول إلى ما يلي على الأقل:
body
setResponseHeader
لضبط عنوان في الاستجابة التي سيتم عرضها. إذا سبق أن ضبطت واجهة برمجة التطبيقات هذه عنوانًا يحمل هذا الاسم (غير حساس لحالة الأحرف)، سيؤدي الطلب الأخير إلى استبدال القيمة التي حدّدها المتصل السابق أو محوها.
تجدر الإشارة إلى أنّه يجب طلب returnResponse لإرسال الردّ إلى العميل.
البنية
setResponseHeader(name, value);
المَعلمات
المَعلمة | النوع | الوصف |
---|---|---|
name |
سلسلة | اسم العنوان. أسماء عناوين HTTP غير حساسة لحالة الأحرف، لذا سيتم كتابة اسم العنوان بأحرف صغيرة. |
value |
سلسلة غير محدَّدة | تمثّل هذه السمة قيمة العنوان. إذا كانت القيمة فارغة أو غير معرَّفة، يؤدي ذلك إلى محو العنوان المُسمّى من الاستجابة التي سيتم عرضها. |
الأذونات المرتبطة
يجب الحصول على إذن access_response
. يجب ضبط الإذن للسماح
بالوصول إلى ما يلي على الأقل:
headers
setResponseStatus
لضبط رمز حالة HTTP للاستجابة التي سيتم عرضها.
تجدر الإشارة إلى أنّه يجب طلب returnResponse لإرسال الردّ إلى العميل.
البنية
setResponseStatus(statusCode);
المَعلمات
المَعلمة | النوع | الوصف |
---|---|---|
statusCode |
رقم | رمز حالة HTTP المطلوب عرضه. |
الأذونات المرتبطة
يجب الحصول على إذن access_response
. يجب ضبط الإذن للسماح
بالوصول إلى ما يلي على الأقل:
status
sha256
تحسب ملخص SHA-256 للمدخل ويستدعي معاودة الاتصال بالملخص مع ترميز base64، ما لم يحدد الكائن options
ترميزًا للإخراج
مختلفًا.
يتطابق سلوك وتوقيع واجهة برمجة التطبيقات هذا مع واجهة برمجة التطبيقات sha256
لحاويات الويب،
ومع ذلك، يجب أن تستخدم النماذج المخصَّصة في حاويات الخادم واجهة برمجة التطبيقات
sha256Sync
لإنشاء رمز أبسط.
مثال
const encodeUriComponent = require('encodeUriComponent');
const sendHttpGet = require('sendHttpGet');
const sha256 = require('sha256');
sha256('inputString', (digest) => {
sendHttpGet('https://example.com/collect?id=' + encodeUriComponent(digest));
});
sha256('inputString', (digest) => {
sendHttpGet('https://example.com/collect?id=' + encodeUriComponent(digest));
}, {outputEncoding: 'hex'});
البنية
sha256(input, onSuccess, options = undefined);
المَعلمات
المَعلمة | النوع | الوصف |
---|---|---|
input |
سلسلة | السلسلة المطلوب تجزئتها. |
onSuccess |
الوظيفة |
يتم استدعاؤه مع الملخص الناتج، ويتم ترميزه باستخدام base64، ما لم يحدد الكائن options ترميزًا مختلفًا للإخراج.
|
options |
كائن |
كائن الخيارات الاختياري لتحديد ترميز الإخراج. وفي حال تحديدها، يجب أن يحتوي الكائن على المفتاح outputEncoding مع قيمة واحدة من base64 أو hex .
|
الأذونات المرتبطة
بلا عُري
sha256Sync
تحسب هذه الدالة ملخص SHA-256 للإدخال ويعرضها بترميز base64،
ما لم يحدد الكائن options
ترميزًا مختلفًا للإخراج.
مثال
const encodeUriComponent = require('encodeUriComponent');
const sendHttpGet = require('sendHttpGet');
const sha256Sync = require('sha256Sync');
const digestBase64 = sha256Sync('inputString');
const digestHex = sha256Sync('inputString', {outputEncoding: 'hex'});
sendHttpGet('https://example.com/collect?id=' + encodeUriComponent(digestBase64));
sendHttpGet('https://example.com/collect?id=' + encodeUriComponent(digestHex));
البنية
sha256Sync(input, options = undefined);
المَعلمات
المَعلمة | النوع | الوصف |
---|---|---|
input |
سلسلة | السلسلة المطلوب تجزئتها. |
options |
كائن |
كائن الخيارات الاختياري لتحديد ترميز الإخراج. وفي حال تحديدها، يجب أن يحتوي الكائن على المفتاح outputEncoding مع قيمة واحدة من base64 أو hex .
|
الأذونات المرتبطة
بلا عُري
templateDataStorage
لعرض كائن مع طرق للوصول إلى تخزين بيانات النموذج. يسمح تخزين بيانات النموذج بمشاركة البيانات عبر عمليات تنفيذ نموذج واحد. تظل البيانات المخزنة في تخزين بيانات النموذج على الخادم الذي يقوم بتشغيل الحاوية. في معظم الحالات، هناك خوادم متعددة تشغل الحاوية، لذا لا يضمن تخزين البيانات في تخزين بيانات النموذج حصول كل طلب لاحق على إمكانية الوصول إلى البيانات.
تشير "البيانات" في اسم "templateDataStorage" إلى حقيقة أنه يمكن تخزين أنواع البيانات العادية وغير الوظيفية فقط باستخدام واجهة برمجة التطبيقات هذه. وسيتم تخزين أي دوال أو إشارات إلى الدوال التي تم تمريرها إلى واجهة برمجة التطبيقات على أنّها null
بدلاً من ذلك.
البنية
const templateDataStorage = require('templateDataStorage');
// Returns a copy of the value stored for the given key, or null if nothing
// is stored with that key.
templateDataStorage.getItemCopy(key);
// Stores a copy of the value for the given key (or removes the data stored
// for the given key if the input value is null).
templateDataStorage.setItemCopy(key, value);
// Removes the value stored for the given key, if present.
templateDataStorage.removeItem(key);
// Deletes all values stored for the current template.
templateDataStorage.clear();
مثال
const sendHttpGet = require('sendHttpGet');
const setResponseBody = require('setResponseBody');
const setResponseStatus = require('setResponseStatus');
const templateDataStorage = require('templateDataStorage');
// Check to see if the item is in the cache.
const cachedBody = templateDataStorage.getItemCopy(data.key);
if (cachedBody) {
setResponseBody(cachedBody);
data.gtmOnSuccess();
return;
}
sendHttpGet(data.url).then((result) => {
if (result.statusCode >= 200 && result.statusCode < 300) {
setResponseBody(result.body);
templateDataStorage.setItemCopy(data.key, result.body);
data.gtmOnSuccess();
} else {
data.gtmOnFailure();
}
setResponseStatus(result.statusCode);
});
الأذونات المرتبطة
testRegex
لاختبار سلسلة مقابل تعبير عادي تم إنشاؤه باستخدام createRegex
API. تعرض true
في حال تطابق التعبير العادي. تعرِض false
في الحالات الأخرى.
ويكون التعبير العادي الذي تم إنشاؤه باستخدام العلامة العامة عبارة عن حالة. راجِع مستندات RegExp لمعرفة التفاصيل.
مثال
const createRegex = require('createRegex');
const testRegex = require('testRegex');
const domainRegex = createRegex('\\w+\\.com', 'i');
// createRegex returns null if the regex is invalid or Re2 is not available.
if (domainRegex === null) return;
// Returns true
testRegex(domainRegex, 'example.com/foobar');
البنية
testRegex(regex, string);
المَعلمات
المَعلمة | النوع | الوصف |
---|---|---|
regex |
كائن | التعبير العادي المطلوب اختباره، والذي يتم عرضه من createRegex API |
string |
سلسلة | سلسلة الاختبار المطلوب اختبارها. |
الأذونات المرتبطة
بلا عُري
toBase64
لترميز سلسلة بالشكل base64 أو base64url. يتم ضبط التشفير تلقائيًا على ترميز base64.
البنية
toBase64(input, options);
المَعلمات
المَعلمة | النوع | الوصف |
---|---|---|
input |
سلسلة | سلسلة مطلوب ترميزها |
options
|
كائن | ضبط واجهة برمجة التطبيقات الاختياري: (راجِع الخيارات أدناه.) |
الخيارات
Option | النوع | الوصف | الحد الأدنى للإصدار |
---|---|---|---|
urlEncoding
|
boolean | إذا كانت القيمة "صحيح"، سيتم
ترميز النتيجة باستخدام
تنسيق
base64url . |
1.0.0 |
مثال
const toBase64 = require('toBase64');
const base64Hello = toBase64('hello');
const base64UrlHello = toBase64('hello', {urlEncoding: true});
الأذونات المرتبطة
بلا عُري
BigQuery
تعرض كائنًا يوفر دوال BigQuery.
تسمح الدالة BigQuery.insert
بكتابة البيانات في جدول BigQuery. ويعرض وعدًا يتم حلّه عند إجراء إدراج ناجح أو رفضه بسبب خطأ.
عندما تنجح عملية الإدراج، يتم حل الوعد بدون أي وسيطات.
عندما يتعذّر الإدراج، يتم رفض الوعد من خلال إضافة قائمة عناصر تحتوي على سبب الخطأ وربما كائن صف في حال حدوث خطأ. من الممكن إكمال جزء من الطلب بنجاح، بينما لا يتم إكمال الأجزاء الأخرى. يتم رفض الميزة في هذه الحالة من خلال إدراج قائمة بالأخطاء لكل صف يتضمّن كائن صف للمساعدة في تمييز الصفوف التي تم إدراجها (يمكنك الاطّلاع على أمثلة عن الأخطاء أدناه). راجِع وثائق BigQuery بشأن رسائل الخطأ للحصول على مزيد من المعلومات.
البنية
BigQuery.insert(connectionInfo, rows[, options]);
المَعلمة | النوع | الوصف |
---|---|---|
connectionInfo |
كائن |
تحدِّد المعلومات المطلوبة للربط بجدول BigQuery. ثمة
معلَمة اختيارية واحدة ومَعلمتَين مطلوبتَين:
|
rows |
مصفوفة | الصفوف المطلوب إدراجها في الجدول. |
options |
كائن | خيارات الطلب الاختيارية. والخيارات المتاحة هي: ignoreUnknownValues وskipInvalidRows. يتم تجاهل مفاتيح الخيارات غير المعروفة. (اطّلِع على الخيارات أدناه.) |
المَعلمة | النوع | الوصف |
---|---|---|
ignoreUnknownValues |
boolean | في حال ضبطها على true ، اقبل الصفوف التي تحتوي على قيم لا تتطابق مع المخطط. ويتم تجاهل القيم غير المعروفة. ويكون الإعداد التلقائي
على false . |
skipInvalidRows |
boolean | في حال ضبط السياسة على true ، أدرِج جميع الصفوف الصالحة في الطلب،
حتى في حال توفُّر صفوف غير صالحة. وتكون الإعدادات التلقائية false . |
يعني الخطأ "لم يتم العثور على الوحدة" أنه من المحتمل أن تستخدم حاوية الخادم لديك إصدارًا قديمًا من الصورة لم يتضمن وحدة BigQuery بعد. يُرجى إعادة نشر حاوية الخادم باستخدام الإعدادات نفسها باستخدام النص البرمجي للنشر. سيتم تضمين الوحدة تلقائيًا بعد اكتمال العملية.
يتضمن الخطأ غير المتعلق بالإدراج عادةً كائن خطأ واحدًا مع مفتاح reason
:
[{reason: 'invalid'}]
يمكن أن يحتوي خطأ الإدراج على عناصر أخطاء متعددة مع مصفوفة errors
وكائن row
. فيما يلي مثال على استجابة خطأ من إدراج صفين حيث يحتوي صف واحد فقط على خطأ:
[
{
"errors": [
{
"reason":"invalid"
}
],
"row": {
"string_col":"otherString",
"number_col":-3,
"bool_col":3
}
},
{
"errors": [
{
"reason":"stopped"
}
],
"row": {
"string_col":"stringValue",
"number_col":5,
"bool_col:false
}
}
]
مثال
const BigQuery = require('BigQuery');
const connectionInfo = {
'projectId': 'gcp-cloud-project-id',
'datasetId': 'destination-dataset',
'tableId': 'destination-table',
};
const rows = [{
'column1': 'String1',
'column2': 1234,
}];
const options = {
'ignoreUnknownValues': true,
'skipInvalidRows': false,
};
BigQuery.insert(connectionInfo, rows, options)
.then(data.gtmOnSuccess, data.gtmOnFailure);
الأذونات المرتبطة
Firestore
لعرض كائن يوفر دوال Firestore.
تتوافق واجهة برمجة التطبيقات هذه مع Firestore في الوضع الأصلي فقط، وليس Firestore في وضع تخزين البيانات.
Firestore.read
تقرأ الدالة Firestore.read
البيانات من مستند Firestore وتعرض وعدًا يؤدي إلى كائن يحتوي على مفتاحَين: id
وdata
. في حال عدم توفّر المستند، يتم رفض الوعد إذا كان هناك عنصر يحتوي على مفتاح reason
يساوي not_found
.
البنية
Firestore.read(path[, options]);
المَعلمة | النوع | الوصف |
---|---|---|
path |
سلسلة | المسار إلى المستند أو المجموعة يجب ألا يبدأ أو ينتهي بالعلامة "/". |
options |
كائن | خيارات الطلب الاختيارية وتشمل الخيارات المتاحة: projectId وdisableCache، وtransaction. ويتم تجاهل مفاتيح الخيارات غير المعروفة. (اطّلِع على الخيارات أدناه.) |
المَعلمة | النوع | الوصف |
---|---|---|
projectId |
سلسلة | Optional. رقم تعريف مشروع Google Cloud Platform في حال حذفه، يتم استرداد
projectId من متغيّر البيئة
GOOGLE_CLOUD_PROJECT طالما تم ضبط إعداد إذن
access_firestore
لرقم تعريف المشروع على * أو
GOOGLE_CLOUD_PROJECT . إذا كانت حاوية الخادم قيد التشغيل على Google Cloud، سيكون GOOGLE_CLOUD_PROJECT قد سبق ضبطه على رقم تعريف مشروع Google Cloud. |
disableCache |
boolean | Optional. يحدد ما إذا كان سيتم إيقاف ذاكرة التخزين المؤقت أم لا. يكون التخزين المؤقت مفعَّلاً تلقائيًا، ما يؤدي إلى تخزين النتائج مؤقتًا طوال مدة الطلب. |
transaction |
سلسلة | Optional. القيمة التي تم استردادها من Firestore.runTransaction(). يحدد العملية المطلوب استخدامها ضمن المعاملة. |
مثال
const Firestore = require('Firestore');
return Firestore.read('collection/document', {
projectId: 'gcp-cloud-project-id',
}).then((result) => result.data.key, () => undefined);
Firestore.write
تكتب الدالة Firestore.write
البيانات إلى مستند أو مجموعة
Firestore. إذا كان المسار إلى مجموعة، سيتم إنشاء مستند
برقم تعريف يتم إنشاؤه عشوائيًا. إذا كان المسار إلى مستند ولم يكن موجودًا،
فسيتم إنشاؤه. تعرض واجهة برمجة التطبيقات هذه وعدًا يفي بمعرّف المستند
الذي تمت إضافته أو تعديله. إذا تم استخدام خيار المعاملة، تستمر واجهة برمجة التطبيقات في عرض الوعد، ولكنها لن تحتوي على المعرف لأنه يتم تجميع البيانات.
البنية
Firestore.write(path, input[, options]);
المَعلمات
المَعلمة | النوع | الوصف |
---|---|---|
path |
سلسلة | المسار إلى المستند أو المجموعة يجب ألا يبدأ أو ينتهي بالعلامة "/". |
input |
كائن | القيمة المطلوب كتابتها في المستند. إذا تم ضبط خيار الدمج، ستدمج واجهة برمجة التطبيقات المفاتيح من الإدخال في المستند. |
options |
كائن | خيارات الطلب الاختيارية وتشمل الخيارات المتاحة: projectId وmerge وtransaction. يتم تجاهل مفاتيح الخيارات غير المعروفة. (اطّلِع على الخيارات أدناه.) |
المَعلمة | النوع | الوصف |
---|---|---|
projectId |
سلسلة | Optional. رقم تعريف مشروع Google Cloud Platform في حال حذفه، يتم استرداد
projectId من متغيّر البيئة
GOOGLE_CLOUD_PROJECT طالما تم ضبط إعداد إذن
access_firestore
لرقم تعريف المشروع على * أو
GOOGLE_CLOUD_PROJECT . إذا كانت حاوية الخادم قيد التشغيل على Google Cloud، سيكون GOOGLE_CLOUD_PROJECT قد سبق ضبطه على رقم تعريف مشروع Google Cloud. |
merge |
boolean | Optional. في حال ضبط هذه السياسة على
true ، يتم دمج المفاتيح من مصدر الإدخال في المستند،
وإلا ستلغي الطريقة المستند بأكمله. وتكون الإعدادات التلقائية
false . |
transaction |
سلسلة | Optional. القيمة التي تم استردادها من Firestore.runTransaction(). يحدد العملية المطلوب استخدامها ضمن المعاملة. |
مثال
const Firestore = require('Firestore');
const input = {key1: 'value1', key2: 12345};
Firestore.write('collection/document', input, {
projectId: 'gcp-cloud-project-id',
merge: true,
}).then((id) => {
data.gtmOnSuccess();
}, data.gtmOnFailure);
Firestore.query
تستعلم الدالة Firestore.query
عن المجموعة المحددة وتعرض الوعد الذي يتم حله في مصفوفة من مستندات Firestore التي تطابق شروط الاستعلام. عنصر مستند Firestore هو نفسه الوارد أعلاه في
Firestore.read
. إذا لم تكن هناك مستندات تطابق شروط الاستعلام،
فسيتم حل الوعد الذي تم إرجاعه إلى صفيف فارغ.
البنية
Firestore.query(collection, queryConditions[, options]);
المَعلمة | النوع | الوصف |
---|---|---|
collection |
سلسلة | المسار إلى المجموعة. يجب ألا يبدأ أو ينتهي بالعلامة "/". |
queryConditions |
مصفوفة | مصفوفة من شروط الاستعلام. ويأتي كل طلب بحث في شكل مصفوفة مكونة من ثلاث قيم: key وoperator وdigitalValue. E.g.:
[[‘id’, ‘<’, ‘5’], [‘state’, ‘==’, ‘CA’]]. يتم ربط الشروط معًا لإنشاء نتيجة طلب البحث. يُرجى الرجوع إلى عوامل تشغيل طلبات البحث في Firestore للاطّلاع على قائمة بعوامل تشغيل طلبات البحث المتوافقة. |
options |
كائن | خيارات الطلب الاختيارية وتشمل الخيارات المتاحة: projectId وdisablecache وlimit وtransaction. ويتم تجاهل مفاتيح الخيارات غير المعروفة. (اطّلِع على الخيارات أدناه.) |
المَعلمة | النوع | الوصف |
---|---|---|
projectId |
سلسلة | Optional. رقم تعريف مشروع Google Cloud Platform في حال حذفه، يتم استرداد
projectId من متغيّر البيئة
GOOGLE_CLOUD_PROJECT طالما تم ضبط إعداد إذن
access_firestore
لرقم تعريف المشروع على * أو
GOOGLE_CLOUD_PROJECT . إذا كانت حاوية الخادم قيد التشغيل على Google Cloud، سيكون GOOGLE_CLOUD_PROJECT قد سبق ضبطه على رقم تعريف مشروع Google Cloud. |
disableCache |
boolean | Optional. يحدد ما إذا كان سيتم إيقاف ذاكرة التخزين المؤقت أم لا. يكون التخزين المؤقت مفعَّلاً تلقائيًا، ما يؤدي إلى تخزين النتائج مؤقتًا طوال مدة الطلب. |
limit |
رقم | Optional. لتغيير الحد الأقصى لعدد النتائج التي يعرضها طلب البحث، ويكون الإعداد التلقائي هو 5. |
transaction |
سلسلة | Optional. القيمة التي تم استردادها من Firestore.runTransaction(). يحدد العملية المطلوب استخدامها ضمن المعاملة. |
مثال
const Firestore = require('Firestore');
const queries = const queries = [['id', '==', '5']];
return Firestore.query('collection', queries, {
projectId: 'gcp-cloud-project-id',
limit: 1,
}).then((documents) => documents[0].data.key, () => undefined);
Firestore.runTransaction
تتيح الدالة Firestore.runTransaction
للمستخدم القراءة
والكتابة من Firestore بشكل ذري. في حال حدوث عملية كتابة متزامنة أو حدوث تضارب في معاملة أخرى،
ستتم إعادة محاولة إجراء المعاملة مرتين. وإذا فشلت بعد ثلاث محاولات إجمالاً، سيتم رفض واجهة برمجة التطبيقات مع ظهور خطأ. تعرض واجهة برمجة التطبيقات هذه وعدًا يحلّ مجموعة من معرّفات المستندات لكل عملية كتابة إذا تمت العملية بنجاح، وسيتم رفضه مع ظهور الخطأ إذا تعذّر ذلك.
البنية
Firestore.runTransaction(callback[, options]);
المَعلمات
المَعلمة | النوع | الوصف |
---|---|---|
callback |
الوظيفة | معاودة الاتصال التي يتم استدعاؤها باستخدام معرِّف معاملة سلسلة. يمكن تمرير معرِّف المعاملة إلى طلبات البيانات من واجهة برمجة التطبيقات للقراءة/الكتابة/الاستعلام. يجب أن تعرض دالة رد الاتصال هذه وعدًا. قد يتم تنفيذ معاودة الاتصال حتى ثلاث مرات قبل أن يتعذّر إتمام العملية. |
options |
كائن | خيارات الطلب الاختيارية الخيار المتوافق فقط هو projectId. يتم تجاهل مفاتيح الخيارات غير المعروفة. (اطّلِع على الخيارات أدناه.) |
المَعلمة | النوع | الوصف |
---|---|---|
projectId |
سلسلة | Optional. رقم تعريف مشروع Google Cloud Platform في حال حذفه، يتم استرداد
projectId من متغيّر البيئة
GOOGLE_CLOUD_PROJECT طالما تم ضبط إعداد إذن
access_firestore
لرقم تعريف المشروع على * أو
GOOGLE_CLOUD_PROJECT . إذا كانت حاوية الخادم قيد التشغيل على Google Cloud، سيكون GOOGLE_CLOUD_PROJECT قد سبق ضبطه على رقم تعريف مشروع Google Cloud. |
مثال
const Firestore = require('Firestore');
const path = 'collection/document';
const projectId = 'gcp-cloud-project-id';
Firestore.runTransaction((transaction) => {
const transactionOptions = {
projectId: projectId,
transaction: transaction,
};
// Must return a promise.
return Firestore.read(path, transactionOptions).then((result) => {
const newInputCount = result.data.inputCount + 1;
const input = {key1: 'value1', inputCount: newInputCount};
return Firestore.write(path, input, transactionOptions);
});
}, {
projectId: projectId
}).then((ids) => {
data.gtmOnSuccess();
}, data.gtmOnFailure);
سيتم رفض الأخطاء المتوفّرة في كل دالة من وظائف Firestore مع عنصر يحتوي على مفتاح reason
:
Firestore.read(...).then(onSuccess, (error) => {
if (error.reason === 'unknown') {
// Handle the unknown error here.
}
});
يمكن أن تتضمن أسباب الخطأ، على سبيل المثال لا الحصر، رموز أخطاء واجهة برمجة التطبيقات Firestore REST.
الأذونات المرتبطة
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
(عادةً باستخدام علامة)، سيتم تنفيذ عملية معاودة الاتصال بشكل متزامن. ويتم تنفيذ هذه العملية باستخدام مَعلمتَين:
messageType:string
message:Object
إذا تمت إضافة الاتصال في أحد البرامج، سيتلقى الرد الرسائل عبر جميع الأحداث التي ينشئها البرنامج. إذا كان يجب أن يتلقّى رد الاتصال رسائل
من حدث معيّن فقط، عليك ربط واجهة برمجة التطبيقات هذه بالحدث باستخدام bindToEvent
في دالة onStart
في واجهة برمجة التطبيقات runContainer
. اطّلِع على المثال.
البنية
const addMessageListener = require('addMessageListener');
addMessageListener('send_pixel', (messageType, message) => {
// This will be run whenever something sends a 'send_pixel' message.
});
المَعلمات
المَعلمة | النوع | الوصف |
---|---|---|
messageType |
سلسلة | نوع الرسالة المطلوب الاستماع إليها. إذا لم تكن القيمة سلسلة، سيتم فرضها على سلسلة. |
callback |
الوظيفة | تمثل هذه السمة رد الاتصال الذي سيتم تنفيذه عند إرسال رسالة من نوع الرسالة المناسب. إذا لم تكن معاودة الاتصال وظيفة، لن تفعل واجهة برمجة التطبيقات أي شيء. |
مثال
const addMessageListener = require('addMessageListener');
const claimRequest = require('claimRequest');
const extractEventsFromMpv1 = require('extractEventsFromMpv1');
const returnResponse = require('returnResponse');
const runContainer = require('runContainer');
claimRequest();
addMessageListener('send_pixel', (messageType, message) => {
// This will be run whenever a tag sends a 'send_pixel' message.
});
const events = extractEventsFromMpv1();
let eventsCompleted = 0;
events.forEach((event, i) => {
runContainer(events[i], /* onComplete= */ () => {
if (events.length === ++eventsCompleted) {
returnResponse();
}
}, /* onStart= */ (bindToEvent) => {
if (i === 0) {
bindToEvent(addMessageListener)('send_pixel', (messageType, message) => {
// This will be called whenever a tag for the first event sends a
// 'send_pixel' message.
});
}
});
});
الأذونات المرتبطة
يجب الحصول على إذن use_message
. يجب ضبط الإذن للسماح بما يلي على الأقل:
- نوع رسالة يحتوي على
Usage
منlisten
أوlisten_and_send
.
hasMessageListener
يتم إرجاع القيمة "صحيح" إذا تمت إضافة مستمع للرسالة لنوع الرسالة المحدّد. وتعرض القيمة false في الحالات الأخرى.
البنية
const hasMessageListener = require('hasMessageListener');
hasMessageListener('send_pixel');
الأذونات المرتبطة
بلا عُري
sendMessage
لإرسال رسالة من النوع المحدّد إلى مستمع مسجَّل يمكن استخدام ذلك لإرسال الرسائل من علامة معيّنة إلى العميل الذي شغّل الحاوية.
البنية
const sendMessage = require('sendMessage');
sendMessage('send_pixel', {url: 'https://analytics.example.com/collect'});
المَعلمات
المَعلمة | النوع | الوصف |
---|---|---|
messageType |
سلسلة | نوع الرسالة المطلوب إرسالها إذا لم تكن القيمة سلسلة، سيتم فرضها على سلسلة. |
message |
كائن | الرسالة المطلوب إرسالها. إذا لم تكن الرسالة كائنًا، لن تفعل واجهة برمجة التطبيقات أي شيء. |
الأذونات المرتبطة
يجب الحصول على إذن use_message
. يجب ضبط الإذن للسماح بما يلي على الأقل:
- نوع رسالة يحتوي على
Usage
منlisten_and_send
أوsend
.
Object
لعرض كائن يوفر طرق Object
.
توفّر الطريقة keys()
سلوك
Object.keys() للمكتبة العادية. تعرض الدالة صفيفًا من أسماء الخصائص القابلة للتعداد لكائن معين بنفس الترتيب الذي تعرضه التكرار الحلقي for...in...
. إذا لم تكن قيمة الإدخال
كائنًا، سيتم فرضها على كائن.
توفّر الطريقة values()
سلوك
Object.values() للمكتبة العادية. تعرض الدالة صفيفًا من قيم خاصية التعداد الخاصة بكائن معين وبنفس الترتيب الذي تعرضه التكرار الحلقي for...in...
. إذا لم تكن قيمة الإدخال كائنًا،
سيتم فرضها على كائن.
توفّر الطريقة entries()
سلوك
Object.entries() للمكتبة العادية. تعرض الدالة صفيفًا من خاصية التعداد الخاصة بكائن معين
أزواج [key, value]
بنفس الترتيب الذي تعرضه حلقة for...in...
. إذا لم تكن قيمة الإدخال كائنًا، فسيتم فرضها على كائن.
توفر الطريقة freeze()
سلوك
Object.freeze() للمكتبة العادية. لم يعد من الممكن تغيير أي كائن مجمّد، فتجميد الكائن يمنع إضافة خصائص جديدة إليه، وإزالة الخصائص الموجودة، وتغيير قيم الخصائص الموجودة. تعرض دالة freeze()
الكائن نفسه الذي تم تمريره فيه. سيتم التعامل مع الوسيطة الأساسية أو الفارغة كما لو كانت
كائنًا مجمدًا، وسيتم عرضها.
توفّر الطريقة delete()
سلوك عامل التشغيل
للمكتبة العادية. تزيل المفتاح المحدد من الكائن ما لم يتم تجميد الكائن.
وعلى غرار عامل التشغيل حذف "المكتبة العادية"، فإنه يعرض true
إذا كانت قيمة الإدخال الأولى (objectInput
) كائنًا لم يتم تجميده حتى إذا كانت قيمة الإدخال الثانية (keyToDelete
) تحدّد مفتاحًا غير موجود. تعرض القيمة false
في
جميع الحالات الأخرى. ومع ذلك، فإنه يختلف عن عامل حذف حذف "المكتبة القياسية"
في الطرق التالية:
- لا يمكن أن يكون الحقل "
keyToDelete
" سلسلة محدّدة بنقاط محدَّدة وتحدّد مفتاحًا مدمجًا. - لا يمكن استخدام
delete()
لإزالة عناصر من مصفوفة. - لا يمكن استخدام
delete()
لإزالة أي مواقع من النطاق العمومي.
البنية
Object.keys(objectInput)
Object.values(objectInput)
Object.entries(objectInput)
Object.freeze(objectInput)
Object.delete(objectInput, keyToDelete)
المَعلمات
Object.keys
المَعلمة | النوع | الوصف |
---|---|---|
objectInput | أيّ | تمثّل هذه السمة الكائن المطلوب تعداد مفاتيحه. إذا لم يكن الإدخال كائنًا، سيتم فرضه على كائن. |
Object.values
المَعلمة | النوع | الوصف |
---|---|---|
objectInput | أيّ | يشير ذلك المصطلح إلى الكائن المطلوب تعداد قيمه. إذا لم يكن الإدخال كائنًا، سيتم فرضه على كائن. |
Object.entries
المَعلمة | النوع | الوصف |
---|---|---|
objectInput | أيّ | يشير ذلك المصطلح إلى الكائن المطلوب تعداده من خلال أزواج المفتاح/القيمة. إذا لم يكن الإدخال كائنًا، سيتم فرضه على كائن. |
Object.freeze
المَعلمة | النوع | الوصف |
---|---|---|
objectInput | أيّ | الكائن المراد تجميده. إذا لم يكن المُدخل كائنًا، سيتم التعامل معه على أنّه كائن مجمّد. |
Object.delete
المَعلمة | النوع | الوصف |
---|---|---|
objectInput | أيّ | تمثّل هذه السمة الكائن المطلوب حذف مفتاحه. |
keyToDelete | سلسلة | مفتاح المستوى الأعلى الذي تريد حذفه. |
مثال
const Object = require('Object');
// The keys of an object are enumerated in an array.
const keys = Object.keys({foo: 'bar'});
// The values of an object are enumerated in an array.
const values = Object.values({foo: 'bar'});
// The key/value pairs of an object are enumerated in an array.
const entries = Object.entries({foo: 'bar'});
// The input object is frozen.
const frozen = Object.freeze({foo: 'bar'});
// The key is removed from the input object.
const obj1 = {deleteme: 'value'};
Object.delete(obj1, 'deleteme');
// Only a top-level key can be specified as the key to delete.
const obj2 = {nested: {key: 'value'}};
Object.delete(obj2, 'nested.key'); // This has no effect.
Object.delete(obj2.nested, 'key'); // This deletes the nested key.
Promise
تعرض كائنًا يوفر طرقًا للتفاعل مع الوعود.
تتشابه الوعود من الناحية العملية مع وعود JavaScript. كل مثال له ثلاث طرق تعرض الوعد الذي يسمح بإجراء إضافي عندما يوافق الوعد:
.then()
: يعالج كل من الطلبات التي تم حلّها ورفضها. لذلك، يتطلب الأمر عمليتي معاودة الاتصال كمعلمة: واحدة لحالة النجاح والأخرى لحالة الفشل..catch()
: يتم التعامل مع الطلبات المرفوضة فقط. تأخذ معاودة اتصال واحدة كمعلمة..finally()
- توفِّر طريقة لتشغيل الرمز البرمجي سواء تم حلّ الوعد أو رفضه. يلزم استدعاء واحد كمعلمة يتم استدعاؤها بدون وسيطة.
يشير ذلك المصطلح إلى متغيّر يعرض وعدًا يساوي القيمة التي تم حلّها، أو القيمة false
إذا تم رفض الوعد.
مثال
promise.then((resolvedValue) => {
// Handles when promise resolves.
}, (rejectedValue) => {
// Handles when promise rejects.
});
promise.catch((rejectedValue) => {
// Handles when promise rejects.
});
promise.finally(() => {
// Runs regardless of whether or not the previous promise resolves or
// rejects.
});
Promise.all
تعرض وعدًا بأنّ أيًا مما يلي:
- يتم حلها عند حل جميع المدخلات، أو
- يتم رفضها عند رفض أي من المدخلات
البنية
Promise.all(inputs);
المَعلمات
المَعلمة | النوع | الوصف |
---|---|---|
inputs |
مصفوفة | يشير ذلك المصطلح إلى مصفوفة من القيم أو الوعود. إذا لم يكن الإدخال عبارة عن وعود، يتم تمرير الإدخال كما لو كان قيمة الوعد التي تم حلّها. تعرض هذه الدالة خطأ إذا لم يكن الإدخال مصفوفة. |
مثال
const Promise = require('Promise');
const sendHttpGet = require('sendHttpGet');
return Promise.all(['a', sendHttpGet('https://example.com')])
.then((results) => {
// results will equal: ['a', {statusCode: 200, headers: {}, body: ''}]
});
الأذونات المرتبطة
بلا عُري
Promise.create
تنشئ وعدًا يكافئ عمليًا بوعد JavaScript.
البنية
Promise.create(resolver);
المَعلمات
المَعلمة | النوع | الوصف |
---|---|---|
resolver |
الوظيفة | دالة يتم استدعاؤها بدالتَين -- الحل والرفض. سيتم التعامل مع الوعد الذي يتم عرضه مرة أخرى أو رفضه عند استدعاء المَعلمة المناظِرة. تعرض رسالة خطأ إذا لم يكن برنامج التعيين وظيفة. |
مثال
const Promise = require('Promise');
return Promise.create((resolve, reject) => {
// Do asynchronous work that eventually calls resolve() or reject()
});
الأذونات المرتبطة
بلا عُري
اختبار واجهات برمجة التطبيقات
تعمل واجهات برمجة التطبيقات هذه مع اختبارات JavaScript في وضع الحماية لإنشاء اختبارات للنماذج المخصّصة في أداة "إدارة العلامات من Google". لا تحتاج واجهات برمجة التطبيقات الاختبارية هذه إلى عبارة require()
. [مزيد من المعلومات عن اختبارات النماذج المخصّصة]
assertApi
تعرض كائن مطابقة يمكن استخدامه لتقديم تأكيدات بطلاقة حول واجهة برمجة التطبيقات المذكورة.
البنية
assertApi(apiName)
المَعلمات
المَعلمة | النوع | الوصف |
---|---|---|
apiName |
سلسلة | اسم واجهة برمجة التطبيقات المطلوب التحقّق منها، والسلسلة نفسها التي تم تمريرها إلى require()
|
مطابقون
Subject.wasCalled()
Subject.wasNotCalled()
Subject.wasCalledWith(...expected)
Subject.wasNotCalledWith(...expected)
أمثلة
assertApi('sendPixel').wasCalled();
assertApi('getUrl').wasNotCalled();
assertApi('makeNumber').wasCalledWith('8');
assertApi('setInWindow').wasNotCalledWith('myVar', 'theWrongValue');
assertThat
تم تصميم واجهة برمجة التطبيقات assertThat
استنادًا إلى مكتبة [Truth] في Google. فهي تعرض كائنًا يمكن استخدامه
لتقديم تأكيدات بطلاقة حول قيمة الموضوع. ويؤدي إخفاق التأكيد إلى إيقاف الاختبار على الفور ووضع علامة عليه كفشل. ومع ذلك، فإن الفشل في اختبار واحد لن يؤثر على حالات الاختبار الأخرى.
البنية
assertThat(actual, opt_message)
المَعلمات
المَعلمة | النوع | الوصف |
---|---|---|
actual |
أيّ | القيمة المطلوب استخدامها في عمليات التحقّق بطلاقة. |
opt_message |
سلسلة | رسالة اختيارية يمكنك طباعتها في حال تعذَّر تأكيد. |
مطابقون
مطابق | الوصف |
---|---|
isUndefined() |
التأكيد على أنّ الموضوع هو undefined . |
isDefined() |
التأكيد على أنّ الموضوع ليس undefined . |
isNull() |
التأكيد على أنّ الموضوع هو null . |
isNotNull() |
التأكيد على أنّ الموضوع ليس null . |
isFalse() |
التأكيد على أنّ الموضوع هو false . |
isTrue() |
التأكيد على أنّ الموضوع هو true . |
isFalsy() |
التأكيد على أنّ الموضوع مزورة القيم الزائفة هي
undefined وnull وfalse
وNaN و0 و '' (سلسلة فارغة). |
isTruthy() |
تؤكد على صحة الموضوع. القيم الزائفة هي
undefined وnull وfalse
وNaN و0 و '' (سلسلة فارغة). |
isNaN() |
تؤكد أن الموضوع هو قيمة NaN. |
isNotNaN() |
تؤكد أن الموضوع أي قيمة بخلاف NaN. |
isInfinity() |
تأكيد أن الموضوع إيجابي أو سالب لانهائي. |
isNotInfinity() |
تأكيد أن الموضوع أي قيمة بخلاف اللانهاية الموجبة أو السالبة. |
isEqualTo(expected) |
تأكيد أن الموضوع يساوي القيمة المقدمة. هذه المقارنة بين القيم وليست مقارنة مرجعية. وتتم مقارنة محتوى الكائنات والصفائف بشكل متكرر. |
isNotEqualTo(expected) |
تؤكد أن الموضوع لا يساوي القيمة المقدمة. هذه المقارنة بين القيم وليست مقارنة مرجعية. وتتم مقارنة محتوى الكائنات والصفائف بشكل متكرر. |
isAnyOf(...expected) |
تأكيد أن الموضوع يساوي إحدى القيمة المقدمة. هذه المقارنة بين القيم وليست مقارنة مرجعية. وتتم مقارنة محتوى الكائنات والصفائف بشكل متكرر. |
isNoneOf(...expected) |
التأكيد على أن الموضوع لا يساوي أي من القيم المقدمة. هذه المقارنة بين القيم وليست مقارنة مرجعية. وتتم مقارنة محتوى الكائنات والصفائف بشكل متكرر. |
isStrictlyEqualTo(expected) |
التأكيد على أنّ الموضوع مساوٍ تمامًا (=== ) للقيمة المقدّمة. |
isNotStrictlyEqualTo(expected) |
التأكيد على أن الموضوع لا يساوي تمامًا (!== )
القيمة المقدَّمة. |
isGreaterThan(expected) |
التأكيد على أن الموضوع أكبر من (> ) القيمة المحددة في مقارنة مرتبة. |
isGreaterThanOrEqualTo(expected) |
التأكيد على أن الموضوع أكبر من أو يساوي
(>= ) القيمة المحددة في مقارنة مرتبة. |
isLessThan(expected) |
التأكيد على أن الموضوع أقل من (< ) القيمة المقدمة في مقارنة مرتبة. |
isLessThanOrEqualTo(expected) |
التأكيد على أنّ الموضوع أقل من أو يساوي (<= )
القيمة المحدّدة في مقارنة مرتّبة |
contains(...expected) |
تأكيد أن الموضوع هو مصفوفة أو سلسلة تحتوي على جميع القيم المقدمة بأي ترتيب. هذه المقارنة بين القيم وليست مقارنة مرجعية. وتتم مقارنة محتوى العناصر والصفائف بشكل متكرر. |
doesNotContain(...expected) |
تؤكد أن الموضوع هو مصفوفة أو سلسلة لا تحتوي على أي من القيم المقدمة. هذه مقارنة بين القيم وليست مقارنة مرجعية. تتم مقارنة محتويات الكائنات والصفائف بشكل متكرر. |
containsExactly(...expected) |
التأكيد على أن الموضوع هو مصفوفة تحتوي على جميع القيم المحددة بأي ترتيب ولا تحتوي على قيم أخرى. هذه المقارنة بين القيم وليست مقارنة مرجعية. وتتم مقارنة محتوى العناصر والصفائف بشكل متكرر. |
doesNotContainExactly(...expected) |
التأكيد على أن الموضوع هو مصفوفة تحتوي على مجموعة مختلفة من القيم من القيم المحددة بأي ترتيب. وهذه المقارنة بين القيم وليست مقارنة مرجعية. وتتم مقارنة محتوى العناصر والصفائف بشكل متكرر. |
hasLength(expected) |
تؤكد أن الموضوع عبارة عن مصفوفة أو سلسلة ذات طول معين. يتعذّر التأكيد دائمًا إذا لم تكن القيمة صفيفًا أو سلسلة. |
isEmpty() |
التأكيد على أن الموضوع هو مصفوفة أو سلسلة فارغة (الطول = 0). يتعذّر التأكيد دائمًا إذا لم تكن القيمة صفيفًا أو سلسلة. |
isNotEmpty() |
تؤكد أن الموضوع هو مصفوفة أو سلسلة غير فارغة (الطول > 0). يتعذّر التأكيد دائمًا إذا لم تكن القيمة صفيفًا أو سلسلة. |
isArray() |
تؤكد أن نوع الموضوع هو صفيف. |
isBoolean() |
تؤكد أن نوع الموضوع منطقي. |
isFunction() |
تؤكد على أن نوع الموضوع هو دالة. |
isNumber() |
تأكيد أن نوع الموضوع هو رقم. |
isObject() |
تأكيد أن نوع الموضوع هو كائن. |
isString() |
تؤكد أن نوع الموضوع هو سلسلة. |
أمثلة
assertThat(undefined).isUndefined();
assertThat(id, 'ID must be defined').isDefined();
assertThat(null).isNull();
assertThat(undefined).isNotNull();
assertThat(true).isTrue();
assertThat(false).isFalse();
assertThat(1).isTruthy();
assertThat('').isFalsy();
assertThat(1/0).isInfinity();
assertThat(0).isNotInfinity();
assertThat(-'foo').isNaN();
assertThat(100).isNotNaN();
assertThat(sentUrl).isEqualTo('https://endpoint.example.com/?account=12345');
assertThat(category).isNotEqualTo('premium');
assertThat(5).isAnyOf(1, 2, 3, 4, 5);
assertThat(42).isNoneOf('the question', undefined, 41.9);
assertThat('value').isStrictlyEqualTo('value');
assertThat('4').isNotStrictlyEqualTo(4);
assertThat(['a', 'b', 'c']).contains('a', 'c');
assertThat(['x', 'y', 'z']).doesNotContain('f');
assertThat(['1', '2', '3']).containsExactly('3', '2', '1');
assertThat(['4', '5']).doesNotContainExactly('4');
assertThat('a string').hasLength(8);
assertThat([]).isEmpty();
assertThat('another string').isNotEmpty();
fail
تعذّر الاختبار الحالي على الفور وتُطبع الرسالة المحددة، إذا تم توفيرها.
البنية
fail(opt_message);
المَعلمات
المَعلمة | النوع | الوصف |
---|---|---|
opt_message |
سلسلة | نص اختياري لرسالة خطأ. |
مثال
fail('This test has failed.');
mock
تسمح لك واجهة برمجة التطبيقات mock
بتجاهل سلوك واجهات برمجة التطبيقات التي تم وضع الحماية لها. تعتبر واجهة برمجة التطبيقات الوهمية آمنة للاستخدام في التعليمات البرمجية للقالب، ولكنها لا تعمل عندما لا تكون في وضع الاختبار. وتتم إعادة ضبط النماذج قبل إجراء كل اختبار.
البنية
mock(apiName, returnValue);
المَعلمات
المَعلمة | النوع | الوصف |
---|---|---|
apiName |
سلسلة | اسم واجهة برمجة التطبيقات المطلوب اختبارها، والسلسلة نفسها التي تم تمريرها إلى require() |
returnValue |
أيّ | القيمة التي يتم عرضها لواجهة برمجة التطبيقات أو دالة يتم استدعاءها بدلاً من واجهة برمجة التطبيقات. إذا كانت returnValue دالة، يتم استدعاء هذه الدالة بدلاً من Sandboxed API. أما إذا كانت returnValue غير دالة، فسيتم عرض هذه القيمة بدلاً من Sandbox API. |
أمثلة
mock('encodeUri', "https://endpoint.example.com/?account=12345");
mock('sendPixel', function(url, onSuccess, onFailure) {
onSuccess();
});
runCode
تنفيذ رمز النموذج، أي محتوى علامة التبويب الرمز، في بيئة الاختبار الحالية باستخدام عنصر بيانات إدخال معيّن.
البنية
runCode(data)
المَعلمات
المَعلمة | النوع | الوصف |
---|---|---|
data |
كائن | كائن البيانات المراد استخدامه في الاختبار. |
قيمة الإرجاع
تعرض قيمة متغير للنماذج المتغيرة، وتعرض undefined
لجميع أنواع النماذج الأخرى.
مثال
runCode({field1: 123, field2: 'value'});