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

خدمة مصغّرة لقوس قزح

1. مقدمة

تاريخ آخر تعديل: 06‏/05‏/2021

Microservice Rainbow Rumpus

هل سبق لك أن شاركت في حرب كرات ثلجية حيث تتحرك ورمي كرات الثلج على الآخرين بشكل عفوي؟ إذا لم تكن هذه هي الحال، ننصحك بتجربة هذه الميزة في المستقبل. ولكن الآن، بدلاً من المخاطرة بالتعرض للضرب، يمكنك إنشاء خدمة صغيرة يمكن الوصول إليها من خلال الشبكة (خدمة صغيرة) ستشارك في معركة ملحمية ضد الخدمات الصغيرة الأخرى، ورميها بقوس قزح بدلاً من كرات الثلج.

قد تتساءل عن... ولكن كيف "ترمي" خدمة صغيرة قوس قزح على الخدمات الصغيرة الأخرى؟ يمكن أن تتلقّى الخدمة المصغرة طلبات الشبكة (عادةً عبر بروتوكول HTTP) وتُرسِل الردود. هناك "مدير حلبة" سيرسل إلى الخدمة المصغرة الحالة الحالية للحلبة، ثم ستستجيب الخدمة المصغرة بطلب يحدّد الإجراء الذي يجب اتّخاذه.

بالطبع، الهدف هو الفوز، ولكن خلال هذه الرحلة، ستتعرّف على كيفية إنشاء الخدمات المصغرة ونشرها على Google Cloud.

آلية العمل

ستنشئ خدمة صغيرة باستخدام أي تكنولوجيا تريدها (أو يمكنك الاختيار من بين Go أو Java أو Kotlin أو Scala أو NodeJS أو Python starters)، ثم نشر الخدمة الصغيرة على Google Cloud. بعد نشر الخدمة، يُرجى إبلاغنا بعنوان URL للخدمة الصغيرة، وسنضيفها بعد ذلك إلى الساحة.

تحتوي الساحة على جميع اللاعبين في معركة معيّنة. سيكون لـ Rainbow Rumpus حلبات خاصة به. يمثّل كل لاعب خدمة صغيرة تتحرك وترمي قوس قزح على اللاعبين الآخرين.

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

في ما يلي شكل الساحة في الإصدار السابق:

مثال على ساحة المعركة الأولى

النزاعات المتكرّرة

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

مشاهدة المعركة

لمعرفة مستوى أداء الخدمة المصغرة في المعركة، يمكنك الاطّلاع على الساحة المباشرة.

Battle API

للعمل مع مدير الساحة، يجب أن تنفِّذ الخدمة المصغرة واجهة برمجة تطبيقات معيّنة للمشاركة في الساحة. سيرسل مدير الساحة الحالة الحالية للساحة في طلب HTTP POST إلى عنوان URL الذي تقدّمه إلينا، باستخدام بنية JSON التالية:

{
  "_links": {
    "self": {
      "href": "https://YOUR_SERVICE_URL"
    }
  },
  "arena": {
    "dims": [4,3], // width, height
    "state": {
      "https://A_PLAYERS_URL": {
        "x": 0, // zero-based x position, where 0 = left
        "y": 0, // zero-based y position, where 0 = top
        "direction": "N", // N = North, W = West, S = South, E = East
        "wasHit": false,
        "score": 0
      }
      ... // also you and the other players
    }
  }
}

يجب أن يكون رمز حالة استجابة HTTP هو 200 (OK) مع نص استجابة يتضمّن الخطوة التالية، ويتم ترميزه كحرف واحد كبير من أيّ مما يلي:

F <- move Forward
R <- turn Right
L <- turn Left
T <- Throw

هذا كل ما عليك فعله. لنطّلِع على كيفية نشر خدمة صغيرة على Cloud Run، وهي خدمة من Google Cloud لتشغيل الخدمات الصغيرة والتطبيقات الأخرى.

2. تسجيل الدخول إلى Google Cloud

لتتمكّن من نشر الخدمة المصغرة على Cloud Run، عليك تسجيل الدخول إلى Google Cloud. سنضيف رصيدًا إلى حسابك ولن تحتاج إلى إدخال بطاقة ائتمان. يكون استخدام حساب شخصي (مثل gmail.com) بدلاً من حساب GSuite أقلّ مشكلة في العادة، لأنّ مشرفي GSuite يمنعون أحيانًا المستخدمين من استخدام ميزات معيّنة في Google Cloud. من المفترض أيضًا أن تعمل وحدة تحكّم الويب التي سنستخدمها بشكلٍ جيد مع Chrome أو Firefox، ولكن قد تواجه مشاكل في Safari.

3- نشر الخدمة المصغرة

يمكنك إنشاء الخدمة الصغيرة باستخدام أي تكنولوجيا ونشرها في أي مكان ما دامت متاحة للجميع ومتوافقة مع Battle API. لتسهيل الأمور، سنساعدك على البدء من خدمة نموذجية ونشرها على Cloud Run.

اختيار عيّنة للبدء

هناك العديد من نماذج الخدمات المصغرة التي يمكنك البدء بها:

‫Kotlin وSpring Boot	المصدر
‫Kotlin وMicronaut	المصدر
‫Kotlin وQuarkus	المصدر
Java وSpring Boot	المصدر
Java وQuarkus	المصدر
البدء	المصدر
Node.js وExpress	المصدر
Python وFlask	المصدر

بعد تحديد العيّنة التي تريد البدء بها، انقر على الزر "النشر على Cloud Run" أعلاه. سيؤدي ذلك إلى تشغيل Cloud Shell (وحدة تحكّم مستندة إلى الويب لآلة افتراضية في السحابة الإلكترونية) حيث سيتم استنساخ المصدر، ثم إنشاؤه في حزمة قابلة للنشر (صورة حاوية Docker)، والتي يتم تحميلها بعد ذلك إلى Google Container Registry، ثم نشرها على Cloud Run.

حدِّد منطقة us-central1 عندما يُطلب منك ذلك.

تعرض لقطة الشاشة أدناه ناتج Cloud Shell لإنشاء الخدمات المصغرة ونشرها

التحقّق من عمل الخدمة الصغيرة

في Cloud Shell، يمكنك إرسال طلب إلى الخدمة الصغيرة التي تم نشرها حديثًا، مع استبدال YOUR_SERVICE_URL بعنوان URL لخدمتك (المتوفّر في Cloud Shell بعد السطر "تطبيقك متوفّر الآن هنا"):

curl -d '{
  "_links": {
    "self": {
      "href": "https://foo.com"
    }
  },
  "arena": {
    "dims": [4,3],
    "state": {
      "https://foo.com": {
        "x": 0,
        "y": 0,
        "direction": "N",
        "wasHit": false,
        "score": 0
      }
    }
  }
}' -H "Content-Type: application/json" -X POST -w "\n" \
  https://YOUR_SERVICE_URL

من المفترض أن تظهر لك سلسلة الاستجابة F أو L أو R أو T.

4. طلب إدراج التطبيق في "الساحة"

للانضمام إلى لعبة Rainbow Rumpus، عليك الانضمام إلى ساحة. افتح rainbowrumpus.dev وانقر على "الانضمام" في ساحة حيث تقدّم عنوان URL للخدمة الصغيرة.

5- إجراء التغييرات ونشرها

قبل إجراء تغييرات، عليك إعداد بعض المعلومات في Cloud Shell عن مشروع Google Cloud Platform والعيّنة التي استخدمتها. أولاً، أدخِل مشاريعك على Google Cloud Platform:

gcloud projects list

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

export PROJECT_ID=YOUR_PROJECT_ID

اضبط الآن متغيّر بيئة آخر للعيّنة التي استخدمتها حتى نتمكّن من تحديد اسم الدليل والخدمة الصحيحَين في الأوامر اللاحقة:

# Copy and paste ONLY ONE of these
export SAMPLE=kotlin-micronaut
export SAMPLE=kotlin-quarkus
export SAMPLE=kotlin-springboot
export SAMPLE=java-quarkus
export SAMPLE=java-springboot
export SAMPLE=go
export SAMPLE=nodejs
export SAMPLE=python

يمكنك الآن تعديل مصدر الخدمة المصغرة من داخل Cloud Shell. لفتح المحرِّر المستنِد إلى الويب في Cloud Shell، شغِّل هذا الأمر:

cloudshell edit cloudbowl-microservice-game/samples/$SAMPLE/README.md

ستظهر لك بعد ذلك تعليمات إضافية لإجراء التغييرات.

Cloud Shell مع المحرِّر مع فتح نموذج المشروع

بعد حفظ التغييرات، ابدأ التطبيق في Cloud Shell باستخدام الأمر من ملف README.md، ولكن تأكَّد أولاً من أنّك في دليل العيّنات الصحيح في Cloud Shell:

cd cloudbowl-microservice-game/samples/$SAMPLE

بعد تشغيل التطبيق، افتح علامة تبويب جديدة في Cloud Shell واختبر الخدمة باستخدام curl:

curl -d '{
  "_links": {
    "self": {
      "href": "https://foo.com"
    }
  },
  "arena": {
    "dims": [4,3],
    "state": {
      "https://foo.com": {
        "x": 0,
        "y": 0,
        "direction": "N",
        "wasHit": false,
        "score": 0
      }
    }
  }
}' -H "Content-Type: application/json" -X POST -w "\n" \
  http://localhost:8080

عندما تكون مستعدًا لنشر التغييرات، أنشئ مشروعك في Cloud Shell باستخدام الأمر pack. يستخدم هذا الأمر حِزم الإنشاء لرصد نوع المشروع وتجميعه وإنشاء العنصر القابل للنشر (صورة حاوية Docker).

# Make sure you are in a Cloud Shell tab where you set the PROJECT_ID
# and SAMPLE env vars. Otherwise, set them again.
pack build gcr.io/$PROJECT_ID/$SAMPLE \
  --path ~/cloudbowl-microservice-game/samples/$SAMPLE \
  --builder gcr.io/buildpacks/builder

بعد إنشاء صورة الحاوية، استخدِم الأمر docker (في Cloud Shell) لدفع صورة الحاوية إلى Google Container Registry حتى يتمكّن Cloud Run من الوصول إليها:

docker push gcr.io/$PROJECT_ID/$SAMPLE

يمكنك الآن نشر الإصدار الجديد على Cloud Run:

gcloud run deploy $SAMPLE \
          --project=$PROJECT_ID \
          --platform=managed \
          --region=us-central1 \
          --image=gcr.io/$PROJECT_ID/$SAMPLE \
          --allow-unauthenticated

ستستخدم الساحة الآن الإصدار الجديد.

6- التطوير على الجهاز (اختياري)

يمكنك العمل على مشروعك على الجهاز باستخدام بيئة التطوير المتكاملة الخاصة بك باتّباع الخطوات التالية:

[في Cloud Shell] اضغط على العيّنة:

# Make sure the SAMPLE env var is still set. If not, re-set it.
cd ~/cloudbowl-microservice-game/samples
zip -r cloudbowl-sample.zip $SAMPLE

[في Cloud Shell] نزِّل ملف zip إلى جهازك:

cloudshell download-file cloudbowl-sample.zip

[على جهازك] فك ضغط الملف ثم إجراء التغييرات واختبارها
[على جهازك] ثبِّت gcloud CLI.
[على جهازك] سجِّل الدخول إلى Google Cloud:

gcloud auth login

[على جهازك] اضبط متغيّري البيئة PROJECT_ID وSAMPLE على القيم نفسها في Cloud Shell.
[على جهازك] استخدِم Cloud Build لإنشاء الحاوية (من دليل المشروع الجذر):

gcloud alpha builds submit . \
  --pack=image=gcr.io/$PROJECT_ID/$SAMPLE \
  --project=$PROJECT_ID

[على جهازك] يمكنك نشر الحاوية الجديدة باتّباع الخطوات التالية:

gcloud run deploy $SAMPLE \
  --project=$PROJECT_ID \
  --platform=managed \
  --region=us-central1 \
  --image=gcr.io/$PROJECT_ID/$SAMPLE \
  --allow-unauthenticated

7- التسليم المستمر

إعداد SCM

يمكنك إعداد GitHub لتتمكّن من التعاون مع فريقك في ما يتعلّق بخدمتك الصغيرة:

تسجيل الدخول إلى GitHub
إنشاء مستودع جديد
إذا كنت تعمل على جهازك المحلي، يمكنك استخدام واجهة سطر أوامر git ‏ (CLI) أو تطبيق واجهة المستخدم الرسومية GitHub Desktop (Windows أو Mac). إذا كنت تستخدم Cloud Shell، عليك استخدام واجهة برمجة التطبيقات git. للحصول على رمز الخدمة الصغيرة على GitHub، اتّبِع تعليمات واجهة سطر الأوامر أو GitHub Desktop.

دفع الرمز البرمجي باستخدام واجهة سطر الأوامر git

اتّبِع تعليمات git عبر https باستخدام رمز دخول شخصي.
اختَر نطاق "المستودع".
إعداد git:

git config --global credential.helper \
  'cache --timeout=172800'
git config --global push.default current
git config --global user.email "YOUR@EMAIL"
git config --global user.name "YOUR NAME"

ضبط متغيّرات البيئة للمؤسسة والمستودع على GitHub (https://github.com/ORG/REPO)

export GITHUB_ORG=YOUR_GITHUB_ORG
export GITHUB_REPO=YOUR_GITHUB_REPO

دفع الرمز إلى المستودع الجديد

# Make sure the SAMPLE env var is still set. If not, re-set it.
cd ~/cloudbowl-microservice-game/samples/$SAMPLE
git init
git add .
git commit -m init
git remote add origin https://github.com/$GITHUB_ORG/$GITHUB_REPO.git
git branch -M main

# This will now ask for your GitHub username & password
# for the password use the personal access token
git push -u origin main

بعد إجراء أي تغييرات، يمكنك إرسالها إلى GitHub:

git add .
git status
git diff --staged
git commit -am "my changes"
git push

دفع الرمز البرمجي باستخدام تطبيق GitHub Desktop

نزِّل الرمز البرمجي باستخدام التعليمات الواردة في ورشة العمل السابقة "التطوير على الجهاز فقط".
ثبِّت تطبيق GitHub Desktop وافتحه وسجِّل الدخول.
استنساخ المستودع الذي تم إنشاؤه حديثًا

افتح "مستكشف الملفات" وانسخ مشروعك إلى المستودع الجديد.
تأكيد التغييرات

نشر فرعك الرئيسي على GitHub

إعداد النشر المستمر في Cloud Run

من خلال إعداد "إدارة سلسلة الإمداد" على GitHub، يمكنك الآن إعداد "التسليم المستمر" بحيث يتم إنشاء التغييرات ونشرها تلقائيًا من خلال Cloud Build في كل مرة يتم فيها دفع عمليات إرسال جديدة إلى فرع main. يمكنك أيضًا إضافة عملية الدمج المستمر التي تُجري اختباراتك قبل نشرها، ولكن تم ترك هذه الخطوة كتدريب لك لأنّ العيّنات الجاهزة لا تحتوي على أي اختبارات.

في Cloud Console، انتقِل إلى خدمة Cloud Run.
انقر على الزر "إعداد النشر المستمر".
المصادقة باستخدام GitHub واختيار مستودع الخدمة المصغرة

اختَر مستودع GitHub واضبط الفرع على: ^main$

ضبط نوع الإنشاء لاستخدام حِزم الإنشاء
انقر على "حفظ" لإعداد ميزة "النشر المستمر".

8. إمكانية تتبّع البيانات

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

المقاييس

ابحث عن خدمتك في قائمة خدمات Cloud Run.
انقر على اسم خدمتك للانتقال إلى لوحة بيانات المقاييس الخاصة بها.

انقر على قائمة ⋮ الخاصة بمقياس معيّن، ثمّ اختَر "عرض في "مستكشف المقاييس".
يمكنك الآن تغيير مقاييس الموارد والفلاتر والتجميع والخيارات الأخرى. على سبيل المثال، يمكنك عرض متوسط أوقات استجابة الخدمة لجميع الخدمات:

السجلّات

يتم إرسال مخرجات STDOUT من الخدمات إلى نظام "تسجيلات Google Cloud". يمكنك الوصول إلى عرض سجلّ أساسي من صفحة مشرف خدمة Cloud Run، مثل:

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

التنبيهات

أنشئ عنوان URL لفحص حالة الخدمة.
بالنسبة إلى Spring Boot، ما عليك سوى إضافة التبعية التالية:

org.springframework.boot:spring-boot-starter-actuator

أنشئ src/main/resources/application.properties أو عدِّله وأوقِف فحص مساحة القرص:

management.health.diskspace.enabled=false

أنشئ تنبيهًا بشأن وقت الاستجابة، مع تحديد البروتوكول واسم المضيف والمسار. بالنسبة إلى Spring Boot، يكون المسار على النحو التالي: /actuator/health
اختبار التنبيه

إنشاء التنبيه

9. تهانينا

مبروك، لقد نجحت في إنشاء خدمة صغيرة ونشرها يمكنها منافسة الخدمات الصغيرة الأخرى. أتمنى لك التوفيق.

مستندات مرجعية

مستندات Cloud Run