أذونات النماذج المخصَّصة من جهة الخادم

يوضّح هذا المستند أذونات النماذج المخصَّصة من جهة الخادم.

---

يتميّز كل إذن بما يلي:

• تم التحقّق من البيانات بواسطة واجهات برمجة التطبيقات التي تتطلّبها.
• يتم رصدها تلقائيًا في JavaScript في وضع الحماية، استنادًا إلى واجهات برمجة التطبيقات التي يتم استخدامها. ويحدث ذلك عند إجراء تعديلات في محرِّر النماذج المخصّصة (للحصول على تقرير ملاحظات سريع)، وبعد تجميع الرمز (للتحقّق من فرض الأذونات الصحيحة).
• قابل للتعديل في محرِّر النماذج المخصّصة لجعل الإذن أكثر تحديدًا.
• يمكن طلب البحث في JavaScript في وضع الحماية من خلال واجهة برمجة التطبيقات queryPermission.

access_bigquery

الاسم المعروض: تصل إلى BigQuery

الوصف: تسمح بالوصول إلى BigQuery على Google Cloud Platform.

الإعداد: خيار السماح باستخدام مجموعات محدّدة من المشاريع ومجموعات البيانات والجداول مع BigQuery. سيسمح ضبط إعداد رقم تعريف مشروع في GOOGLE_CLOUD_PROJECT باستخدام متغير بيئة GOOGLE_CLOUD_PROJECT كرقم تعريف المشروع عند استبعاد projectId من BigQuery API parameter.

مطلوب من: BigQuery

توقيع طلب البحث: queryPermission('access_bigquery', <operation>, <options>)

ملاحظات: <operation> هي سلسلة ويمكن أن تحتوي على القيم التالية:

• كتابة

<options> هو كائن يحتوي على العناصر التالية:

{
  'projectId': <project_id>,
  'datasetId': <dataset_id>,
  'tableId': <table_id>
}

مثال على الرمز

const BigQuery = require('BigQuery');
const queryPermission = require('queryPermission');

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

if (queryPermission('access_bigquery', 'write', connectionInfo)) {
  const rows = [{
    'column1': 'String1',
    'column2': 1234,
  }];
  const options = {
    'ignoreUnknownValues': true,
    'skipInvalidRows': false,
  };

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

access_firestore

الاسم المعروض: للوصول إلى Google Firestore

الوصف: السماح بالوصول إلى Google Firestore.

التهيئة: خيار السماح باستخدام مجموعات محددة من المشروع والمسار (بناء جملة حرف البدل) مع Firestore. سيسمح ضبط إعداد رقم تعريف مشروع لـ GOOGLE_CLOUD_PROJECT باستخدام متغيّر بيئة GOOGLE_CLOUD_PROJECT كرقم تعريف المشروع عند استبعاد projectId من Firestore API parameter.

مطلوب من: Firestore

توقيع طلب البحث: queryPermission('access_firestore', <operation>, <options>)

ملاحظات: <operation> هي سلسلة ويمكن أن تحتوي على القيم التالية:

• القراءة - لمنح إمكانية الوصول لقراءة واجهات برمجة التطبيقات وطلب البحث عنها
• الكتابة - يمنح حق الوصول لكتابة واجهة برمجة التطبيقات
• read_كتابة - لمنح حق الوصول إلى واجهات برمجة التطبيقات للقراءة والكتابة والاستعلام

<options> هو كائن يحتوي على العناصر التالية:

{
  'projectId': <project_id>,
  'path': <path>
}

مثال على الرمز

const Firestore = require('Firestore');
const queryPermission = require('queryPermission');

const options = {
  'projectId': 'gcp-cloud-project-id',
  'path': 'collection/document',
};

if (queryPermission('access_firestore', 'read', options)) {
  Firestore.read('collection/document', {
    projectId: 'gcp-cloud-project-id',
  }).then(data.gtmOnSuccess, data.gtmOnFailure);
}

access_response

الاسم المعروض: للوصول إلى الردّ

الوصف: الوصول إلى نص الاستجابة أو العناوين أو الحالة

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

مطلوب من: setPixelResponse، setResponseBody، setResponseHeader، setResponseStatus

توقيع طلب البحث: queryPermission('access_response', 'write', <component>[, <optional component name>])

ملاحظات: يتحكّم هذا الإعداد في إمكانية الوصول إلى مكوّن استجابة HTTP الصادرة.

مثال على الرمز

const queryPermission = require('queryPermission');
const setResponseBody = require('setResponseBody');
const setResponseHeader = require('setResponseHeader');
const setResponseStatus = require('setResponseStatus');
if (queryPermission('access_response', 'write', 'header', 'Content-Type')) {
  setResponseHeader('Content-Type', 'text/plain');
}
if (queryPermission('access_response', 'write', 'body')) {
  setResponseBody('Not Found');
}
if (queryPermission('access_response', 'write', 'status')) {
  setResponseStatus(404);
}

access_template_storage

الاسم المعروض: الوصول إلى مساحة تخزين النماذج

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

الإعدادات: غير متوفّرة

مطلوب من: templateDataStorage

توقيع طلب البحث: queryPermission('access_template_storage')

مثال على الرمز

const queryPermission = require('queryPermission');
const templateDataStorage = require('templateDataStorage');
const key = 'my_key';
if (queryPermission('access_template_storage')) {
  const value = templateDataStorage.getItemCopy(key);
}

get_cookies

الاسم المعروض: يقرأ قيم ملفات تعريف الارتباط

الوصف: تقرأ قيم ملفات تعريف الارتباط بالاسم المحدَّد.

الإعداد: قائمة بأسماء ملفات تعريف الارتباط المسموح بها للقراءة.

مطلوب من: getCookieValues

توقيع طلب البحث: queryPermission('get_cookies', <name>)

ملاحظات: يتحكّم هذا الخيار في إمكانية قراءة ملف تعريف الارتباط، وذلك استنادًا إلى اسمه.

مثال على الرمز

const queryPermission = require('queryPermission');
const getCookieValues = require('getCookieValues');
const cookieName = 'info';
let cookieValues;
if (queryPermission('get_cookies', cookieName)) {
  cookieValues = getCookieValues(cookieName);
}

تسجيل

الاسم المعروض: السجلات في وحدة التحكّم

الوصف: يُسجِّل هذا القسم وحدة تحكُّم المطوِّر ووضع المعاينة في أداة "إدارة العلامات من Google".

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

مطلوب من: logToConsole

توقيع طلب البحث: queryPermission('logging')

ملاحظات: تتحكَّم هذه السياسة في إمكانية تسجيل نموذج مخصَّص إلى وحدة تحكُّم المطوِّر.

مثال على الرمز

const queryPermission = require('queryPermission');
const logToConsole = require('logToConsole');
// Note that it's fine to call log, since the log call will be ignored if
// logging isn't permitted in the current environment.
logToConsole('diagnostic info');

use_message

الاسم المعروض: لاستخدام الرسائل

الوصف: لإرسال الرسائل أو تلقّيها باستخدام addMessageListener أو sendMessage API

الإعداد: خيار تحديد نوع الرسالة وما إذا كان النموذج يمكنه الاستماع أو الإرسال أو كليهما.

مطلوب من: addMessageListener، sendMessage

توقيع طلب البحث: queryPermission('use_message', <usage>, <message type>)

ملاحظات: يمكن أن يكون الاستخدام listen، أو send، أو listen_and_send.

مثال على الرمز

const queryPermission = require('queryPermission');
const sendMessage = require('sendMessage');
if (queryPermission('use_message', 'send', 'set_cookie')) {
  sendMessage('set_cookie', {name: 'foo', value: 'bar'});
}

read_container_data

الاسم المعروض: لقراءة بيانات الحاوية

الوصف: تقرأ بيانات عن الحاوية.

الإعدادات: غير متوفّرة.

مطلوب من: getClientName، getContainerVersion

توقيع طلب البحث: queryPermission('read_container_data')

ملاحظات: تتحكّم هذه السياسة في ما إذا كان النموذج المخصّص يمكنه قراءة بيانات الحاوية.

مثال على الرمز

const getContainerVersion = require('getContainerVersion');
const queryPermission = require('queryPermission');
if (queryPermission('read_container_data')) {
  return getContainerVersion();
}

read_event_data

الاسم المعروض: لقراءة بيانات الأحداث

الوصف: لقراءة البيانات من الحدث.

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

مطلوب من: getAllEventData، getEventData

توقيع طلب البحث: queryPermission('read_event_data'[, <optional key>])

ملاحظات: تتحكّم هذه السياسة في ما إذا كان بإمكان النموذج المخصّص قراءة بيانات الأحداث في مسار مفتاح معيّن (أو جميع بيانات الأحداث، في حال عدم توفير مسار رئيسي).

مثال على الرمز

const getAllEventData = require('getAllEventData');
const queryPermission = require('queryPermission');
if (queryPermission('read_event_data')) {
  return getAllEventData();
}

const getEventData = require('getEventData');
const queryPermission = require('queryPermission');
const keyPath = 'parentField.childField';
if (queryPermission('read_event_data', keyPath)) {
  return getEventData(keyPath);
}

read_event_metadata

الاسم المعروض: لقراءة البيانات الوصفية للحدث

الوصف: قراءة البيانات الوصفية للحدث في طلبات معاودة الاتصال للأحداث

الإعدادات: غير متوفّرة

مطلوب من: addEventCallback

توقيع طلب البحث: queryPermission('read_event_metadata')

ملاحظات: تتحكَّم هذه السياسة في ما إذا كان بإمكان نموذج مخصَّص قراءة البيانات الوصفية للحدث في عمليات معاودة الاتصال.

مثال على الرمز

const queryPermission = require('queryPermission');
const addEventCallback = require('addEventCallback');
if (queryPermission('read_event_metadata')) {
  addEventCallback((containerId, eventMetadata) => {
    // Read event metadata.
  });
}

read_request

الاسم المعروض: يقرأ طلب HTTP

الوصف: تقرأ عناوين الطلبات أو معلَمات طلب البحث أو النص أو المسار أو عنوان IP البعيد.

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

مطلوب من: extractEventsFromMpv1 وextractEventsFromMpv2 getRemoteAddress وgetRequestBody وgetRequestHeader وgetRequestPath وgetRequestQueryParameter وgetRequestQueryParameters getRequestQueryString

توقيع طلب البحث: queryPermission('read_request', <component>[, <optional component name>])

ملاحظات: يتحكّم هذا الإعداد في إمكانية الوصول إلى مكوّن استجابة HTTP الوارد.

مثال على الرمز

const queryPermission = require('queryPermission');
const getRequestBody = require('getRequestBody');
const getRequestHeader = require('getRequestHeader');
let body, contentType;
if (queryPermission('read_request', 'body')) {
  body = getRequestBody();
}
if (queryPermission('read_request', 'header', 'content-type')) {
  contentType = getRequestHeader('content-type');
}
if (body && contentType == 'application/json') { ... }

return_response

الاسم المعروض: يعرض الردّ

الوصف: يعرض الردّ على المتصل.

الإعدادات: غير متوفّرة

مطلوب من: returnResponse

توقيع طلب البحث: queryPermission('return_response')

ملاحظات: لا يحتوي هذا الإذن على حقول لتضييق نطاقه، ولا يتم الاستعلام عنه عادةً.

run_container

الاسم المعروض: يشغِّل الحاوية

الوصف: لتشغيل الحاوية مع حدث

الإعدادات: غير متوفّرة

مطلوب من: runContainer

توقيع طلب البحث: queryPermission('run_container')

ملاحظات: لا يحتوي هذا الإذن على حقول لتضييق نطاقه، ولا يتم الاستعلام عنه عادةً.

send_http

الاسم المعروض: يُرسل طلبات HTTP

الوصف: لإرسال طلب HTTP إلى عنوان URL محدّد.

مطلوب من: getGoogleScript، sendEventToGoogleAnalytics، sendHttpGet، sendHttpRequest

توقيع طلب البحث: queryPermission('send_http', <url>)

ملاحظات: تتحكّم هذه السياسة في إمكانية تقديم طلب HTTP، وذلك استنادًا إلى عنوان URL. لضمان اتصال آمن، يُسمح فقط بعناوين URL الآمنة (HTTPS).

مثال على الرمز

const queryPermission = require('queryPermission');
const sendHttpGet = require('sendHttpGet');
const url = 'https://example.com/search?query=foo&results=10';
if (queryPermission('send_http', url)) {
  sendHttpGet(url);
}

send_pixel_from_browser

اسم العرض: يرسل وحدات البكسل من المتصفحات

الوصف: لإرسال طلب GET إلى عنوان URL محدّد من المتصفّح.

مطلوب من: sendPixelFromBrowser

توقيع طلب البحث: queryPermission('send_pixel_from_browser', <url>)

ملاحظات: تتحكّم هذه السياسة في ما إذا كان من الممكن إرسال الطلب من المتصفّح استنادًا إلى عنوان URL.

مثال على الرمز

const queryPermission = require('queryPermission');
const sendPixelFromBrowser = require('sendPixelFromBrowser');
const url = 'https://example.com/search?query=foo&results=10';
if (queryPermission('send_pixel_from_browser', url)) {
  sendPixelFromBrowser(url);
}

set_cookies

الاسم المعروض: لضبط ملف تعريف ارتباط

الوصف: لإعداد ملف تعريف ارتباط بالاسم والمَعلمات المحدَّدة

الضبط: جدول يضم أسماء ملفات تعريف الارتباط المسموح بها، ويشمل كل منها قيودًا اختيارية على الاسم والنطاق والمسار وسمة secure وتاريخ انتهاء الصلاحية.

مطلوب من: setCookie

توقيع طلب البحث: queryPermission('set_cookies', <name>, <options>)

ملاحظات: يتحكّم هذا الإعداد في إمكانية إضافة عنوان "Set-Cookie" محدّد إلى الاستجابة، وذلك استنادًا إلى اسم ملف تعريف الارتباط والنطاق والمسار وسمة secure وانتهاء الصلاحية.

مثال على الرمز

const queryPermission = require('queryPermission');
const setCookie = require('setCookie');
const options = {
  'domain': 'www.example.com',
  'path': '/',
  'max-age': 60*60*24*365,
  'secure': true
};
if (queryPermission('set_cookies', 'info', options)) {
  setCookie('info', 'xyz', options);
}

use_custom_private_keys

الاسم المعروض: يستخدم مفاتيح خاصة مخصّصة.

الوصف: يستخدم هذا الإعداد مفاتيح خاصة من ملف مفتاح JSON لعمليات التشفير.

الإعدادات: قائمة بمعرّفات المفاتيح المسموح بها يجب أن تتطابق أرقام التعريف مع المفاتيح في ملف مفتاح JSON الذي يشير إليه متغير بيئة SGTM_CREDENTIALS على الخادم.

مطلوب من: hmacSha256

توقيع طلب البحث: queryPermission('use_custom_private_keys', <key id>)

ملاحظات: يتحكّم هذا الخيار في قائمة المفاتيح الخاصة المسموح بها.

مثال على الرمز

const hmacSha256= require('hmacSha256');
const queryPermission = require('queryPermission');
const keyId = 'key1';

let result;
if (queryPermission('use_custom_private_keys', keyId)) {
  result = hmacSha256('my_data', keyId);
}

use_google_credentials

الاسم المعروض: يستخدم بيانات الاعتماد التلقائية لتطبيق Google

الوصف: يستخدم هذا الخيار بيانات اعتماد Google التلقائية لإجراء اتصالات بواجهات برمجة تطبيقات Google.

الإعدادات: قائمة بنطاقات Google OAuth 2.0 المسموح بها

مطلوب من: getGoogleAuth

توقيع طلب البحث: queryPermission('use_google_credentials', <scopes>)

ملاحظات: يتم تقييد نطاقات Google OAuth 2.0 المسموح بها للاستخدام مع Google APIs.

مثال على الرمز

const getGoogleAuth = require('getGoogleAuth');
const queryPermission = require('queryPermission');

const scopes = [
  'https://www.googleapis.com/auth/datastore'
];

let auth;
if (queryPermission('use_google_credentials', scopes)) {
  auth = getGoogleAuth(scopes);
}