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