استخدام المراجعات في وظائف Cloud Run لتقسيم الزيارات والعمليات الطرحية التدريجية وإلغاء عمليات الطرح

1. مقدمة

نظرة عامة

تتيح لك دوال Cloud Run تحديد المراجعات التي يجب أن تتلقّى الزيارات وتحديد النِسب المئوية للزيارات التي تتلقّاها المراجعة. تتيح لك المراجعات العودة إلى الحالة السابقة لمراجعة سابقة، وطرح مراجعة تدريجيًا، وتقسيم عدد الزيارات بين مراجعات متعدّدة.

توضّح لك هذه السلسلة من الدروس التدريبية كيفية استخدام المراجعات لإدارة عدد الزيارات إلى دوال Cloud Run. يمكنك الاطّلاع على مزيد من المعلومات حول المراجعات في مستندات Cloud Run.

ما ستتعلمه

كيفية تقسيم عدد الزيارات بين إصدارَين أو أكثر من دالة Cloud Run
كيفية طرح مراجعة جديدة تدريجيًا
كيفية العودة إلى نسخة سابقة

2. الإعداد والمتطلبات

المتطلبات الأساسية

يجب أن تكون مسجّلاً الدخول إلى Cloud Console.
سبق لك نشر دالة Cloud Run. على سبيل المثال، يمكنك اتّباع خطوات نشر دالة Cloud Run للبدء.

تفعيل Cloud Shell

من Cloud Console، انقر على تفعيل Cloud Shell .

إذا كانت هذه هي المرة الأولى التي تبدأ فيها Cloud Shell، ستظهر لك شاشة وسيطة توضّح ماهية هذه الخدمة. إذا ظهرت لك شاشة وسيطة، انقر على متابعة.

يستغرق توفير Cloud Shell والاتصال به بضع لحظات فقط.

يتم تحميل هذا الجهاز الافتراضي بجميع أدوات التطوير اللازمة. توفّر هذه الخدمة دليلًا رئيسيًا دائمًا بسعة 5 غيغابايت وتعمل في Google Cloud، ما يؤدي إلى تحسين أداء الشبكة والمصادقة بشكل كبير. يمكن إنجاز معظم عملك في هذا الدرس التطبيقي حول الترميز، إن لم يكن كله، باستخدام متصفح.

بعد الاتصال بـ Cloud Shell، من المفترض أن يظهر لك أنّه تم إثبات هويتك وأنّه تم ضبط المشروع على رقم تعريف مشروعك.

نفِّذ الأمر التالي في Cloud Shell للتأكّد من إكمال عملية المصادقة:

gcloud auth list

ناتج الأمر

 Credentialed Accounts
ACTIVE  ACCOUNT
*       <my_account>@<my_domain.com>

To set the active account, run:
    $ gcloud config set account `ACCOUNT`

نفِّذ الأمر التالي في Cloud Shell للتأكّد من أنّ أمر gcloud يعرف مشروعك:

gcloud config list project

ناتج الأمر

[core]
project = <PROJECT_ID>

إذا لم يكن كذلك، يمكنك تعيينه من خلال هذا الأمر:

gcloud config set project <PROJECT_ID>

ناتج الأمر

Updated property [core/project].

3- تقسيم عدد الزيارات

يوضّح لك هذا النموذج كيفية إنشاء دالة تقرأ متغيّر بيئة لون وتستجيب باسم المراجعة باستخدام لون الخلفية هذا.

على الرغم من أنّ هذا الدرس التطبيقي العملي يستخدم node.js، يمكنك استخدام أي وقت تشغيل.

ضبط متغيرات البيئة

يمكنك ضبط متغيّرات البيئة التي سيتم استخدامها في جميع مراحل هذا الدرس التطبيقي حول الترميز.

REGION=<YOUR_REGION>
PROJECT_ID=<YOUR-PROJECT-ID>
BG_COLOR=darkseagreen

إنشاء الدالة

أولاً، أنشئ دليلاً لرمز المصدر وانتقِل إلى هذا الدليل.

mkdir revisions-gcf-codelab && cd $_

بعد ذلك، أنشِئ ملف package.json يتضمّن المحتوى التالي:

{
    "dependencies": {
        "@google-cloud/functions-framework": "^3.0.0"
    }
}

بعد ذلك، أنشئ ملف مصدر index.js يتضمّن المحتوى التالي:

const functions = require('@google-cloud/functions-framework');

const BG_COLOR = process.env.BG_COLOR;
const K_REVISION = process.env.K_REVISION;

functions.http('helloWorld', (req, res) => {
    res.writeHead(200, { 'Content-Type': 'text/html' });
    res.end('<html><body style="background-color:' + BG_COLOR + ';"' + '><div><p>' + 'Hello from ' + K_REVISION + ' using color ' + BG_COLOR + '</p></div></body>' + '</html>');
});

لنشر إحدى دوال Cloud Run مباشرةً على Cloud Run، شغِّل الأمر التالي:

gcloud beta run deploy traffic-splitting-gcf \
      --source . \
      --function helloWorld \
      --region $REGION \
      --no-allow-unauthenticated \
      --set-env-vars BG_COLOR=$BG_COLOR

إذا كنت تفضّل النشر كـ "الجيل الثاني من Cloud Functions"، استخدِم الأمر التالي:

gcloud functions deploy traffic-splitting-gcf \
  --gen2 \
  --runtime=nodejs20 \
  --region=$REGION \
  --source=. \
  --entry-point=helloWorld \
  --trigger-http \
  --no-allow-unauthenticated \
  --set-env-vars BG_COLOR=$BG_COLOR

لاختبار الدالة، يمكنك إما استخدام curl لنقطة النهاية الحالية لمعرفة لون darkseagreen في رمز HTML، أو استخدام المتصفّح للوصول إلى نقطة النهاية مباشرةً لمعرفة لون الخلفية.

SERVICE_URL=$(gcloud run services describe traffic-splitting-gcf --platform managed --region $REGION --format 'value(status.url)')

curl -H "Authorization: bearer $(gcloud auth print-identity-token)" -X GET $SERVICE_URL

الآن، يمكنك نشر مراجعة ثانية بلون خلفية أسمر.

لنشر إحدى دوال Cloud Run مباشرةً على Cloud Run، شغِّل الأمر التالي:

# update the env var
BG_COLOR=tan

gcloud beta run deploy traffic-splitting-gcf \
      --source . \
      --function helloWorld \
      --region $REGION \
      --no-allow-unauthenticated \
      --update-env-vars BG_COLOR=$BG_COLOR

إذا كنت تفضّل النشر كـ "الجيل الثاني من Cloud Functions"، استخدِم الأمر التالي:

# update the env var
BG_COLOR=tan

gcloud functions deploy traffic-splitting-gcf \
  --gen2 \
  --runtime nodejs20 \
  --entry-point helloHttp \
  --source . \
  --region $REGION \
  --trigger-http \
  --no-allow-unauthenticated \
  --update-env-vars BG_COLOR=$BG_COLOR

الآن، عندما تستخدم curl مع نقطة النهاية، سيظهر لك لون الخلفية الأسمر.

curl -H "Authorization: bearer $(gcloud auth print-identity-token)" -X GET $SERVICE_URL

تقسيم عدد الزيارات مناصفةً

لتقسيم عدد الزيارات بين المراجعات باللون الأخضر الداكن والبني، عليك العثور على أرقام تعريف المراجعات لخدمات Cloud Run الأساسية. يمكنك الاطّلاع على أرقام تعريف المراجعات من خلال تنفيذ الأمر التالي:

gcloud run revisions list --service traffic-splitting-gcf \
  --region $REGION --format 'value(REVISION)'

من المفترض أن تظهر لك نتائج مشابهة لما يلي

traffic-splitting-gcf-00003-qoq
traffic-splitting-gcf-00002-zag

يمكنك تقسيم عدد الزيارات بالتساوي بين المراجعتَين من خلال تنفيذ الأمر التالي:

gcloud run services update-traffic traffic-splitting-gcf \
  --region $REGION \
  --to-revisions <REVISION1>=50,<REVISION2>=50

اختبار تقسيم عدد الزيارات

يمكنك اختبار الدالة من خلال الانتقال إلى عنوان URL العام الخاص بها (إما باستخدام curl أو مباشرةً في المتصفّح).

curl -H "Authorization: bearer $(gcloud auth print-identity-token)" $SERVICE_URL

في نصف الوقت، يجب أن ترى المراجعة باللون الأخضر الداكن، وفي النصف الآخر، يجب أن ترى المراجعة باللون الأسمر. سيظهر لك أيضًا اسم المراجعة في الناتج، مثل

<html><body style="background-color:tan;"><div><p>Hello traffic-splitting-gcf-00006-qoq</p></div></body></html>

4. عمليات الطرح التدريجي

في هذا القسم، ستتعرّف على كيفية طرح التغييرات تدريجيًا على مراجعة جديدة في Cloud Functions. يمكنك الاطّلاع على مزيد من المعلومات حول عمليات الطرح التدريجي في المستندات.

ستستخدم الرمز البرمجي نفسه المستخدَم في القسم السابق، ولكن سيتم نشره كدالة Cloud جديدة.

أولاً، اضبط لون الخلفية على beige ونفِّذ الدالة بالاسم gradual-rollouts-gcf.

لنشر إحدى دوال Cloud Run مباشرةً على Cloud Run، شغِّل الأمر التالي:

# update the env var
BG_COLOR=beige

gcloud beta run deploy gradual-rollouts-gcf \
      --source . \
      --function helloWorld \
      --region $REGION \
      --no-allow-unauthenticated \
      --update-env-vars BG_COLOR=$BG_COLOR

إذا كنت تفضّل النشر كـ "الجيل الثاني من Cloud Functions"، استخدِم الأمر التالي:

# update the env var
BG_COLOR=beige

# deploy the function
gcloud functions deploy gradual-rollouts-gcf \
  --gen2 \
  --runtime nodejs20 \
  --entry-point helloHttp \
  --source . \
  --region $REGION \
  --trigger-http \
  --no-allow-unauthenticated \
  --update-env-vars BG_COLOR=$BG_COLOR

لنفترض الآن أنّنا نريد طرح مراجعة جديدة تدريجيًا بلون خلفية الخزامى.

أولاً، لنضبط المراجعة الحالية باللون البيج لتلقّي% 100 من عدد الزيارات. سيضمن ذلك عدم تلقّي عمليات نشر دوال Cloud المستقبلية أي زيارات. تضبط Cloud Functions تلقائيًا نسبة% 100 من الزيارات على المراجعة التي تتضمّن العلامة latest. من خلال تحديد أنّ هذه المراجعة الحالية باللون البيج يجب أن تتلقّى كل الزيارات يدويًا، لن تتلقّى المراجعة التي تحمل العلامة latest% 100 من الزيارات بعد ذلك. يُرجى الاطّلاع على المستندات.

# get the revision name

BEIGE_REVISION=$(gcloud run revisions list --service gradual-rollouts-gcf \
  --region $REGION --format 'value(REVISION)')

# now set 100% traffic to that revision

gcloud run services update-traffic gradual-rollouts-gcf --to-revisions=$BEIGE_REVISION=100 --region $REGION

ستظهر لك نتيجة مشابهة لما يلي: Traffic: 100% gradual-rollouts-gcf2-00001-yox

يمكنك الآن نشر نسخة جديدة لن تتلقّى أي زيارات. بدلاً من إجراء أي تغييرات على الرمز، يمكنك تعديل متغيّر البيئة BG_COLOR لهذه المراجعة.

لنشر إحدى دوال Cloud Run مباشرةً على Cloud Run، شغِّل الأمر التالي:

# update color

BG_COLOR=lavender

# deploy the function that will not receive any traffic
gcloud beta run deploy gradual-rollouts-gcf \
      --source . \
      --function helloWorld \
      --region $REGION \
      --no-allow-unauthenticated \
      --update-env-vars BG_COLOR=$BG_COLOR

إذا كنت تفضّل النشر كـ "الجيل الثاني من Cloud Functions"، استخدِم الأمر التالي:

# update color

BG_COLOR=lavender

# deploy the function that will not receive any traffic
gcloud functions deploy gradual-rollouts-gcf \
  --gen2 \
  --runtime nodejs20 \
  --entry-point helloHttp \
  --source . \
  --region $REGION \
  --trigger-http \
  --no-allow-unauthenticated \
  --update-env-vars BG_COLOR=$BG_COLOR \
  --tag $BG_COLOR

الآن، عدِّل متغيّر البيئة SERVICE_URL لاستخدام الدالة gradual-rollouts-gcf

SERVICE_URL=$(gcloud run services describe gradual-rollouts-gcf --platform managed --region $REGION --format 'value(status.url)')

والآن عندما تستخدم curl للوصول إلى الخدمة

curl -H "Authorization: bearer $(gcloud auth print-identity-token)" -X GET $SERVICE_URL

سيظهر لك اللون البيج، على الرغم من أنّ اللون اللافندر هو آخر مراجعة تم نشرها.

<html><body style="background-color:beige;"><div><p>Hello from gradual-rollouts-gcf-24jan16-staging-2-00001-kop using color beige</p></div></body></html>

اختبار مراجعة تعرض 0% من عدد الزيارات

لنفترض أنّك تحقّقت من أنّ المراجعة تم نشرها بنجاح وأنّها تعرض% 0 من الزيارات. على الرغم من اجتيازها لعمليات التحقّق من الصحة، لا يزال عليك التأكّد من أنّ هذه المراجعة تستخدم لون الخلفية الخزامي.

لاختبار مراجعة Lavender، يمكنك تطبيق علامة على هذه المراجعة. تتيح لك عملية وضع العلامات اختبار المراجعة الجديدة مباشرةً على عنوان URL محدّد، بدون عرض أي زيارات.

أولاً، احصل على عنوان URL الخاص بالصورة لهذا الإصدار.

IMAGE_URL=$(gcloud run services describe gradual-rollouts-gcf --region $REGION --format 'value(IMAGE)')

والآن، ضع علامة على تلك الصورة باستخدام اللون المرتبط بها.

gcloud run deploy gradual-rollouts-gcf --image $IMAGE_URL --no-traffic --tag $BG_COLOR --region $REGION --no-allow-unauthenticated

ستظهر لك نتيجة مشابهة لما يلي:

The revision can be reached directly at https://lavender---gradual-rollouts-gcf-k6msmyp47q-lz.a.run.app

يمكنك الآن استرداد هذه المراجعة مباشرةً

curl -H "Authorization: bearer $(gcloud auth print-identity-token)" -X GET <DIRECT_REVISION_URL>

وستظهر لك النتائج باللون الخزامي:

<html><body style="background-color:lavender;"><div><p>Hello from gradual-rollouts-gcf-24jan16-00003-xik using color lavender</p></div></body></html>

زيادة عدد الزيارات تدريجيًا

يمكنك الآن البدء في إرسال الزيارات إلى نسخة Lavender. يوضّح المثال أدناه كيفية إرسال% 1 من حركة البيانات إلى lavender.

gcloud run services update-traffic gradual-rollouts-gcf --region $REGION --to-tags lavender=1

لإرسال% 50 من الزيارات إلى اللون الخزامى، يمكنك استخدام الأمر نفسه، ولكن حدِّد% 50 بدلاً من ذلك.

gcloud run services update-traffic gradual-rollouts-gcf --region $REGION --to-tags lavender=50

من المفترض أن تظهر لك قائمة بعدد الزيارات التي تتلقّاها كل مراجعة.

Traffic:
  50% gradual-rollouts-gcf-00001-hos
  50% gradual-rollouts-gcf-00004-mum
        lavender: https://lavender---gradual-rollouts-gcf-k6msmyp47q-uc.a.run.app

عندما تكون مستعدًا لطرح اللون الخزامي بالكامل، يمكنك ضبط اللون الخزامي على% 100 لاستبدال اللون البيج.

gcloud run services update-traffic gradual-rollouts-gcf --region $REGION --to-tags lavender=100

والآن، عند الانتقال إلى عنوان URL الخاص بخدمة وظيفة gradual-rollouts-gcf أو استخدام الأمر curl،

curl -H "Authorization: bearer $(gcloud auth print-identity-token)" -X GET $SERVICE_URL

سيظهر لك اللون الخزامي فقط.

<html><body style="background-color:lavender;"><div><p>Hello gradual-rollouts-gcf-00004-mum</p></div></body></html>

5- عمليات العودة إلى الحالة السابقة

لنفترض أنّك تلقّيت ملاحظات مبكرة بشأن تجربة المستخدم تشير إلى أنّ العملاء يفضّلون اللون البيج على اللون الخزامى، وأنّك بحاجة إلى العودة إلى الحالة السابقة إلى اللون البيج.

يمكنك العودة إلى النسخة السابقة (البيج) من خلال تنفيذ هذا الأمر.

gcloud run services update-traffic gradual-rollouts-gcf --region $REGION --to-revisions $BEIGE_REVISION=100

والآن، عندما تستخدم curl أو تزور نقطة نهاية عنوان URL للدالة،

curl -H "Authorization: bearer $(gcloud auth print-identity-token)" -X GET $SERVICE_URL

سيظهر لك اللون البيج.

<html><body style="background-color:beige;"><div><p>Hello gradual-rollouts-gcf-00001-hos</p></div></body></html>

يمكنك الاطّلاع على مزيد من المعلومات حول عمليات التراجع في المستندات.

6. تهانينا!

تهانينا على إكمال هذا الدرس العملي.

ننصحك بمراجعة المستندات حول عمليات الطرح والتراجع ونقل الزيارات.

المواضيع التي تناولناها

كيفية تقسيم عدد الزيارات بين إصدارَين أو أكثر من دالة Cloud Run
كيفية طرح مراجعة جديدة تدريجيًا
كيفية العودة إلى نسخة سابقة

7. تَنظيم

لتجنُّب الرسوم غير المقصودة (على سبيل المثال، إذا تم استدعاء وظيفة Cloud Run هذه مرات أكثر من عدد مرات استدعاء Cloud Function المخصّصة لك شهريًا في الطبقة المجانية)، يمكنك إما حذف وظيفة Cloud Run أو حذف المشروع الذي أنشأته في الخطوة 2.

لحذف دالة Cloud Run تم تفعيلها إلى Cloud Run، انتقِل إلى Cloud Run في Cloud Console على https://console.cloud.google.com/functions/ واحذف الوظائف التي أنشأتها في هذا الدرس التطبيقي حول الترميز.

لحذف دوال Cloud Run التي تم نشرها كدوال من الجيل الثاني، انتقِل إلى Cloud Functions في Cloud Console على https://console.cloud.google.com/functions/ واحذف الدوال التي أنشأتها في هذا الدرس العملي.

إذا اخترت حذف المشروع بأكمله، يمكنك الانتقال إلى https://console.cloud.google.com/cloud-resource-manager، واختيار المشروع الذي أنشأته في الخطوة 2، ثم النقر على "حذف". إذا حذفت المشروع، عليك تغيير المشاريع في Cloud SDK. يمكنك الاطّلاع على قائمة بجميع المشاريع المتاحة من خلال تنفيذ gcloud projects list.