يوضّح هذا المستند واجهات برمجة التطبيقات لوضع العلامات من جهة الخادم.
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
،
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 |
سلسلة |
يشير هذا المصطلح إلى عنوان URL تم ترميزه من قِبل
encodeUri() أو بأي وسيلة أخرى.
|
الأذونات المرتبطة
بلا عُري
decodeUriComponent
فك ترميز أي أحرف مشفرة في مكوّن معرّف الموارد المنتظم (URI) المقدَّم. تؤدي إلى إرجاع
string التي تمثل مكوّن URI الذي تم فك ترميزه. تعرض undefined
عند
تم تقديم إدخال غير صالح.
مثال
const decodeUriComponent = require('decodeUriComponent');
const decodedQuery = decodeUriComponent(data.query);
if (decodedQuery) {
// ...
}
البنية
decodeUriComponent(encoded_uri_component);
المعلّمات
المعلمة | النوع | الوصف |
---|---|---|
encoded_uri_component |
سلسلة |
يشير هذا المصطلح إلى مكوّن معرّف الموارد المنتظم (URI) الذي تمّ ترميزه بواسطة
encodeUriComponent()
أو بوسائل أخرى.
|
الأذونات المرتبطة
بلا عُري
encodeUri
لعرض مُعرّف موارد منتظم (URI) مُشفَّر من خلال وضع حروف إلغاء خاصة الأحرف. عرض سلسلة تمثل السلسلة المقدّمة المشفّرة كمعرف موارد منتظم (URI).
مثال
const encodeUri = require('encodeUri');
const sendHttpGet = require('sendHttpGet');
sendHttpGet('https://www.example.com/' + encodeUri(pathInput));
البنية
encodeUri(uri);
المعلّمات
المعلمة | النوع | الوصف |
---|---|---|
uri |
سلسلة | معرّف موارد منتظم (URI) كامل. |
الأذونات المرتبطة
بلا عُري
encodeUriComponent
لعرض مُعرّف موارد منتظم (URI) مُشفَّر من خلال وضع حروف إلغاء خاصة الأحرف. عرض سلسلة تمثل السلسلة المقدّمة المشفرة معرف موارد منتظم (URI).
مثال
const encodeUriComponent = require('encodeUriComponent');
const sendHttpGet = require('sendHttpGet');
sendHttpGet('https://www.example.com/?' + encodeUriComponent(queryInput));
البنية
encodeUriComponent(str);
المعلّمات
المعلمة | النوع | الوصف |
---|---|---|
str |
سلسلة | مكون من مكونات معرف الموارد المنتظم (URI). |
الأذونات المرتبطة
بلا عُري
extractEventsFromMpv1
ترجمة طلب Measurement Protocol V1 الوارد إلى قائمة بالأحداث في تنسيق المخطط الموحّد. تعرض قائمة الأحداث المستخرجة. تعرض رسالة خطأ إذا تنسيق الطلب ليس صحيحًا.
مثال
const extractEventsFromMpv1 = require('extractEventsFromMpv1');
const isRequestMpv1 = require('isRequestMpv1');
if (isRequestMpv1()) {
const events = extractEventsFromMpv1();
for (let i = 0; i < events.length; ++i) {
const event = events[i];
// Process event.
}
}
البنية
extractEventsFromMpv1();
الأذونات المرتبطة
يجب الحصول على إذن read_request
. يجب ضبط الإذن من أجل
إلى ما لا يقل عن:
body
query parameters
extractEventsFromMpv2
ترجمة طلب Measurement Protocol V2 الوارد إلى قائمة بالأحداث في تنسيق المخطط الموحّد. تعرض قائمة الأحداث المستخرجة. تعرض رسالة خطأ إذا تنسيق الطلب ليس صحيحًا.
مثال
const extractEventsFromMpv2 = require('extractEventsFromMpv2');
const isRequestMpv2 = require('isRequestMpv2');
if (isRequestMpv2()) {
const events = extractEventsFromMpv2();
for (let i = 0; i < events.length; ++i) {
const event = events[i];
// Process event.
}
}
البنية
extractEventsFromMpv2();
الأذونات المرتبطة
يجب الحصول على إذن read_request
. يجب ضبط الإذن من أجل
إلى ما لا يقل عن:
body
query parameters
fromBase64
فك ترميز سلسلة base64 المرمّزة. تعرض undefined
إذا كان الإدخال غير صالح.
البنية
fromBase64(base64EncodedString);
المعلّمات
المعلمة | النوع | الوصف |
---|---|---|
base64EncodedString |
سلسلة | سلسلة Base64 مرمّزة. |
مثال
const fromBase64 = require('fromBase64');
const greeting = fromBase64('aGVsbG8=');
if (greeting === 'hello') {
// ...
}
الأذونات المرتبطة
بلا عُري
generateRandom
تعرض رقمًا عشوائيًا (عدد صحيح) ضمن النطاق المحدّد.
مثال
const generateRandom = require('generateRandom');
const randomValue = generateRandom(0, 10000000);
البنية
generateRandom(min, max);
المعلّمات
المعلمة | النوع | الوصف |
---|---|---|
min |
الرقم | الحد الأدنى للقيمة المحتملة للعدد الصحيح المعروض (شامل). |
max |
الرقم | الحد الأقصى للقيمة المحتملة للعدد الصحيح الذي تم إرجاعه (شامل). |
الأذونات المرتبطة
بلا عُري
getAllEventData
تعرض نسخة من بيانات الحدث.
البنية
getAllEventData();
الأذونات المرتبطة
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 |
منطقية |
إذا كانت 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
|
مصفوفة | مصفوفة من نطاقات واجهة برمجة تطبيقات Google 2.0 OAuth طلب الوصول إليه. |
الأذونات المرتبطة
يجب الحصول على إذن use_google_credentials
. يجب أن يكون الإذن
باستخدام نطاق واحد أو أكثر مسموح به.
getGoogleScript
لاسترداد مورد من مجموعة محددة مسبقًا من النصوص البرمجية من Google، وعرض التعهد بالنص البرمجي والبيانات الوصفية للتخزين المؤقت المرتبطة به
سينتهي الوعد بعنصر يحتوي على مفتاحَين: script
metadata
وفي حال عدم نجاح الطلب، سيتم رفض الوعد باستخدام مفتاح reason
.
سيحتوي عنصر metadata
على البيانات الوصفية التالية للتخزين المؤقت استنادًا إلى
عناوين استجابة الموارد سيكون كل حقل موجودًا فقط إذا كان
موجودة في استجابة المورد.
{
'cache-control': string,
'expires': string,
'last-modified': string,
}
مثال
const getGoogleScript = require('getGoogleScript');
getGoogleScript('ANALYTICS').then((result) => {
// Operate on result.script and result.metadata here.
});
البنية
getGoogleScript(script[, options]);
المعلّمات
المعلمة | النوع | الوصف |
---|---|---|
script |
سلسلة |
تمثّل هذه السمة اسم النص البرمجي. النصوص البرمجية المتوافقة هي
'ANALYTICS' و'GTAG' و
'GTM' 'ANALYTICS'
يجلب النص البرمجي لـ Google Analytics من
https://www.google-analytics.com/analytics.js يسترجع الخيار 'GTAG' علامة الموقع الشاملة (gtag.js)
النص البرمجي من https://www.googletagmanager.com/gtag/js .يسترجع الخيار 'GTM' أداة "إدارة العلامات من Google".
النص البرمجي من https://www.googletagmanager.com/gtm.js .
|
options |
كائن | خيارات الطلب الاختيارية. انظر أدناه للاطّلاع على الخيارات المتوافقة. |
الخيارات
Option | النوع | الوصف |
---|---|---|
id |
سلسلة |
تنطبق على 'GTAG' باستخدام رقم تعريف قياس علامة الموقع الشاملة (gtag)
'GTM' مع رقم تعريف حاوية الويب (على سبيل المثال، GTM-XXXX).
|
debug |
أيّ | إذا كانت الحقيقة، تطلب نسخة تصحيح الأخطاء من القياس وتعرضها. البرنامج النصي. |
timeout |
الرقم |
مهلة الطلب بالمللي ثانية؛ ويتم تجاهل القيم غير الموجبة. في حال حذف
انتهاء مهلة الطلب، فسيتم استدعاء الاتصال
undefined لقيمة النص البرمجي و{}
البيانات الوصفية.
|
ويتم تجاهل مفاتيح الخيارات غير المعروفة.
الأذونات المرتبطة
يجب الحصول على إذن send_http
. يجب ضبط الإذن للسماح
الوصول إلى ما لا يقل عن:
- السماح بنطاقات Google Domains
getRemoteAddress
عرض تمثيل string لعنوان IP الذي يتضمّن الطلب
قد تم إنشاؤها، على سبيل المثال 12.345.67.890
لبروتوكول IPv4 أو 2001:0db8:85a3:0:0:8a2e:0370:7334
لـ IPv6، من خلال قراءة عناوين الطلبات مثل Redirected وX-forwarded-For.
ملاحظة: تعمل واجهة برمجة التطبيقات هذه بأقصى جهد لاكتشاف عنوان IP الأصلي، ولكن
فإنه لا يمكنه ضمان دقة النتيجة.
البنية
getRemoteAddress();
الأذونات المرتبطة
يجب الحصول على إذن read_request
. يجب ضبط الإذن من أجل
إلى ما لا يقل عن:
- العنوانان
Forwarded
وX-Forwarded-For
- عنوان IP البعيد
getRequestBody
عرض نص الطلب كـ string، في حال توفّره، أو undefined
غير ذلك.
البنية
getRequestBody();
الأذونات المرتبطة
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' |
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
تستند "إحصاءات Google" أو "إحصاءات Google 4" إلى رقم تعريف القياس في الحدث.
البيانات.
يتم ضبط الحقل location
على عنوان location
، إذا كان متوفّرًا.
مثال
const logToConsole = require('logToConsole');
const sendEventToGoogleAnalytics = require('sendEventToGoogleAnalytics');
const setResponseHeader = require('setResponseHeader');
const setResponseStatus = require('setResponseStatus');
// Sends an event to Google Analytics and returns failure if the request did not
// succeed. Additionally, if the request resulted in a redirect request, the
// code nominates a redirect response to be returned.
sendEventToGoogleAnalytics(event).then((response) => {
if (response.location) {
setResponseHeader('location', response.location);
setResponseStatus(302);
} else {
setResponseStatus(200);
}
data.gtmOnSuccess();
}).catch((error) => {
logToConsole(error.reason);
setResponseStatus(500);
data.gtmOnFailure();
});
البنية
sendEventToGoogleAnalytics(event);
المعلّمات
المعلمة | النوع | الوصف |
---|---|---|
event |
كائن | الحدث بتنسيق المخطط الموحّد. |
الأذونات المرتبطة
يجب الحصول على إذن send_http
. يجب ضبط الإذن للسماح
الوصول إلى ما لا يقل عن:
- السماح بنطاقات Google Domains
sendHttpGet
لتقديم طلب HTTP GET إلى عنوان URL المحدد وعرض وعد يتم حله مع النتيجة بعد اكتمال الطلب أو المهلة.
النتيجة التي تم حلها هي كائن يحتوي على ثلاثة مفاتيح: statusCode
وheaders
وbody
. في حال فشل الطلب (مثلاً، عنوان URL غير صالح أو لا يوجد مسار إلى المضيف)
تعذَّر تفاوض طبقة المقابس الآمنة وما إلى ذلك)، سيتم رفض الوعد مع: {reason:
'failed'}
. إذا تم ضبط الخيار timeout
وانتهت مهلة الطلب،
سيتم رفض الوعد باستخدام: {reason: 'timed_out'}
مثال
const sendHttpGet = require('sendHttpGet');
// Returns the response body as the value for a variable.
return sendHttpGet('https://example.com/item/' + data.itemId, {
headers: {key: 'value'},
timeout: 500,
}).then((result) => result.body, () => undefined);
البنية
sendHttpGet(url[, options]);
المعلّمات
المعلمة | النوع | الوصف |
---|---|---|
url |
سلسلة | عنوان URL المطلوب |
options
|
كائن | خيارات الطلب اختيارية (راجع الخيارات أدناه). |
الخيارات
Option | النوع | الوصف |
---|---|---|
headers |
سلسلة | عناوين إضافية للطلبات |
timeout
|
الرقم | تنتهي المهلة بالملي ثانية التي تسبق
يتم إلغاء الطلب. وتكون القيمة التلقائية هي 15000 . |
authorization
|
كائن | كائن تفويض اختياري من
الاتصال برقم getGoogleAuth لتضمين
عناوين التفويض عند إجراء الطلبات
إلى googleapis.com . |
الأذونات المرتبطة
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- العمر، المسار، آمن، وsameSite. (راجع الخيارات، أدناه). |
noEncode |
منطقية |
في حال اختيار القيمة "true"، لن يتم ترميز قيمة ملف تعريف الارتباط. الإعدادات التلقائية على
false
|
النطاق: المضيف الذي سيتم إرسال ملف تعريف الارتباط إليه. في حال الضبط على الميزات الخاصة القيمة 'auto'، فسيتم حساب المضيف تلقائيًا باستخدام الاستراتيجية التالية:
- eTLD+1 لعنوان
Forwarded
، في حال توفّره - eTLD+1 لعنوان
X-Forwarded-Host
، في حال توفّره - eTLD+1 من عنوان
Host
.
- eTLD+1 لعنوان
expires: الحد الأقصى لمدة صلاحية ملف تعريف الارتباط. يجب أن يكون هذا بتنسيق UTC سلسلة التاريخ، مثل "السبت، 26 تشرين الأول (أكتوبر) 1985 08:21:00 بتوقيت غرينيتش". إذا كان كل من
expires
و تم ضبطmax-age
، والأولوية لـmax-age
.httpOnly: يمنع JavaScript من الوصول إلى ملف تعريف الارتباط في حالة
true
.max-age: عدد الثواني المتبقية قبل انتهاء صلاحية ملفّ تعريف الارتباط. صفر أو سالب انتهاء صلاحية ملف تعريف الارتباط على الفور. إذا كانت كل من
expires
وmax-age
يتم تعيينها، تكون الأولوية لـmax-age
.path: مسار يجب أن يكون موجودًا في عنوان URL المطلوب، وإلّا فلن إرسال عنوان ملف تعريف الارتباط.
آمن: في حال ضبط هذه السياسة على
true
، لا يتم إرسال ملف تعريف الارتباط إلى الخادم إلا عندما يتم تقديم طلب من نقطة نهايةhttps:
.sameSite: تؤكِّد عدم إرسال ملف تعريف الارتباط من خلال مصادر متعددة الطلبات. يجب أن تكون القيم
'strict'
أو'lax'
أو'none'
.
الأذونات المرتبطة
setPixelResponse
لضبط نص الاستجابة على ملف GIF 1×1، وضبط العنوان Content-Type على "image/gif" تضبط عناوين التخزين المؤقت بحيث لا يخزّن وكلاء المستخدم الاستجابة في ذاكرة التخزين المؤقت، وتضبط حالة الاستجابة إلى 200.
تجدر الإشارة إلى أنّه يجب استدعاء الدالة returnResponse لتلقّي الردّ على إعادة إرساله إلى العميل.
البنية
setPixelResponse();
الأذونات المرتبطة
يجب الحصول على إذن access_response
. يجب ضبط الإذن من أجل
إلى ما لا يقل عن:
headers
- يجب السماح باستخدام المفاتيح التاليةcontent-type
cache-control
expires
pragma
body
status
setResponseBody
لضبط نص الاستجابة على الوسيطة.
تجدر الإشارة إلى أنّه يجب استدعاء الدالة returnResponse لتلقّي الردّ على إعادة إرساله إلى العميل.
البنية
setResponseBody(body[, encoding]);
المعلّمات
المعلمة | النوع | الوصف |
---|---|---|
body |
سلسلة | القيمة المطلوب ضبطها كنص للاستجابة. |
encoding |
سلسلة |
ترميز الأحرف لنص الاستجابة (القيمة التلقائية
'utf8' ). وتشمل القيم المسموح بها 'ascii' ،
'utf8' ، 'utf16le' ، 'ucs2' ،
'base64' ، 'latin1' ، 'binary' ،
و'hex' .
|
الأذونات المرتبطة
يجب الحصول على إذن access_response
. يجب ضبط الإذن من أجل
إلى ما لا يقل عن:
body
setResponseHeader
لضبط عنوان في الرد الذي سيتم عرضه. إذا كان العنوان بهذا الاسم (غير حساس لحالة الأحرف) تم تعيينه مسبقًا بواسطة واجهة برمجة التطبيقات هذه، فإن الطلب الأخير استبدال أو محو القيمة التي حددها المتصل السابق.
تجدر الإشارة إلى أنّه يجب استدعاء الدالة returnResponse لتلقّي الردّ على إعادة إرساله إلى العميل.
البنية
setResponseHeader(name, value);
المعلّمات
المعلمة | النوع | الوصف |
---|---|---|
name |
سلسلة | اسم العنوان. أسماء عناوين HTTP غير حساسة لحالة الأحرف، ولذلك فإن العنوان سيُكتب بحروف صغيرة. |
value |
string unspecific | قيمة العنوان. إذا كانت القيمة خالية أو غير محددة، فسيتم محو العنوان المسمى من الرد الذي سيتم إرجاعه. |
الأذونات المرتبطة
يجب الحصول على إذن access_response
. يجب ضبط الإذن من أجل
إلى ما لا يقل عن:
headers
setResponseStatus
لتعيين رمز حالة HTTP للاستجابة التي سيتم عرضها.
تجدر الإشارة إلى أنّه يجب استدعاء الدالة returnResponse لتلقّي الردّ على إعادة إرساله إلى العميل.
البنية
setResponseStatus(statusCode);
المعلّمات
المعلمة | النوع | الوصف |
---|---|---|
statusCode |
الرقم | رمز حالة HTTP الذي سيتم عرضه. |
الأذونات المرتبطة
يجب الحصول على إذن access_response
. يجب ضبط الإذن من أجل
إلى ما لا يقل عن:
status
sha256
لحساب ملخص SHA-256 للإدخال واستدعاء استدعاء مع
بترميز base64، إلا إذا كان الكائن options
يحدد
ترميز الإخراج.
يتطابق سلوك وتوقيع واجهة برمجة التطبيقات هذا مع واجهة برمجة تطبيقات sha256
لحاويات الويب.
ومع ذلك، فإن النماذج المخصصة في حاويات الخادم يجب أن تستخدم السمة
sha256Sync
واجهة برمجة التطبيقات لرموز أبسط.
مثال
const encodeUriComponent = require('encodeUriComponent');
const sendHttpGet = require('sendHttpGet');
const sha256 = require('sha256');
sha256('inputString', (digest) => {
sendHttpGet('https://example.com/collect?id=' + encodeUriComponent(digest));
});
sha256('inputString', (digest) => {
sendHttpGet('https://example.com/collect?id=' + encodeUriComponent(digest));
}, {outputEncoding: 'hex'});
البنية
sha256(input, onSuccess, options = undefined);
المعلّمات
المعلمة | النوع | الوصف |
---|---|---|
input |
سلسلة | السلسلة المطلوب تجزئتها. |
onSuccess |
الوظيفة |
ويتم استدعاءه مع الملخص الناتج، بترميز base64، ما لم
يحدد الكائن options ترميز إخراج مختلفًا.
|
options |
كائن |
اختياري للخيارات لتحديد ترميز الإخراج. في حال حذف
محدد، يجب أن يحتوي الكائن على المفتاح outputEncoding
بالقيمة واحدة من base64 أو hex .
|
الأذونات المرتبطة
بلا عُري
sha256Sync
لحساب وعرض ملخص SHA-256 للمدخل، بترميز base64،
ما لم يحدّد الكائن options
ترميز إخراج مختلفًا.
مثال
const encodeUriComponent = require('encodeUriComponent');
const sendHttpGet = require('sendHttpGet');
const sha256Sync = require('sha256Sync');
const digestBase64 = sha256Sync('inputString');
const digestHex = sha256Sync('inputString', {outputEncoding: 'hex'});
sendHttpGet('https://example.com/collect?id=' + encodeUriComponent(digestBase64));
sendHttpGet('https://example.com/collect?id=' + encodeUriComponent(digestHex));
البنية
sha256Sync(input, options = undefined);
المعلّمات
المعلمة | النوع | الوصف |
---|---|---|
input |
سلسلة | السلسلة المطلوب تجزئتها. |
options |
كائن |
اختياري للخيارات لتحديد ترميز الإخراج. في حال حذف
محدد، يجب أن يحتوي الكائن على المفتاح outputEncoding
بالقيمة واحدة من base64 أو hex .
|
الأذونات المرتبطة
بلا عُري
templateDataStorage
تعرض كائنًا بالطرق للوصول إلى تخزين بيانات النموذج. نموذج يتيح تخزين البيانات مشاركة البيانات عبر عمليات التنفيذ لنموذج واحد. تستمر البيانات المخزنة في تخزين بيانات النموذج على الخادم الذي يشغل . في معظم الحالات، هناك خوادم متعددة تشغل الحاوية، لذلك تخزين البيانات في تخزين بيانات القالب لا يضمن أن كل طلب الوصول إلى البيانات.
"البيانات" في الاسم "templateDataStorage" إلى حقيقة أن البديهي
أنواع البيانات غير الوظيفية باستخدام واجهة برمجة التطبيقات هذه. تُعد أي دوال أو
سيتم تخزين مراجع الدوال التي تم تمريرها إلى واجهة برمجة التطبيقات كـ null
بدلاً من ذلك.
البنية
const templateDataStorage = require('templateDataStorage');
// Returns a copy of the value stored for the given key, or null if nothing
// is stored with that key.
templateDataStorage.getItemCopy(key);
// Stores a copy of the value for the given key (or removes the data stored
// for the given key if the input value is null).
templateDataStorage.setItemCopy(key, value);
// Removes the value stored for the given key, if present.
templateDataStorage.removeItem(key);
// Deletes all values stored for the current template.
templateDataStorage.clear();
مثال
const sendHttpGet = require('sendHttpGet');
const setResponseBody = require('setResponseBody');
const setResponseStatus = require('setResponseStatus');
const templateDataStorage = require('templateDataStorage');
// Check to see if the item is in the cache.
const cachedBody = templateDataStorage.getItemCopy(data.key);
if (cachedBody) {
setResponseBody(cachedBody);
data.gtmOnSuccess();
return;
}
sendHttpGet(data.url).then((result) => {
if (result.statusCode >= 200 && result.statusCode < 300) {
setResponseBody(result.body);
templateDataStorage.setItemCopy(data.key, result.body);
data.gtmOnSuccess();
} else {
data.gtmOnFailure();
}
setResponseStatus(result.statusCode);
});
الأذونات المرتبطة
testRegex
لاختبار سلسلة مقابل تعبير عادي تم إنشاؤه من خلال createRegex
API إرجاع true
في حال تطابُق التعبير العادي. تعرض false
في الحالات الأخرى.
التعبير العادي الذي يتم إنشاؤه باستخدام العلامة العامة يكون له حالة خاصة. يمكنك الاطّلاع على مستندات RegExp للاطّلاع على التفاصيل
مثال
const createRegex = require('createRegex');
const testRegex = require('testRegex');
const domainRegex = createRegex('\\w+\\.com', 'i');
// createRegex returns null if the regex is invalid or Re2 is not available.
if (domainRegex === null) return;
// Returns true
testRegex(domainRegex, 'example.com/foobar');
البنية
testRegex(regex, string);
المعلّمات
المعلمة | النوع | الوصف |
---|---|---|
regex |
كائن | التعبير العادي المطلوب اختباره، ويتم عرضه من واجهة برمجة تطبيقات createRegex. |
string |
سلسلة | سلسلة تجريبية لاختبارها. |
الأذونات المرتبطة
بلا عُري
toBase64
لترميز سلسلة كـ base64 أو base64url. يتم ضبط القيمة التلقائية على ترميز base64.
البنية
toBase64(input, options);
المعلّمات
المعلمة | النوع | الوصف |
---|---|---|
input |
سلسلة | سلسلة لترميزها. |
options
|
كائن | ضبط واجهة برمجة التطبيقات اختيارية (راجع الخيارات أدناه). |
الخيارات
Option | النوع | الوصف | الحد الأدنى للإصدار |
---|---|---|---|
urlEncoding
|
منطقية | إذا كانت true، فإن النتيجة ستظهر
أن يتم ترميزه باستخدام
تنسيق base64url |
1.0.0 |
مثال
const toBase64 = require('toBase64');
const base64Hello = toBase64('hello');
const base64UrlHello = toBase64('hello', {urlEncoding: true});
الأذونات المرتبطة
بلا عُري
BigQuery
تعرض كائنًا يوفّر دوال BigQuery.
تسمح الدالة BigQuery.insert
بكتابة البيانات في جدول BigQuery. أُنشأها جون هنتر، الذي كان متخصصًا
يعرض وعدًا يتم حله عند إدراجه بنجاح أو
يتم رفضها عند حدوث خطأ.
عند نجاح الإدراج، يتمّ إنهاء الوعد بدون أي وسيطات.
عند تعذُّر الإدراج، يتم رفض الوعد مع عرض قائمة بالعناصر التي تحتوي على سبب الخطأ وربما كائن صف في حالة حدوث خطأ. من الممكن أن إتمام جزء من الطلب بنجاح، في حين أن الأجزاء الأخرى ليست كذلك. تم رفض الوعد في هذه الحالة مع عرض قائمة بالأخطاء لكل صف يحتوي على لكائن صف للمساعدة في تمييز الصفوف التي تم إدراجها (اطّلِع على أمثلة الأخطاء أدناه). عرض وثائق BigQuery على خطأ الرسائل للحصول على مزيد من المعلومات.
البنية
BigQuery.insert(connectionInfo, rows[, options]);
المعلمة | النوع | الوصف |
---|---|---|
connectionInfo |
كائن |
تحدد المعلومات المطلوبة للربط بجدول BigQuery. تتوفر
معلمة اختيارية واحدة ومعلمتين مطلوبتين:
|
rows |
مصفوفة | الصفوف المراد إدراجها في الجدول. |
options |
كائن | خيارات الطلب الاختيارية. إليك الخيارات المتاحة: ignoreUnknownValues و skipInvalidRows. يتم تجاهل مفاتيح الخيارات غير المعروفة. (راجع الخيارات، أدناه). |
المعلمة | النوع | الوصف |
---|---|---|
ignoreUnknownValues |
منطقية | في حال ضبط هذه السياسة على true ، يمكنك قبول الصفوف التي تحتوي على قيم.
التي لا تتطابق مع المخطط. ويتم تجاهل القيم غير المعروفة. الإعدادات التلقائية
إلى false . |
skipInvalidRows |
منطقية | في حال ضبطها على true ، أدرِج جميع الصفوف الصالحة للطلب.
حتى في حالة وجود صفوف غير صالحة. وتكون القيمة التلقائية هي false . |
يعني الخطأ "لم يتم العثور على الوحدة" أن حاوية الخادم تقوم على الأرجح بتشغيل النسخة القديمة من صورتنا والتي لم تتضمن وحدة BigQuery حتى الآن. يُرجى إعادة نشر حاوية الخادم باستخدام الإعدادات نفسها باستخدام النص البرمجي للنشر. سيتم تضمين الوحدة تلقائيًا بعد انتهاء العملية.
يتضمن الخطأ الذي لا يستند إلى الإدراج عادةً كائن خطأ واحدًا يحتوي على مفتاح reason
:
[{reason: 'invalid'}]
يمكن أن يحتوي خطأ إدراج على عناصر خطأ متعددة باستخدام مصفوفة errors
.
وكائن row
. فيما يلي مثال على استجابة خطأ من
إدراج صفين حيث يحتوي صف واحد فقط على خطأ:
[
{
"errors": [
{
"reason":"invalid"
}
],
"row": {
"string_col":"otherString",
"number_col":-3,
"bool_col":3
}
},
{
"errors": [
{
"reason":"stopped"
}
],
"row": {
"string_col":"stringValue",
"number_col":5,
"bool_col:false
}
}
]
مثال
const BigQuery = require('BigQuery');
const connectionInfo = {
'projectId': 'gcp-cloud-project-id',
'datasetId': 'destination-dataset',
'tableId': 'destination-table',
};
const rows = [{
'column1': 'String1',
'column2': 1234,
}];
const options = {
'ignoreUnknownValues': true,
'skipInvalidRows': false,
};
BigQuery.insert(connectionInfo, rows, options)
.then(data.gtmOnSuccess, data.gtmOnFailure);
الأذونات المرتبطة
Firestore
لعرض كائن يوفر دوال Firestore.
تتوافق واجهة برمجة التطبيقات هذه مع Firestore في الوضع الأصلي فقط، وليست في Firestore في وضع تخزين البيانات. بالإضافة إلى ذلك، لا تتيح واجهة برمجة التطبيقات إلا استخدام قاعدة البيانات التلقائية.
Firestore.read
تقرأ الدالة Firestore.read
البيانات من مستند Firestore
تؤدي إلى إرجاع وعد يتم ربطه بكائن يحتوي على مفتاحين:
"id
" و"data
" في حال عدم توفّر المستند، يتم رفض الوعد مع
يحتوي على مفتاح reason
يساوي not_found
.
البنية
Firestore.read(path[, options]);
المعلمة | النوع | الوصف |
---|---|---|
path |
سلسلة | المسار إلى المستند أو المجموعة. يجب ألا تبدأ أو تنتهي بـ "/". |
options |
كائن | خيارات الطلب اختيارية إليك الخيارات المتاحة: projectId وdisablecache و معاملة. فئة غير معروفة تجاهل مفاتيح الخيارات. (راجع الخيارات، أدناه). |
المعلمة | النوع | الوصف |
---|---|---|
projectId |
سلسلة | Optional. رقم تعريف مشروع Google Cloud Platform في حال حذفها،
تم استرداد projectId من متغيّر البيئة.
وGOOGLE_CLOUD_PROJECT طالما أن
access_firestore
تم ضبط إعداد الإذن لرقم تعريف المشروع على * أو
GOOGLE_CLOUD_PROJECT إذا كانت حاوية الخادم قيد التشغيل على
Google Cloud، سبق أن تم ضبط GOOGLE_CLOUD_PROJECT على
معرّف مشروع Google Cloud. |
disableCache |
منطقية | Optional. تحدِّد هذه السياسة ما إذا كان سيتم إيقاف ذاكرة التخزين المؤقت. يتم تمكين التخزين المؤقت افتراضيًا، والذي سيقوم بتخزين نتائج مدة الطلب. |
transaction |
سلسلة | Optional. القيمة المستردة من Firestore.runTransaction(). وضع علامة على العملية المطلوب استخدامها داخل معاملة. |
مثال
const Firestore = require('Firestore');
return Firestore.read('collection/document', {
projectId: 'gcp-cloud-project-id',
}).then((result) => result.data.key, () => undefined);
Firestore.write
تكتب الدالة Firestore.write
البيانات إلى مستند Firestore أو
الأولية. إذا كان المسار إلى مجموعة، فسيتم إنشاء مستند باستخدام
معرّف يتم إنشاؤه عشوائيًا. إذا كان المسار يؤدي إلى مستند ولم يكن موجودًا، فإنه
سيتم إنشاؤه. تعرض واجهة برمجة التطبيقات هذه وعدًا تتم ملاءمته لرقم تعريف
إضافة أو تعديل المستند. في حال استخدام خيار المعاملة، ستظل واجهة برمجة التطبيقات
وعدًا، ولكنها لن تحتوي على المعرّف نظرًا لأن عمليات الكتابة مجمّعة.
البنية
Firestore.write(path, input[, options]);
المعلّمات
المعلمة | النوع | الوصف |
---|---|---|
path |
سلسلة | المسار إلى المستند أو المجموعة. يجب ألا تبدأ أو تنتهي بـ "/". |
input |
كائن | القيمة المطلوب كتابتها في المستند. إذا تم تعيين خيار الدمج، ستدمج واجهة برمجة التطبيقات المفاتيح من الإدخال في المستند. |
options |
كائن | خيارات الطلب اختيارية إليك الخيارات المتاحة: projectId وmerge و معاملة. يتم تجاهل مفاتيح الخيارات غير المعروفة. (راجع الخيارات، أدناه). |
المعلمة | النوع | الوصف |
---|---|---|
projectId |
سلسلة | Optional. رقم تعريف مشروع Google Cloud Platform في حال حذفها،
تم استرداد projectId من متغيّر البيئة.
وGOOGLE_CLOUD_PROJECT طالما أن
access_firestore
تم ضبط إعداد الإذن لرقم تعريف المشروع على * أو
GOOGLE_CLOUD_PROJECT إذا كانت حاوية الخادم قيد التشغيل على
Google Cloud، سبق أن تم ضبط GOOGLE_CLOUD_PROJECT على
معرّف مشروع Google Cloud. |
merge |
منطقية | Optional. في حال الضبط على
true ، ثم ادمج المفاتيح من الإدخال في المستند،
وإلا فإن الطريقة ستلغي المستند بأكمله. الإعدادات التلقائية على
false |
transaction |
سلسلة | Optional. القيمة المستردة من Firestore.runTransaction(). وضع علامة على العملية المطلوب استخدامها داخل معاملة. |
مثال
const Firestore = require('Firestore');
const input = {key1: 'value1', key2: 12345};
Firestore.write('collection/document', input, {
projectId: 'gcp-cloud-project-id',
merge: true,
}).then((id) => {
data.gtmOnSuccess();
}, data.gtmOnFailure);
Firestore.query
تستعلم الدالة Firestore.query
من المجموعة المحددة وتعرض
وعد تتم حلها إلى مجموعة من مستندات Firestore التي تتطابق مع طلب البحث
الظروف. عنصر مستند Firestore هو نفسه الوارد أعلاه في
Firestore.read
إذا لم تكن هناك مستندات تطابق شروط الاستعلام،
سيحل الوعد الذي تم إرجاعه إلى صفيف فارغ.
البنية
Firestore.query(collection, queryConditions[, options]);
المعلمة | النوع | الوصف |
---|---|---|
collection |
سلسلة | المسار إلى المجموعة. يجب ألا تبدأ أو تنتهي بـ "/". |
queryConditions |
مصفوفة | مصفوفة من شروط طلب البحث. يأتي كل استعلام في شكل
مصفوفة بثلاث قيم: key،
عامل التشغيل، وestimatedValue. مثلاً:
[[‘id’, ‘<’, ‘5’], [‘state’, ‘==’, ‘CA’]]. يتم ربط الشروط معًا لإنشاء نتيجة الاستعلام. من فضلك مراجعة عوامل تشغيل طلب البحث في Firestore لقائمة من طلبات البحث المتوافقة والمشغلات. |
options |
كائن | خيارات الطلب اختيارية إليك الخيارات المتاحة: projectId وdisablecache و الحد الأقصى والمعاملة. فئة غير معروفة تجاهل مفاتيح الخيارات. (راجع الخيارات، أدناه). |
المعلمة | النوع | الوصف |
---|---|---|
projectId |
سلسلة | Optional. رقم تعريف مشروع Google Cloud Platform في حال حذفها،
تم استرداد projectId من متغيّر البيئة.
وGOOGLE_CLOUD_PROJECT طالما أن
access_firestore
تم ضبط إعداد الإذن لرقم تعريف المشروع على * أو
GOOGLE_CLOUD_PROJECT إذا كانت حاوية الخادم قيد التشغيل على
Google Cloud، سبق أن تم ضبط GOOGLE_CLOUD_PROJECT على
معرّف مشروع Google Cloud. |
disableCache |
منطقية | Optional. تحدِّد هذه السياسة ما إذا كان سيتم إيقاف ذاكرة التخزين المؤقت. يتم تمكين التخزين المؤقت افتراضيًا، والذي سيقوم بتخزين نتائج مدة الطلب. |
limit |
الرقم | Optional. تغير الحد الأقصى لعدد النتائج التي يتم عرضها بواسطة طلب البحث، تكون القيمة التلقائية هي 5. |
transaction |
سلسلة | Optional. القيمة المستردة من Firestore.runTransaction(). وضع علامة على العملية المطلوب استخدامها داخل معاملة. |
مثال
const Firestore = require('Firestore');
const queries = const queries = [['id', '==', '5']];
return Firestore.query('collection', queries, {
projectId: 'gcp-cloud-project-id',
limit: 1,
}).then((documents) => documents[0].data.key, () => undefined);
Firestore.runTransaction
تسمح الدالة Firestore.runTransaction
للمستخدم بإجراء
القراءة والكتابة من Firestore. إذا كانت هناك عملية كتابة متزامنة أو معاملة أخرى
حدوث تعارض، ستتم إعادة محاولة إجراء المعاملة مرتين. في حال فشلت
بعد ثلاث محاولات إجمالاً، سيتم رفض واجهة برمجة التطبيقات مع ظهور خطأ. تعرض واجهة برمجة التطبيقات هذه
وعد تتماشى مع مصفوفة من معرفات المستندات، لكل عملية كتابة،
إذا تمت المعاملة بنجاح، وسيتم رفضها مع عرض الخطأ إذا تعذّر إكمالها.
البنية
Firestore.runTransaction(callback[, options]);
المعلّمات
المعلمة | النوع | الوصف |
---|---|---|
callback |
الوظيفة | يشير ذلك المصطلح إلى استدعاء تم استدعاؤه باستخدام معرِّف معاملة سلسلة. تشير رسالة الأشكال البيانية يمكن تمرير معرِّف المعاملة إلى طلبات البيانات من واجهة برمجة التطبيقات للقراءة/الكتابة/الطلب. يجب أن تقدّم دالة معاودة الاتصال هذه وعدًا. وقد يتم تنفيذ معاودة الاتصال حتى ثلاث مرات قبل أن تفشل. |
options |
كائن | خيارات الطلب اختيارية الخيار المدعوم فقط هي projectId. يتم تجاهل مفاتيح الخيارات غير المعروفة. (راجع الخيارات، أدناه). |
المعلمة | النوع | الوصف |
---|---|---|
projectId |
سلسلة | Optional. رقم تعريف مشروع Google Cloud Platform في حال حذفها،
تم استرداد projectId من متغيّر البيئة.
وGOOGLE_CLOUD_PROJECT طالما أن
access_firestore
تم ضبط إعداد الإذن لرقم تعريف المشروع على * أو
GOOGLE_CLOUD_PROJECT إذا كانت حاوية الخادم قيد التشغيل على
Google Cloud، سبق أن تم ضبط GOOGLE_CLOUD_PROJECT على
معرّف مشروع Google Cloud. |
مثال
const Firestore = require('Firestore');
const path = 'collection/document';
const projectId = 'gcp-cloud-project-id';
Firestore.runTransaction((transaction) => {
const transactionOptions = {
projectId: projectId,
transaction: transaction,
};
// Must return a promise.
return Firestore.read(path, transactionOptions).then((result) => {
const newInputCount = result.data.inputCount + 1;
const input = {key1: 'value1', inputCount: newInputCount};
return Firestore.write(path, input, transactionOptions);
});
}, {
projectId: projectId
}).then((ids) => {
data.gtmOnSuccess();
}, data.gtmOnFailure);
الأخطاء المتوفّرة في كل وظيفة من وظائف Firestore سيتم رفضها باستخدام أحد العناصر
تحتوي على مفتاح reason
:
Firestore.read(...).then(onSuccess, (error) => {
if (error.reason === 'unknown') {
// Handle the unknown error here.
}
});
قد تتضمن أسباب الخطأ، على سبيل المثال لا الحصر، خطأ في واجهة برمجة تطبيقات Firestore REST الرموز:
الأذونات المرتبطة
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
يتم عرض true إذا تمت إضافة مستمع رسالة لنوع معين من الرسائل. تعرِض القيمة "خطأ" في الحالات الأخرى.
البنية
const hasMessageListener = require('hasMessageListener');
hasMessageListener('send_pixel');
الأذونات المرتبطة
بلا عُري
sendMessage
إرسال رسالة من النوع المحدّد إلى مستمع مسجَّل يمكن استخدام هذه المعلومات لإرسال رسائل من إحدى العلامات مرة أخرى إلى العميل الذي شغّل الحاوية.
البنية
const sendMessage = require('sendMessage');
sendMessage('send_pixel', {url: 'https://analytics.example.com/collect'});
المعلّمات
المعلمة | النوع | الوصف |
---|---|---|
messageType |
سلسلة | نوع الرسالة المطلوب إرسالها. إذا لم تكن القيمة سلسلة، سيتم فرضها على سلسلة. |
message |
كائن | الرسالة المطلوب إرسالها. وإذا لم تكن الرسالة كائنًا، لن تفعل واجهة برمجة التطبيقات أي شيء. |
الأذونات المرتبطة
يجب الحصول على إذن use_message
. يجب ضبط الإذن للسماح
على الأقل:
- نوع الرسالة مع
Usage
منlisten_and_send
أوsend
.
Object
تعرض كائنًا يوفّر طرق Object
.
توفّر الطريقة keys()
ملف Object.keys() للمكتبة العادية.
السلوك. يعرض صفيفًا من خاصية تعداد خاصة بكائن معين
نفس الترتيب الذي يتم به التكرار الحلقي for...in...
. إذا كانت قيمة الإدخال
وليس كائنًا، فسيتم فرضه على كائن.
توفر الطريقة values()
واجهة Object.values() للمكتبة العادية
السلوك. يعرض صفيفًا من قيم الخصائص القابلة للتعداد لكائن معين.
بالترتيب نفسه الذي يتم فيه إجراء التكرار الحلقي for...in...
. إذا لم تكن قيمة الإدخال
فسيتم فرضه على كائن.
توفّر الطريقة entries()
واجهة برمجة التطبيقات العادية Object.entries().
السلوك. يعرض صفيفًا من خاصية تعداد خاصة بكائن معين
أزواج [key, value]
بالترتيب نفسه الذي تتبعه حلقة for...in...
. إذا كانت
قيمة الإدخال ليست كائنًا، فسيتم فرضها على كائن.
توفر الطريقة freeze()
واجهة Object.freeze() للمكتبة العادية
السلوك. لم يعد من الممكن تغيير الكائن المجمّد؛ ويمنع تجميد كائن
إضافة المواقع الجديدة إليها، أو إزالة المواقع الحالية،
وقيم المواقع الحالية من التغيير. تعرض freeze()
نفس الكائن الذي تم تمريره. يتم التعامل مع الوسيطة الأساسية أو الفارغة على أنها
إذا كان كائنًا مجمدًا وسيتم إعادته.
توفّر الطريقة delete()
عامل تشغيل الحذف للمكتبة العادية.
السلوك. وتؤدي هذه السياسة إلى إزالة المفتاح المحدّد من الكائن ما لم يتم تجميده.
وكما هي الحال في عامل تشغيل حذف المكتبة العادية، تعرض الدالة true
إذا كان الإدخال الأول
القيمة (objectInput
) هي كائن لا يتم تجميده حتى إذا كان الإدخال الثاني
تحدد القيمة (keyToDelete
) مفتاحًا غير موجود. يتم إرجاع false
في
جميع الحالات الأخرى. ومع ذلك، فهو يختلف عن عامل تشغيل حذف "المكتبة العادية"
بالطرق التالية:
- لا يمكن أن يكون
keyToDelete
سلسلة مفصولة بالنقاط تحدد مفتاحًا مدمجًا. - لا يمكن استخدام
delete()
لإزالة عناصر من مصفوفة. - لا يمكن استخدام
delete()
لإزالة أي خصائص من النطاق العمومي.
البنية
Object.keys(objectInput)
Object.values(objectInput)
Object.entries(objectInput)
Object.freeze(objectInput)
Object.delete(objectInput, keyToDelete)
المعلّمات
Object.keys
المعلمة | النوع | الوصف |
---|---|---|
objectInput | أيّ | الكائن المراد تعداد مفاتيحه. إذا لم يكن الإدخال كائنًا، سيتم فرضها على كائن. |
Object.values
المعلمة | النوع | الوصف |
---|---|---|
objectInput | أيّ | الكائن المطلوب تعداد قيمه. إذا لم يكن المدخل كائنًا، سيتمّ فرضه على كائن. |
Object.entries
المعلمة | النوع | الوصف |
---|---|---|
objectInput | أيّ | الكائن الذي يتم تعداد المفتاح/القيمة له. إذا لم يكن المُدخل فسيتم فرضه على كائن. |
Object.freeze
المعلمة | النوع | الوصف |
---|---|---|
objectInput | أيّ | الكائن المراد تجميده. إذا لم يكن المدخل كائنًا، فسيتم التعامل معه على أنه كائن مجمد. |
Object.delete
المعلمة | النوع | الوصف |
---|---|---|
objectInput | أيّ | تمثّل هذه السمة الكائن الذي تريد حذف مفتاحه. |
keyToDelete | سلسلة | مفتاح المستوى الأعلى الذي تريد حذفه. |
مثال
const Object = require('Object');
// The keys of an object are enumerated in an array.
const keys = Object.keys({foo: 'bar'});
// The values of an object are enumerated in an array.
const values = Object.values({foo: 'bar'});
// The key/value pairs of an object are enumerated in an array.
const entries = Object.entries({foo: 'bar'});
// The input object is frozen.
const frozen = Object.freeze({foo: 'bar'});
// The key is removed from the input object.
const obj1 = {deleteme: 'value'};
Object.delete(obj1, 'deleteme');
// Only a top-level key can be specified as the key to delete.
const obj2 = {nested: {key: 'value'}};
Object.delete(obj2, 'nested.key'); // This has no effect.
Object.delete(obj2.nested, 'key'); // This deletes the nested key.
Promise
تعرض كائنًا يوفّر طرقًا للتفاعل مع الوعود.
تتطابق الوعود من الناحية الوظيفية مع وعود JavaScript. لكل مثيل ثلاث طرق تقدم وعودًا تتيح اتخاذ إجراء إضافي عندما يتم الوعد يستقر:
.then()
: تعالج الطلبات التي تم حلّها ورفضها على حد سواء. يستغرق الأمر عمليات الاستدعاء كمعلمات: واحدة لحالة النجاح وواحدة لحالة الإخفاق الحالة..catch()
- يعالج الطلبات المرفوضة فقط. استخدام معاودة الاتصال مرة واحدة ..finally()
- توفير طريقة لتنفيذ الرمز سواء كان الوعد حله أو رفضه. يتم استخدام عملية استدعاء واحدة كمَعلمة تم استدعاؤها باستخدام لا توجد وسيطة.
المتغير الذي يُرجع وعدًا يساوي القيمة التي تم حلها للوعد،
false
في حال رفض الوعد.
مثال
promise.then((resolvedValue) => {
// Handles when promise resolves.
}, (rejectedValue) => {
// Handles when promise rejects.
});
promise.catch((rejectedValue) => {
// Handles when promise rejects.
});
promise.finally(() => {
// Runs regardless of whether or not the previous promise resolves or
// rejects.
});
Promise.all
عرض وعد بما يلي:
- عند حل جميع المدخلات، أو
- الرفض عند رفض أي من الإدخالات
البنية
Promise.all(inputs);
المعلّمات
المعلمة | النوع | الوصف |
---|---|---|
inputs |
مصفوفة | مصفوفة من القيم أو الوعود. إذا لم يكن المُدخل وعدًا، سيتم يمر بها كما لو كانت القيمة التي تم حلها للوعد. يرمي إذا لم يكن المُدخل مصفوفة. |
مثال
const Promise = require('Promise');
const sendHttpGet = require('sendHttpGet');
return Promise.all(['a', sendHttpGet('https://example.com')])
.then((results) => {
// results will equal: ['a', {statusCode: 200, headers: {}, body: ''}]
});
الأذونات المرتبطة
بلا عُري
Promise.create
إنشاء وعد مماثل من الناحية الوظيفية لوعد استخدام JavaScript
البنية
Promise.create(resolver);
المعلّمات
المعلمة | النوع | الوصف |
---|---|---|
resolver |
الوظيفة | دالة يتم استدعاءها بدالتين: الحل والرفض. سيتم حلّ المشكلة المُراد إرجاعها أو رفضها في حال تم استدعاء المعلمة. تعرض رسالة خطأ إذا لم يكن برنامج التعيين وظيفة. |
مثال
const Promise = require('Promise');
return Promise.create((resolve, reject) => {
// Do asynchronous work that eventually calls resolve() or reject()
});
الأذونات المرتبطة
بلا عُري
اختبار واجهات برمجة التطبيقات
تعمل واجهات برمجة التطبيقات هذه مع اختبارات JavaScript في وضع الحماية لإنشاء اختبارات مخصّصة
النماذج في أداة "إدارة العلامات من Google" لا تحتاج واجهات برمجة التطبيقات التجريبية هذه إلى require()
.
الشخصي. [مزيد من المعلومات عن اختبارات النماذج المخصَّصة]
assertApi
تعرض كائن مطابقة يمكن استخدامه للتأكيد على وجود تأكيدات حول واجهة برمجة التطبيقات المحددة.
البنية
assertApi(apiName)
المعلّمات
المعلمة | النوع | الوصف |
---|---|---|
apiName |
سلسلة | اسم واجهة برمجة التطبيقات المطلوب التحقّق منها نفس السلسلة التي تم تمريرها إلى
require()
|
أدوات المطابقة
Subject.wasCalled()
Subject.wasNotCalled()
Subject.wasCalledWith(...expected)
Subject.wasNotCalledWith(...expected)
أمثلة
assertApi('sendPixel').wasCalled();
assertApi('getUrl').wasNotCalled();
assertApi('makeNumber').wasCalledWith('8');
assertApi('setInWindow').wasNotCalledWith('myVar', 'theWrongValue');
assertThat
وقد تم تصميم واجهة برمجة التطبيقات assertThat
على غرار مكتبة [Truth] من Google. تُرجع
التي يمكن استخدامها للتعبير بطلاقة عن قيمة الموضوع. إنّ
سيؤدي إخفاق التأكيد إلى إيقاف الاختبار فورًا ووضع علامة عليه كإخفاق. ومع ذلك،
عدم تأثير الفشل في اختبار واحد على حالات الاختبار الأخرى.
البنية
assertThat(actual, opt_message)
المعلّمات
المعلمة | النوع | الوصف |
---|---|---|
actual |
أيّ | القيمة التي يمكن استخدامها في عمليات التحقّق من اللغة بطلاقة |
opt_message |
سلسلة | رسالة اختيارية لطباعتها في حال تعذّر التأكيد. |
أدوات المطابقة
مطابق | الوصف |
---|---|
isUndefined() |
التأكيد على أن الموضوع هو undefined . |
isDefined() |
التأكيد على أن الموضوع ليس undefined . |
isNull() |
التأكيد على أن الموضوع هو null . |
isNotNull() |
التأكيد على أن الموضوع ليس null . |
isFalse() |
التأكيد على أن الموضوع هو false . |
isTrue() |
التأكيد على أن الموضوع هو true . |
isFalsy() |
يؤكد أن الموضوع غير حقيقي. القيم الخاطئة
undefined ، null ، false ،
NaN و0 و'' (سلسلة فارغة). |
isTruthy() |
التأكيد على أنّ الموضوع صادق القيم الخاطئة
undefined ، null ، false ،
NaN و0 و'' (سلسلة فارغة). |
isNaN() |
تؤكد أن الموضوع هو قيمة NaN. |
isNotNaN() |
تؤكد أن الموضوع هو أي قيمة بخلاف NaN. |
isInfinity() |
تؤكد أن الموضوع لانهائي إيجابي أو سلبي. |
isNotInfinity() |
تؤكد على أن الموضوع يمثل أي قيمة بخلاف الإيجابية أو السلبية ما لا نهاية. |
isEqualTo(expected) |
تأكيد أن الموضوع مساوٍ للقيمة المحددة. هذه قيمة وليس مقارنة مرجعية. محتويات الكائنات والصفائف بشكل متكرر. |
isNotEqualTo(expected) |
تؤكد أن الموضوع لا يساوي القيمة المقدمة. هذا هو وليس مقارنة مرجعية. قد تتضمن محتويات الكائنات تتم مقارنة الصفائف بشكل متكرر. |
isAnyOf(...expected) |
تأكيد أن الموضوع يساوي إحدى القيم المحددة. هذا هو وليس مقارنة مرجعية. قد تتضمن محتويات الكائنات تتم مقارنة الصفائف بشكل متكرر. |
isNoneOf(...expected) |
تؤكد أن الموضوع لا يساوي أيًا من القيم المحددة. هذا النمط هي مقارنة القيم، وليست مقارنة مرجعية. محتوى العناصر تتم مقارنة الصفائف بشكل متكرر. |
isStrictlyEqualTo(expected) |
تؤكد أن الموضوع متساوي تمامًا (=== ) مع
قيمة معينة. |
isNotStrictlyEqualTo(expected) |
تؤكد أن الموضوع لا يساوي تمامًا (!== ) مع
للقيمة المحددة. |
isGreaterThan(expected) |
التأكيد على أن الموضوع أكبر من (> ) المحدد
قيمة في مقارنة مرتبة. |
isGreaterThanOrEqualTo(expected) |
تؤكد أن الموضوع أكبر من أو يساوي
(>= ) القيمة المحددة في مقارنة مرتبة. |
isLessThan(expected) |
التأكيد على أن الموضوع أقل من (< ) المحدد
قيمة في مقارنة مرتبة. |
isLessThanOrEqualTo(expected) |
التأكيد على أن الموضوع أقل من أو يساوي (<= )
القيمة المحددة في مقارنة مرتبة. |
contains(...expected) |
التأكيد على أن الموضوع عبارة عن صفيف أو سلسلة تحتوي على جميع القيم المحددة بأي ترتيب. هذه مقارنة قيم، وليست مرجعًا والمقارنة. تتم مقارنة محتوى الكائنات والصفائف. بشكل متكرر. |
doesNotContain(...expected) |
التأكيد على أن الموضوع عبارة عن مصفوفة أو سلسلة لا تحتوي على أي مما يلي القيم المحددة. هذه مقارنة قيم، وليست مقارنة مرجعية. تتم مقارنة محتوى الكائنات والصفائف بشكل متكرر. |
containsExactly(...expected) |
تؤكد أن الموضوع عبارة عن صفيف يشتمل على جميع بأي ترتيب وبدون قيم أخرى. هذه مقارنة قيمة، مقارنة مرجعية. تتم مقارنة محتوى الكائنات والصفائف. بشكل متكرر. |
doesNotContainExactly(...expected) |
التأكيد على أن الموضوع عبارة عن صفيف يحتوي على مجموعة مختلفة من القيم من القيم المحددة بأي ترتيب. هذه مقارنة القيمة، وليس مقارنة مرجعية. محتويات الكائنات والصفائف بشكل متكرر. |
hasLength(expected) |
التأكيد على أن الموضوع عبارة عن مصفوفة أو سلسلة بالطول المحدد. يتعذّر التأكيد دائمًا إذا لم تكن القيمة مصفوفة أو سلسلة. |
isEmpty() |
تؤكد أن الموضوع عبارة عن صفيف أو سلسلة فارغة (الطول = 0). يخفق التأكيد دائمًا إذا لم تكن القيمة مصفوفة أو سلسلة. |
isNotEmpty() |
التأكيد على أن الموضوع عبارة عن مصفوفة أو سلسلة غير فارغة (الطول > 0). يفشل التأكيد دائمًا إذا لم تكن القيمة مصفوفة أو سلسلة. |
isArray() |
تؤكد أن نوع الموضوع مصفوفة. |
isBoolean() |
تؤكد على أن نوع الموضوع منطقي. |
isFunction() |
تؤكد على أن نوع الموضوع دالة. |
isNumber() |
تؤكد على أن نوع الموضوع رقم. |
isObject() |
تؤكد على أن نوع الموضوع عبارة عن كائن. |
isString() |
تؤكد على أن نوع الموضوع عبارة عن سلسلة. |
أمثلة
assertThat(undefined).isUndefined();
assertThat(id, 'ID must be defined').isDefined();
assertThat(null).isNull();
assertThat(undefined).isNotNull();
assertThat(true).isTrue();
assertThat(false).isFalse();
assertThat(1).isTruthy();
assertThat('').isFalsy();
assertThat(1/0).isInfinity();
assertThat(0).isNotInfinity();
assertThat(-'foo').isNaN();
assertThat(100).isNotNaN();
assertThat(sentUrl).isEqualTo('https://endpoint.example.com/?account=12345');
assertThat(category).isNotEqualTo('premium');
assertThat(5).isAnyOf(1, 2, 3, 4, 5);
assertThat(42).isNoneOf('the question', undefined, 41.9);
assertThat('value').isStrictlyEqualTo('value');
assertThat('4').isNotStrictlyEqualTo(4);
assertThat(['a', 'b', 'c']).contains('a', 'c');
assertThat(['x', 'y', 'z']).doesNotContain('f');
assertThat(['1', '2', '3']).containsExactly('3', '2', '1');
assertThat(['4', '5']).doesNotContainExactly('4');
assertThat('a string').hasLength(8);
assertThat([]).isEmpty();
assertThat('another string').isNotEmpty();
fail
عند اجتياز الاختبار الحالي فورًا، تتم طباعة الرسالة المحدّدة إذا كانت متوفّرة.
البنية
fail(opt_message);
المعلّمات
المعلمة | النوع | الوصف |
---|---|---|
opt_message |
سلسلة | نص رسالة خطأ اختياري. |
مثال
fail('This test has failed.');
mock
تتيح لك واجهة برمجة التطبيقات mock
إلغاء سلوك واجهات برمجة التطبيقات التي تم وضع الحماية لها. النموذج الوهمي
يمكن استخدام واجهة برمجة التطبيقات بأمان في رمز النموذج، ولكنّها لا تعمل إلا في وضع الاختبار.
وتتم إعادة ضبط النماذج قبل إجراء كل اختبار.
البنية
mock(apiName, returnValue);
المعلّمات
المعلمة | النوع | الوصف |
---|---|---|
apiName |
سلسلة | اسم واجهة برمجة التطبيقات المطلوب محاكاةها نفس السلسلة التي تم تمريرها إلى
require() |
returnValue |
أيّ | القيمة المطلوب عرضها لواجهة برمجة التطبيقات أو دالة يتم استدعاءها بدلاً من
واجهة برمجة التطبيقات. إذا كانت returnValue دالة، يتم استدعاء هذه الدالة في
مكان واجهة برمجة التطبيقات Sandboxed API إذا كانت السمة returnValue تمثّل أي قيمة أخرى
من إحدى الدوال، يتم عرض هذه القيمة بدلاً من وضع الحماية
واجهة برمجة التطبيقات. |
أمثلة
mock('encodeUri', "https://endpoint.example.com/?account=12345");
mock('sendPixel', function(url, onSuccess, onFailure) {
onSuccess();
});
mockObject
تتيح لك واجهة برمجة التطبيقات mockObject
إلغاء سلوك واجهات برمجة التطبيقات ذات وضع الحماية التي
لإرجاع كائن. يمكن استخدام واجهة برمجة التطبيقات بأمان في رمز النموذج، ولكنّها قابلة للتشغيل
في وضع الاختبار فقط. وتتم إعادة ضبط النماذج قبل إجراء كل اختبار.
البنية
mockObject(apiName, objectMock);
المعلّمات
المعلمة | النوع | الوصف |
---|---|---|
apiName |
سلسلة | اسم واجهة برمجة التطبيقات المطلوب محاكاةها نفس السلسلة التي تم تمريرها إلى
require() |
objectMock |
كائن | القيمة المطلوب عرضها لواجهة برمجة التطبيقات أو دالة يتم استدعاءها بدلاً من واجهة برمجة التطبيقات. يجب أن تكون كائنًا. |
أمثلة
const storage = {};
let firestoreId = 1;
function asTestPromise(result) {
return {
then: (callback) => callback(result)
};
}
mockObject('Firestore', {
write: (collection, input) => {
storage[collection + '/' + (++firestoreId)] = input;
return asTestPromise(firestoreId);
},
read: (document) => asTestPromise({data: storage[document]})
});
runCode
لتشغيل رمز النموذج، أي محتوى علامة التبويب الرمز في بيئة الاختبار الحالية مع كائن بيانات إدخال معين.
البنية
runCode(data)
المعلّمات
المعلمة | النوع | الوصف |
---|---|---|
data |
كائن | كائن البيانات المطلوب استخدامه في الاختبار. |
القيمة المعروضة
لعرض قيمة متغير لنماذج المتغير؛ يُرجع undefined
مقابل
جميع أنواع النماذج الأخرى.
مثال
runCode({field1: 123, field2: 'value'});