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

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

---

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

• يتم التحقّق منها من خلال واجهات برمجة التطبيقات التي تتطلّب ذلك.
• تم اكتشافه تلقائيًا في 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 - لمنح إذن الوصول إلى واجهات برمجة التطبيقات للقراءة وطلبات البحث
• كتابة - منح إمكانية الدخول لكتابة واجهة برمجة التطبيقات
• read_ write - منح حق الوصول إلى واجهات برمجة التطبيقات للقراءة والكتابة والاستعلام

<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 من واجهات برمجة التطبيقات.

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

مطلوب من: 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 واجهات برمجة التطبيقات.

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

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);
}