تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

استخدام المراجعات في وظائف 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

إنشاء الدالة

أولاً، أنشئ دليلاً لرمز المصدر وانتقِل إليه باستخدام الأمر cd.

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 -H "Authorization: bearer $(gcloud auth print-identity-token)" -X GET $SERVICE_URL

تقسيم عدد الزيارات بنسبة 50/50

لتقسيم عدد الزيارات بين الإصدارَين الأخضر الداكن والبني، عليك العثور على أرقام تعريف الإصدارات لخدمات 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 Function. يمكنك الاطّلاع على مزيد من المعلومات حول عمليات الطرح التدريجي في المستندات.

ستستخدم الرمز البرمجي نفسه المستخدَم في القسم السابق، ولكنك ستنشره كوظيفة جديدة في 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 -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% من الزيارات. على الرغم من أنّه اجتاز عمليات التحقّق من الصحة، لا يزال عليك التأكّد من أنّ هذه النسخة تستخدم لون الخلفية البنفسجي.

لاختبار المراجعة باللون البنفسجي، يمكنك تطبيق علامة على هذه المراجعة. تتيح لك ميزة وضع العلامات اختبار النسخة الجديدة مباشرةً على عنوان 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>

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

يمكنك الآن بدء إرسال الزيارات إلى النسخة البنفسجية. يوضّح المثال أدناه كيفية إرسال% 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- تهانينا!

تهانينا على إكمال دورة codelab.

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

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

كيفية تقسيم الزيارات بين نسختَين أو أكثر من دالة 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 ثم اختيار "حذف". في حال حذف المشروع، عليك تغيير المشاريع في حزمة تطوير البرامج (SDK) من Cloud. يمكنك عرض قائمة بجميع المشاريع المتاحة من خلال تشغيل gcloud projects list.