دليل الإعداد اليدوي

يمكن استخدام مسار التوفير التلقائي لنشر خادم وضع العلامات على Cloud Run ببضع نقرات فقط. إذا كنت تريد توفير خادم وضع العلامات في بيئات أخرى، يمكنك إجراء ذلك يدويًا. خادم وضع العلامات هو خادم Node.js داخل صورة Docker.

تتطلّب عملية توفير خادم وضع العلامات يدويًا توفير مجموعة خادم وضع العلامات من جهة الخادم (SST) وخادم معاينة بشكل منفصل. مجموعة خوادم SST هي نقطة الدخول لجميع الطلبات إلى خادم وضع العلامات، وستتعامل مع الطلبات كما هو موضّح في مقدمة عن وضع العلامات من جهة الخادم. خادم المعاينة مطلوب لمعاينة حاوية.

راجِع الشكل 1 للاطّلاع على توضيح لتفاعل البيانات بين خوادم وضع العلامات وخادم المعاينة.

مخطّط انسيابي لبيانات خوادم وضع العلامات وخادم المعاينة

الشكل 1: رسم بياني لخوادم وضع العلامات وتدفّق بيانات خادم المعاينة

يوضّح هذا الدليل كيفية تنفيذ ما يلي:

  • عرض جميع الإعدادات المتاحة لصورة Docker
  • (اختياري) تضمين بيانات اعتماد BigQuery
  • توفير خادم معاينة يدويًا باستخدام صورة SST Docker
  • توفير مجموعة SST يدويًا باستخدام صورة SST Docker
  • تأكَّد من ضبط خادم المعاينة ومجموعة خوادم SST بشكلٍ صحيح.
  • احرص على تحديث إصدار خادم وضع العلامات بعد توفير الخادم.

لتنفيذ أوامر Docker الواردة في هذا الدليل، يجب أولاً تثبيت Docker على جهاز الكمبيوتر.

عرض جميع الإعدادات المتاحة لصورة Docker

يمكن العثور على صورة Docker لخادم وضع العلامات على عنوان URL التالي:

gcr.io/cloud-tagging-10302018/gtm-cloud-image:stable

يستخدم خادم وضع العلامات وخادم المعاينة صورة Docker نفسها مع علامات مختلفة. في هذا القسم، سنشرح كيفية البحث عن جميع الإعدادات المتاحة التي يمكن استخدامها مع صورة Docker.

للاطّلاع على جميع الإعدادات المتاحة، نفِّذ ما يلي باستخدام أداة سطر الأوامر Docker:

docker run gcr.io/cloud-tagging-10302018/gtm-cloud-image:stable server_bin.js --help

(اختياري) تضمين بيانات اعتماد Google Cloud

لاستخدام واجهة برمجة التطبيقات BigQuery أو Firestore خارج Google Cloud، يجب تقديم بيانات اعتماد حساب خدمة مخوَّلة بالوصول إلى هذه الموارد.

  1. اتّبِع هذا الدليل لإنشاء حساب خدمة لديه دور محرّر بيانات BigQuery للوصول إلى BigQuery أو دور مستخدم Cloud Datastore للوصول إلى Firestore وتصدير بيانات اعتماد JSON الخاصة به باسم الملف local_service_account_key.json.
  2. ربط بيانات اعتماد JSON في وحدة تخزين يمكن الوصول إليها من الصورة باستخدام docker run، يمكنك تحديد -v local_service_account_key.json:/app/service_account_key.json لتثبيت بيانات الاعتماد في الصورة.
  3. وجِّه متغيّر البيئة GOOGLE_APPLICATION_CREDENTIALS إلى بيانات الاعتماد.
  4. يمكنك اختياريًا تحديد رقم تعريف مشروع Google Cloud في متغيّر البيئة GOOGLE_CLOUD_PROJECT للسماح لخادم وضع العلامات باختيار المشروع ضمنيًا.

  5. شغِّل الخادم. ينفّذ الأمر التالي خادم وضع العلامات مع تضمين بيانات الاعتماد:

    docker run -v local_service_account_key.json:/app/service_account_key.json \
-p 8080:8080 \
-e GOOGLE_APPLICATION_CREDENTIALS='/app/service_account_key.json' \
-e GOOGLE_CLOUD_PROJECT='<your project id>' \
-e CONTAINER_CONFIG='<config string>' \
gcr.io/cloud-tagging-10302018/gtm-cloud-image:stable

استنادًا إلى النظام الذي يتم نشر خادم وضع العلامات عليه، قد تتوفّر طرق مختلفة لربط بيانات الاعتماد. على سبيل المثال، يوفّر Kubernetes وDocker Swarm أدلة لإدارة البيانات السرية. يُرجى الرجوع إلى دليل النظام المعنيّ للحصول على مزيد من المعلومات.

احرص على اتّباع أفضل الممارسات لحماية بيانات الاعتماد.

توفير خادم معاينة يدويًا

يتيح لك خادم المعاينة معاينة حاوية الخادم. لتشغيل خادم المعاينة، شغِّل صورة Docker مع متغيرات البيئة التالية التي تم تمريرها إلى بيئة Docker.

الإعدادات المطلوبة

  • CONTAINER_CONFIG: سلسلة الإعدادات لحاوية الخادم. في أداة Tag Manager، انتقِل إلى مساحة عمل حاوية الخادم وانقر على رقم تعريف الحاوية في أعلى يسار الصفحة. انقر على توفير خادم وضع العلامات يدويًا للعثور على قيمة إعداد الحاوية.

  • اضبط هذا الخيار على true لتوفير الخادم كخادم معاينة.RUN_AS_PREVIEW_SERVER

مثال على استخدام أداة سطر الأوامر Docker

لتوفير خادم معاينة محليًا، نفِّذ ما يلي:

docker run -p 8080:8080 -e CONTAINER_CONFIG='<config string>' -e RUN_AS_PREVIEW_SERVER=true gcr.io/cloud-tagging-10302018/gtm-cloud-image:stable

من المفترض أن يظهر لك الرمز 200 عند إرسال طلب إلى http://localhost:8080/healthy. يمكنك اختياريًا استخدام متغيّر البيئة PORT لتغيير المنفذ.

أفضل الممارسات

  • يجب نشر خادم معاينة واحد بالضبط. لا تضبط ميزة التوسيع التلقائي بما يتجاوز مثيلاً واحدًا.
  • بعد إعداد خادم معاينة باستخدام Docker، اضبط عنوان URL لبروتوكول HTTPS للإشارة إلى خادم المعاينة. هذا الإجراء مطلوب لإعداد مجموعة SST.
  • يجب أن يكون مهلة التحميل في موازن التحميل أو شبكة توصيل المحتوى أطول من 20 ثانية، وإلا لن يعمل وضع المعاينة بشكل صحيح.

توفير مجموعة من خوادم وضع العلامات من جهة الخادم يدويًا

تعمل مجموعة خوادم SST كنقطة دخول، وتعمل كخادم وكيل لطلبات المعاينة إلى خادم المعاينة، وتتعامل مع جميع الطلبات الأخرى كما هو موضّح في مقدمة عن وضع العلامات من جهة الخادم. استخدِم الإعدادات المطلوبة التالية مع صورة Docker لخادم وضع العلامات لتوفير مجموعة خوادم من جهة الخادم (SST) في أي بيئة متوافقة مع Docker.

الإعدادات المطلوبة

  • CONTAINER_CONFIG: سلسلة الإعدادات لحاوية الخادم. في أداة Tag Manager، انتقِل إلى مساحة عمل حاوية الخادم وانقر على رقم تعريف الحاوية في أعلى يسار الصفحة. انقر على توفير خادم وضع العلامات يدويًا للعثور على قيمة إعداد الحاوية.

  • PREVIEW_SERVER_URL: عنوان URL الذي يستخدم HTTPS لخادم المعاينة. يجب ضبط هذا الإعداد فقط لتوفير خادم وضع العلامات، وهو غير مطلوب لتوفير خادم المعاينة. راجِع القسم أعلاه للحصول على دليل حول إعداد خادم المعاينة.

مثال على استخدام أداة سطر الأوامر Docker

لتوفير خادم وضع علامات واحد على المستوى المحلي، نفِّذ ما يلي:

docker run -p 8080:8080 -e CONTAINER_CONFIG='<config string>' -e PREVIEW_SERVER_URL='<HTTPS preview server url>' gcr.io/cloud-tagging-10302018/gtm-cloud-image:stable

من المفترض أن يظهر لك الرمز 200 عند إرسال طلب إلى http://localhost:8080/healthy. يمكنك اختياريًا استخدام متغيّر البيئة PORT لتغيير المنفذ.

أفضل الممارسات

  • يمكن توفير خوادم وضع العلامات من جهة الخادم إما كخادم واحد أو كمجموعة خوادم. ننصحك بتوفيرها كمجموعة لتحسين مستوى التوفّر وقابلية التوسّع والأداء. يُرجى العِلم أنّه عند توفير مثيل خادم كمجموعة، يجب إعداد كل مثيل خادم باستخدام متغيرَي البيئة CONTAINER_CONFIG وPREVIEW_SERVER_URL نفسيهما.
  • احرص على استضافة خادم وضع العلامات في المصدر نفسه (أفضل الممارسات) أو كنطاق فرعي لموقعك الإلكتروني الحالي. على سبيل المثال، إذا كان تطبيقك يعرض محتوى على الويب على example.com، استخدِم مسارًا مثل example.com/analytics لخادم وضع العلامات. مزيد من المعلومات حول إعداد النطاق المخصّص
  • بعد إعداد مجموعة SST باستخدام Docker، اضبط عنوان URL لبروتوكول HTTPS للإشارة إلى مجموعة SST.
  • احرص على إعادة تشغيل الخوادم بشكل دوري لضمان توفّر آخر تحديثات الرموز البرمجية في خوادمك من أجل ميزة "العرض من جهة الخادم". وقد يؤدي عدم إجراء ذلك إلى عدم توافق بعض وظائف ميزات SST الجديدة. إحدى طرق معرفة الوقت الذي يجب فيه إعادة تشغيل الخادم هي إعداد عمليات التحقّق من النشاط، كما هو موضّح أدناه. يُرجى أيضًا العِلم أنّه سيتم تطبيق أي تحديثات منشورة على حاوية الخادم بدون الحاجة إلى إعادة التشغيل.
  • استخدِم نقطة النهاية الحالية /healthy (مثل https://analytics.example.com/healthy) على خوادم وضع العلامات لإعداد عمليات التحقّق من النشاط. تشير الاستجابة غير السليمة إلى أنّه يجب إعادة تشغيل الخادم.
  • يتضمّن حاوي Docker أمرًا تلقائيًا للتحقّق من الصحة، وهو HEALTHCHECK CMD ["/nodejs/bin/node", "/app/health_checker_bin.js"]، يطلب البيانات من نقطة النهاية /healthy بشكل دوري. إذا كنت تعتمد على عملية التحقّق من سلامة Docker، يمكنك تغيير الإعدادات باتّباع تعليمات Docker.
  • إذا كان خادم المعاينة وخادم وضع العلامات على المصدر نفسه، استضِف خادم المعاينة على مسار مختلف عن خادم وضع العلامات. حدِّد PREVIEW_SERVER_URL بما في ذلك المسار.
  • يجب أن تحتوي الخوادم الموفَّرة على وحدة معالجة مركزية افتراضية واحدة كحدّ أقصى. لا يتم استخدام وحدات المعالجة الافتراضية الإضافية وتؤثر سلبًا في التوسيع التلقائي.

التحقّق من الصحة

ضبط عنوان URL لحاوية الخادم

في أداة "إدارة العلامات من Google"، انتقِل إلى حاوية الخادم. ضمن المشرف > إعدادات الحاوية، ضَع عنوان URL لخادم وضع العلامات في حقل عنوان URL لحاوية الخادم وانقر على حفظ.

التحقّق من خلال وضع المعاينة

في مساحة العمل بحسابك على أداة "إدارة العلامات من Google"، عاين الحاوية من خلال النقر على معاينة وتأكَّد من تحميل صفحة المعاينة. في علامة تبويب أخرى في المتصفّح، انتقِل إلى أي مسار على عنوان URL لحاوية الخادم. إذا كانت صفحة المعاينة تعرض الطلب الذي تم إرساله، يعني ذلك أنّه تم إعداد كل شيء بشكلٍ سليم.

إذا ربطت نطاقات فرعية متعدّدة بخادم وضع علامات واحد وأردت معاينة كل نطاق فرعي، أضِف عناوين URL إضافية لحاوية الخادم ضمن المشرف > إعدادات الحاوية. في حال تقديم عناوين URL متعددة، يجب أن تتطابق جميع مسارات عناوين URL (سلسلة المعلومات التي تلي اسم النطاق). على سبيل المثال، يمكنك المعاينة على example.com/abc وexample2.com/abc، ولكن لا يمكنك المعاينة على example.com/abc وexample2.com/def. في حال إضافة عناوين URL متعددة، سيظهر لك رمز بجانب الزر معاينة يتيح لك اختيار عنوان URL الذي تريد معاينته.

تعديل إصدار خادم وضع العلامات

تحتوي صورة gtm-cloud-image على Node.js والمكتبات اللازمة لعمل خادم وضع العلامات. يتم تحديث صورة Docker بشكل دوري لإصلاح المشاكل الأمنية وإضافة ميزات جديدة. ننصحك على الأقل بتحديث خادم وضع العلامات مع كل إصدار رئيسي (مثل الترقية من الإصدار 1.x.x إلى 2.x.x).

لتعديل صورة Docker، اتّبِع الخطوات التالية:

  1. يمكنك جلب إصدار الصورة الحالي على gcr.io/cloud-tagging-10302018/gtm-cloud-image:stable.
  2. يمكنك نشر الخادم باستخدام الإعدادات نفسها التي استخدمتها في عملية النشر السابقة.
  3. عدِّل خادم المعاينة الفردي وجميع خوادم وضع العلامات في المجموعة.
  4. أوقِف أي خوادم قديمة.

للتأكّد من نجاح عملية التعديل، اتّبِع الخطوات التالية:

  1. في حاوية الخادم، انقر على الزر معاينة لبدء جلسة تصحيح أخطاء جديدة وإرسال طلب في علامة تبويب منفصلة.
  2. في &quot;الملخّص&quot;، اختَر علامة التبويب وحدة التحكّم وتأكَّد من عدم ظهور أي رسائل تطلب منك تعديل خادم وضع العلامات.

قد تعرض "إدارة العلامات من Google" رسائل تطلب منك تعديل خادم وضع العلامات لمدة تصل إلى يوم واحد بعد تعديل الخادم بنجاح. ومع ذلك، ستعرض صفحة المعاينة رسالة حديثة بشأن إصدار خادم وضع العلامات.