تنفيذ قصص مستخدمي JIRA باستخدام الذكاء الاصطناعي التوليدي

1. نظرة عامة

في هذا الدرس التطبيقي، ستنشئ حلاً لأتمتة عملية تطوير قصص المستخدمين في JIRA باستخدام الذكاء الاصطناعي التوليدي.

ما ستتعلمه

يتضمّن المختبر عدة أجزاء رئيسية:

نشر تطبيق Cloud Run لدمجه مع Gemini APIs
إنشاء تطبيق Atlassian Forge ونشره في JIRA
استخدام وكلاء LangChain ReAct لأتمتة مهام GitLab

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

يفترض هذا التمرين العملي معرفة بيئتَي Cloud Console وCloud Shell.

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

إعداد مشروع على السحابة الإلكترونية

سجِّل الدخول إلى Google Cloud Console وأنشِئ مشروعًا جديدًا أو أعِد استخدام مشروع حالي. إذا لم يكن لديك حساب على Gmail أو Google Workspace، عليك إنشاء حساب.

اسم المشروع هو الاسم المعروض للمشاركين في هذا المشروع. وهي سلسلة أحرف لا تستخدمها Google APIs. ويمكنك تعديلها في أي وقت.
رقم تعريف المشروع هو معرّف فريد في جميع مشاريع Google Cloud ولا يمكن تغييره بعد ضبطه. تنشئ Cloud Console تلقائيًا سلسلة فريدة، ولا يهمّك عادةً ما هي. في معظم دروس البرمجة، عليك الرجوع إلى رقم تعريف مشروعك (يُشار إليه عادةً باسم PROJECT_ID). إذا لم يعجبك رقم التعريف الذي تم إنشاؤه، يمكنك إنشاء رقم تعريف عشوائي آخر. يمكنك بدلاً من ذلك تجربة اسم من اختيارك ومعرفة ما إذا كان متاحًا. لا يمكن تغيير هذا الخيار بعد هذه الخطوة وسيظل ساريًا طوال مدة المشروع.
للعلم، هناك قيمة ثالثة، وهي رقم المشروع، تستخدمها بعض واجهات برمجة التطبيقات. يمكنك الاطّلاع على مزيد من المعلومات عن كل هذه القيم الثلاث في المستندات.

بعد ذلك، عليك تفعيل الفوترة في Cloud Console لاستخدام موارد/واجهات برمجة تطبيقات Cloud. لن تكلفك تجربة هذا الدرس التطبيقي حول الترميز الكثير، إن وُجدت أي تكلفة على الإطلاق. لإيقاف الموارد وتجنُّب تحمّل تكاليف فوترة تتجاوز هذا البرنامج التعليمي، يمكنك حذف الموارد التي أنشأتها أو حذف المشروع. يمكن لمستخدمي Google Cloud الجدد الاستفادة من برنامج الفترة التجريبية المجانية بقيمة 300 دولار أمريكي.

إعداد البيئة

افتح محادثة Gemini.

أو اكتب "اسأل Gemini" في شريط البحث.

فعِّل واجهة برمجة التطبيقات Gemini for Google Cloud API باتّباع الخطوات التالية:

انقر على "Start chatting" واتّبِع أحد الأسئلة النموذجية أو اكتب طلبك الخاص لتجربته.

إليك بعض الطلبات التي يمكن تجربتها:

اشرح Cloud Run في 5 نقاط رئيسية.
أنا مدير منتج Cloud Run في Google Cloud، وأريد شرح Cloud Run لطالب في 5 نقاط رئيسية قصيرة.
أنت مدير منتج في Google Cloud Run، اشرح خدمة Cloud Run لمطوّر معتمد في Kubernetes في 5 نقاط رئيسية قصيرة.
أنت مدير منتج Google Cloud Run، اشرح متى يمكنك استخدام Cloud Run بدلاً من GKE لمطوّر أقدم في 5 نقاط رئيسية قصيرة.

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

كيف يستخدم "Gemini في Google Cloud" بياناتك؟

التزام Google بالخصوصية

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

البيانات التي ترسلها وتتلقّاها

تُعرف الأسئلة التي تطرحها على Gemini، بما في ذلك أي معلومات أو رموز برمجية ترسلها إلى Gemini لتحليلها أو إكمالها، باسم الطلبات. تُعرف الإجابات أو عمليات إكمال الرمز البرمجي التي تتلقّاها من Gemini باسم الردود. لا يستخدم Gemini طلباتك أو ردوده كبيانات لتدريب نماذجه.

تشفير الطلبات

عند إرسال طلبات إلى Gemini، يتم تشفير بياناتك أثناء نقلها كمدخلات إلى النموذج الأساسي في Gemini.

بيانات البرنامج من إنشاء Gemini

يتم تدريب Gemini على رمز Google Cloud للطرف الأول بالإضافة إلى رمز الطرف الثالث المحدّد. تتحمّل أنت مسؤولية أمان الرمز واختباره وفعاليته، بما في ذلك أي عملية إكمال أو إنشاء أو تحليل للرمز يقدّمه لك Gemini.

مزيد من المعلومات حول طريقة Google في معالجة طلباتك

3- خيارات لاختبار الطلبات

تتوفّر لك عدة خيارات لاختبار الطلبات.

Vertex AI Studio

‫Vertex AI Studio هو جزء من منصة Vertex AI من Google Cloud، وهو مصمَّم خصيصًا لتبسيط عملية تطوير نماذج الذكاء الاصطناعي التوليدي وتسريعها واستخدامها.

Google AI Studio

‫Google AI Studio هي أداة مستندة إلى الويب تتيح إنشاء نماذج أولية وتجربة هندسة الطلبات وGemini API.

تطبيق Gemini للويب (gemini.google.com)

تطبيق Google Gemini للويب (gemini.google.com) هو أداة مستندة إلى الويب مصمّمة لمساعدتك في استكشاف إمكانات نماذج الذكاء الاصطناعي Gemini من Google والاستفادة منها.

تطبيق Google Gemini للأجهزة الجوّالة على Android وتطبيق Google على iOS

4. مراجعة الطلب

إنشاء حساب خدمة

ارجع إلى Google Cloud Console وفعِّل Cloud Shell من خلال النقر على الرمز على يسار شريط البحث.

في الوحدة الطرفية التي تم فتحها، شغِّل الأوامر التالية لإنشاء حساب خدمة ومفاتيح جديدة.

ستستخدم حساب الخدمة هذا لإجراء طلبات البيانات من واجهة برمجة التطبيقات إلى Vertex AI Gemini API من تطبيق Cloud Run.

اضبط تفاصيل المشروع باستخدام تفاصيل مشروع Qwiklabs.

مثلاً: qwiklabs-gcp-00-2c10937585bb

gcloud config set project YOUR_QWIKLABS_PROJECT_ID

أنشئ حساب خدمة.

PROJECT_ID=$(gcloud config get-value project)
SERVICE_ACCOUNT_NAME='vertex-client'
DISPLAY_NAME='Vertex Client'

gcloud iam service-accounts create $SERVICE_ACCOUNT_NAME --project $PROJECT_ID --display-name "$DISPLAY_NAME"

منح الأدوار

gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com" --role="roles/aiplatform.admin"

gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com" --role="roles/aiplatform.user"

gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com" --role="roles/cloudbuild.builds.editor"

gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com" --role="roles/artifactregistry.admin"

gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com" --role="roles/storage.admin"

gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com" --role="roles/run.admin"

gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com" --role="roles/secretmanager.secretAccessor"

إذا طُلب منك منح الإذن، انقر على "منح الإذن" للمتابعة.

فعِّل الخدمات المطلوبة لاستخدام واجهات Vertex AI API وميزة "محادثة Gemini".

gcloud services enable \
    generativelanguage.googleapis.com \
    aiplatform.googleapis.com \
    cloudaicompanion.googleapis.com \
    run.googleapis.com \
    cloudresourcemanager.googleapis.com

فعِّل الخدمات المطلوبة لاستخدام واجهات Vertex AI API وميزة "محادثة Gemini".

gcloud services enable \
    artifactregistry.googleapis.com \
    cloudbuild.googleapis.com \
    runapps.googleapis.com \
    workstations.googleapis.com \
    servicemanagement.googleapis.com \
    secretmanager.googleapis.com \
    containerscanning.googleapis.com

استنساخ مستودع GitHub

استنسِخ مستودع GitHub.

git clone https://github.com/GoogleCloudPlatform/genai-for-developers.git

فتح "محرّر Cloud Shell"

باستخدام عنصر القائمة "File / Open Folder"، افتح "genai-for-developers".

افتح الملف "devai-api/app/routes.py"، ثم انقر بزر الماوس الأيمن في أي مكان في الملف واختَر "Gemini > Explain this"" من قائمة السياق.

راجِع شرح Gemini للملف المحدّد.

5- إعداد مستودع GitLab ومجموعة الأدوات

في هذا الدرس العملي، ستستخدم GitLabToolkit لأتمتة عملية إنشاء طلبات الدمج في GitLab.

نظرة عامة على مجموعات أدوات LangChain

مجموعات أدوات LangChain هي مجموعات من الأدوات المصمَّمة لتبسيط عملية تطوير التطبيقات باستخدام LangChain وتحسينها. توفّر هذه الأدوات وظائف متنوعة حسب مجموعة الأدوات المحدّدة، ولكن بشكل عام، تساعد في ما يلي:

الربط بمصادر البيانات الخارجية: يمكنك الوصول إلى المعلومات من واجهات برمجة التطبيقات وقواعد البيانات والمصادر الخارجية الأخرى ودمجها في تطبيقات LangChain.
تقنيات الطلبات المتقدّمة: استخدِم طلبات معدّة مسبقًا أو أنشئ طلبات مخصّصة لتحسين التفاعلات مع النماذج اللغوية.
إنشاء السلاسل وإدارتها: يمكنك إنشاء سلاسل معقّدة بسهولة وإدارتها بكفاءة.
التقييم والرصد: يمكنك تحليل أداء تطبيقاتك وسلاسل LangChain.

تشمل بعض حِزم أدوات LangChain الشائعة ما يلي:

مجموعات أدوات Agent Executor: أدوات لتطوير وكلاء يمكنهم التفاعل مع العالم الحقيقي من خلال إجراءات مثل تصفّح الويب أو تنفيذ الرموز البرمجية.
مجموعة أدوات هندسة الطلبات: مجموعة من المراجع لصياغة طلبات فعّالة

نظرة عامة على "مجموعة أدوات GitLab"

تحتوي مجموعة أدوات Gitlab على أدوات تتيح لوكيل نموذج لغوي كبير التفاعل مع مستودع Gitlab. الأداة هي برنامج تضمين لمكتبة python-gitlab.

يمكن لمجموعة أدوات GitLab تنفيذ المهام التالية:

إنشاء ملف: لإنشاء ملف جديد في المستودع
قراءة الملف: لقراءة ملف من المستودع
تعديل الملف: لتعديل ملف في المستودع
إنشاء طلب سحب: ينشئ طلب سحب من فرع عمل البوت إلى الفرع الأساسي.
Get Issues: لاسترداد المشاكل من المستودع
Get Issue: لاسترداد تفاصيل حول مشكلة معيّنة.
التعليق على مشكلة: ينشر تعليقًا على مشكلة معيّنة.
حذف ملف: لحذف ملف من المستودع

إعداد مشروع GitLab

افتح GitLab، وأنشئ مشروعًا جديدًا، واضبط رمز الدخول إلى المشروع ضمن "Settings / Access Tokens".

استخدِم التفاصيل التالية:

اسم الرمز المميز: devai-api-qwiklabs
الدور: Maintainer
اختَر النطاقات: api

انسخ قيمة رمز الدخول والصِقها في ملف مؤقت على الكمبيوتر المحمول، وسيتم استخدامها في الخطوات التالية.

6. الاستعداد لنشر التطبيق على Cloud Run

ارجع إلى "محرّر Cloud Shell" واستخدِم وحدة طرفية حالية أو افتح وحدة طرفية جديدة.

اضبط تفاصيل المشروع باستخدام تفاصيل مشروع Qwiklabs.

مثلاً: qwiklabs-gcp-00-2c10937585bb

gcloud config set project YOUR-QWIKLABS-PROJECT-ID

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

export PROJECT_ID=$(gcloud config get-value project)
export LOCATION=us-central1
export REPO_NAME=devai-api
export SERVICE_NAME=devai-api

اضبط متغيّرات البيئة المطلوبة لعملية دمج GitLab.

export GITLAB_PERSONAL_ACCESS_TOKEN=gitlab-token

لتجنُّب الكشف عن معلومات حساسة في Terminal، يُنصح باستخدام read -s GITLAB_PERSONAL_ACCESS_TOKEN، فهذه طريقة آمنة لضبط متغيرات البيئة بدون ظهور القيمة في سجلّ الأوامر في وحدة التحكّم. بعد تشغيله، عليك لصق القيمة والضغط على مفتاح الإدخال. عليك أيضًا تصدير متغيّر البيئة: export GITLAB_PERSONAL_ACCESS_TOKEN

يتطلّب هذا الأمر تعديل معرّف مستخدم GitLab واسم المستودع.

مثلاً: export GITLAB_REPOSITORY="gitrey/qwiklabs-test"

export GITLAB_REPOSITORY="USERID/REPOSITORY"

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

export GITLAB_URL="https://gitlab.com"
export GITLAB_BRANCH="devai"
export GITLAB_BASE_BRANCH="main"

إعدادات تتبُّع نماذج اللغات الكبيرة في LangSmith

يمكنك إعداد الحساب إذا كنت تريد عرض معلومات تتبُّع الوكيل في LangSmith، وإلا نفِّذ الأوامر كما هي.

أنشئ حسابًا على LangSmith وأنشئ مفتاح Service API في قسم "الإعدادات". https://smith.langchain.com/settings

اضبط متغيّرات البيئة المطلوبة لعملية دمج LangSmith.

export LANGCHAIN_TRACING_V2=true
export LANGCHAIN_ENDPOINT="https://api.smith.langchain.com"

export LANGCHAIN_API_KEY=langchain-service-api-key

إعدادات JIRA

لا يتم استخدام هذه القيم في هذا الدرس التطبيقي، لذا لست بحاجة إلى تعديلها لتناسب قيم مشروع JIRA المحدّد قبل تنفيذ الأوامر.

اضبط متغيّرات البيئة المطلوبة لتفعيل خدمة Cloud Run.

export JIRA_API_TOKEN=jira-token
export JIRA_USERNAME="YOUR-EMAIL"
export JIRA_INSTANCE_URL="https://YOUR-JIRA-PROJECT.atlassian.net"
export JIRA_PROJECT_KEY="YOUR-JIRA-PROJECT-KEY"
export JIRA_CLOUD=true

إنشاء مفتاح واجهة برمجة تطبيقات

أنشئ مفتاحًا جديدًا لواجهة برمجة التطبيقات في قسم وحدة تحكّم Cloud / واجهات برمجة التطبيقات والخدمات / بيانات الاعتماد.

سيتم استخدام هذا المفتاح للمصادقة على طلبات JIRA API إلى تطبيق Cloud Run.

بالنسبة إلى بيئة الإنتاج، عليك ضبط قيود التطبيق وواجهة برمجة التطبيقات لمفتاح واجهة برمجة التطبيقات الذي تم إنشاؤه. تحدّ قيود التطبيق من استخدام مفتاح واجهة برمجة التطبيقات في مواقع إلكترونية معيّنة(مثل مثيل JIRA).

اضبط متغيّرات البيئة المطلوبة لتفعيل خدمة Cloud Run.

export DEVAI_API_KEY=your-api-key

إنشاء أسرار في Secret Manager

في هذا المختبر، نتّبع أفضل الممارسات ونستخدم Secret Manager لتخزين قيم رموز الدخول ومفتاح واجهة برمجة التطبيقات ومفتاح LangChain API والإشارة إليها في Cloud Run.

إنشاء الأسرار المطلوبة وتخزينها في Secret Manager

echo -n $DEVAI_API_KEY | \
 gcloud secrets create DEVAI_API_KEY \
 --data-file=-

echo -n $JIRA_API_TOKEN | \
 gcloud secrets create JIRA_API_TOKEN \
 --data-file=-

echo -n $GITLAB_PERSONAL_ACCESS_TOKEN | \
 gcloud secrets create GITLAB_PERSONAL_ACCESS_TOKEN \
 --data-file=-

echo -n $LANGCHAIN_API_KEY | \
 gcloud secrets create LANGCHAIN_API_KEY \
 --data-file=-

7. نشر Devai-API على Cloud Run

تأكَّد من أنّك في المجلد الصحيح.

cd ~/genai-for-developers/devai-api

نشر التطبيق على Cloud Run

gcloud run deploy "$SERVICE_NAME" \
  --source=. \
  --region="$LOCATION" \
  --allow-unauthenticated \
  --service-account vertex-client \
  --set-env-vars PROJECT_ID="$PROJECT_ID" \
  --set-env-vars LOCATION="$LOCATION" \
  --set-env-vars GITLAB_URL="$GITLAB_URL" \
  --set-env-vars GITLAB_REPOSITORY="$GITLAB_REPOSITORY" \
  --set-env-vars GITLAB_BRANCH="$GITLAB_BRANCH" \
  --set-env-vars GITLAB_BASE_BRANCH="$GITLAB_BASE_BRANCH" \
  --set-env-vars JIRA_USERNAME="$JIRA_USERNAME" \
  --set-env-vars JIRA_INSTANCE_URL="$JIRA_INSTANCE_URL" \
  --set-env-vars JIRA_PROJECT_KEY="$JIRA_PROJECT_KEY" \
  --set-env-vars JIRA_CLOUD="$JIRA_CLOUD" \
  --set-env-vars LANGCHAIN_TRACING_V2="$LANGCHAIN_TRACING_V2" \
  --update-secrets="LANGCHAIN_API_KEY=LANGCHAIN_API_KEY:latest" \
  --update-secrets="GITLAB_PERSONAL_ACCESS_TOKEN=GITLAB_PERSONAL_ACCESS_TOKEN:latest" \
  --update-secrets="JIRA_API_TOKEN=JIRA_API_TOKEN:latest" \
  --update-secrets="DEVAI_API_KEY=DEVAI_API_KEY:latest" \
  --min-instances=1 \
  --max-instances=3

أدخِل Y لإنشاء مستودع Docker في Artifact Registry.

Deploying from source requires an Artifact Registry Docker repository to store built containers. A repository named [cloud-run-source-deploy] in 
region [us-central1] will be created.

Do you want to continue (Y/n)?  y

راجِع مسار gcloud run deploy SERVICE_NAME --source=. أدناه. مزيد من المعلومات

وراء الكواليس، يستخدم هذا الأمر buildpacks وCloud Build من Google Cloud لإنشاء صور حاويات تلقائيًا من الرمز المصدر بدون الحاجة إلى تثبيت Docker على جهازك أو إعداد حِزم الإنشاء أو Cloud Build. أي أنّ الأمر الفردي الموضّح أعلاه ينفّذ ما كان يتطلّب استخدام الأمرَين gcloud builds submit وgcloud run deploy.

إذا كنت قد قدّمت Dockerfile(كما فعلنا في هذا المستودع)، سيستخدمه Cloud Build لإنشاء صور الحاويات بدلاً من الاعتماد على حِزم الإنشاء لرصد صور الحاويات وإنشائها تلقائيًا. لمزيد من المعلومات حول حِزم الإنشاء، اطّلِع على المستندات.

راجِع سجلّات Cloud Build في وحدة التحكّم.

راجِع صورة Docker التي تم إنشاؤها في Artifact Registry.

راجِع تفاصيل مثيل Cloud Run في Cloud Console.

تطبيق الاختبار

اختبِر نقطة النهاية من خلال تنفيذ أمر curl.

عدِّل عنوان URL الخاص بخدمة Cloud Run قبل تنفيذ الأمر.

مثال:

curl -H "X-devai-api-key: $DEVAI_API_KEY" https://devai-api-1110000001.us-central1.run.app/test

8. أتمتة عملية تنفيذ القصص

Forge هي منصة تتيح للمطوّرين إنشاء تطبيقات تتكامل مع منتجات Atlassian، مثل Jira وConfluence وCompass وBitbucket.

تثبيت Forge CLI

ثبِّت Forge CLI على مستوى العالم عن طريق تنفيذ ما يلي:

npm install -g @forge/cli

في هذا الدرس التطبيقي، سنستخدم متغيرات البيئة لتسجيل الدخول.

إعداد مشروع JIRA

استخدِم حسابك الشخصي لإنشاء مشاريع JIRA أو عرضها.

راجِع مشاريع JIRA الحالية: https://admin.atlassian.com/

أنشِئ مشروعًا جديدًا على JIRA باستخدام حسابك الشخصي.

انتقِل إلى https://team.atlassian.com/your-work وانقر على ، ثم اختَر . بعد ذلك، اختَر "JIRA Software" - "تجربته الآن". اتّبِع التعليمات التي تظهر على الشاشة لإكمال عملية إنشاء المشروع أو الموقع.

اختَر JIRA Software.

أنشِئ مشروعًا جديدًا.

إنشاء رمز مميّز لواجهة برمجة تطبيقات Atlassian

أنشئ رمزًا مميزًا لواجهة برمجة تطبيقات Atlassian أو استخدِم رمزًا حاليًا لتسجيل الدخول إلى واجهة سطر الأوامر.

تستخدم واجهة سطر الأوامر الرمز المميز عند تنفيذ الأوامر.

انتقِل إلى https://id.atlassian.com/manage/api-tokens.
انقر على إنشاء رمز مميّز لواجهة برمجة التطبيقات.
أدخِل تصنيفًا لوصف الرمز المميز لواجهة برمجة التطبيقات. على سبيل المثال، forge-api-token.
انقر على إنشاء.
انقر على النسخ إلى الحافظة وأغلِق مربّع الحوار.

ضبط إعدادات بيئة Forge

ارجع إلى Cloud Console ونفِّذ الأوامر أدناه في الوحدة الطرفية.

سجِّل الدخول إلى Forge CLI لبدء استخدام أوامر Forge.

اضبط عنوان بريدك الإلكتروني على JIRA أو FORGE. استبدِلها بعنوان بريدك الإلكتروني.

export FORGE_EMAIL=your-email

اضبط الرمز المميز لواجهة برمجة تطبيقات Forge. استبدِلها بالرمز المميز لواجهة برمجة التطبيقات في JIRA.

export FORGE_API_TOKEN=your-jira-api-token

اختبِر واجهة سطر الأوامر Forge من خلال تنفيذ الأمر أدناه. أجب بـ "No" عندما يُطلب منك جمع الإحصاءات.

forge settings set usage-analytics false

تأكَّد من تسجيل الدخول.

forge whoami

مثال على الناتج

Logged in as John Green (johngreen@email.com)
Account ID: 123090:aaabbcc-076a-455c-99d0-d1aavvccdd

إنشاء تطبيق Forge

تأكَّد من أنّك في المجلد "~/genai-for-developers".

تشغيل الأمر لإنشاء تطبيق Forge

forge create

استخدِم القيم التالية عند طلبها:

اسم التطبيق: devai-jira-ui-qwiklabs
اختَر فئة: UI Kit
اختَر منتجًا: Jira
اختَر نموذجًا: jira-issue-panel

انتقِل إلى مجلد التطبيق.

cd devai-jira-ui-qwiklabs/

شغِّل الأمر لتثبيت الاعتماديات.

npm install

نفِّذ أمر النشر.

forge deploy

مثال على الناتج:

Deploying your app to the development environment.
Press Ctrl+C to cancel.

Running forge lint...
No issues found.

✔ Deploying devai-jira-ui-qwiklabs to development...

ℹ Packaging app files
ℹ Uploading app
ℹ Validating manifest
ℹ Snapshotting functions
ℹ Deploying to environment

✔ Deployed

Deployed devai-jira-ui-qwiklabs to the development environment.

تثبيت التطبيق

forge install

استخدِم القيم التالية عند طلبها:

اختَر منتجًا: Jira
أدخِل عنوان URL للموقع الإلكتروني: your-domain.atlassian.net

مثال على الناتج:

Select the product your app uses.

? Select a product: Jira

Enter your site. For example, your-domain.atlassian.net

? Enter the site URL: genai-for-developers.atlassian.net

Installing your app onto an Atlassian site.
Press Ctrl+C to cancel.

? Do you want to continue? Yes

✔ Install complete!

Your app in the development environment is now installed in Jira on genai-for-developers.atlassian.net

افتح موقع JIRA الإلكتروني وأنشئ مهمة JIRA جديدة مع الوصف التالي:

Create HTML, CSS and JavaScript using React.js framework to implement Login page with username and password fields, validation and documentation. Provide complete implementation, do not omit anything.

عند فتح المهمة، سيظهر لك الزر "devai-jira-ui-qwiklabs".

انقر على الزر وراجِع التغييرات في واجهة المستخدم.

عرض سجلّات الخلفية في Forge

forge logs

Atlassian Developer Console

يمكنك أيضًا عرض التطبيقات التي تم نشرها وإدارتها في Atlassian Developer Console.

سجلّات المراجعة - التبديل إلى بيئة Development

مراجعة بيان تطبيق Forge ورمز المصدر

افتح الملف "devai-jira-ui-qwiklabs/manifest.yml" واستخدِم Gemini Code Assist لشرح الإعداد.

مراجعة التفسير

افتح الملفات التالية واطلب من Gemini Code Assist شرحها:

devai-jira-ui-qwiklabs/src/frontend/index.jsx
devai-jira-ui-qwiklabs/src/resolvers/index.js

تعديل تطبيق Forge باستخدام نقطة نهاية DevAI API Cloud Run

تحقَّق مما إذا تم ضبط معرّف مشروع Google Cloud Platform:

gcloud config get project

إذا لم يكن الأمر كذلك، اضبط مشروع Google Cloud Platform باستخدام معرّف المشروع من صفحة المختبر في Qwiklabs:

مثلاً: qwiklabs-gcp-00-2c10937585bb

gcloud config set project YOUR_QWIKLABS_PROJECT_ID

ضبط عنوان URL لخدمة Cloud Run:

export DEVAI_API_URL=$(gcloud run services list --filter="(devai-api)" --format="value(URL)")

forge variables set DEVAI_API_URL $DEVAI_API_URL

اضبط مفتاح واجهة برمجة التطبيقات DEVAI:

export DEVAI_API_KEY=api-key-that-you-created

forge variables set --encrypt DEVAI_API_KEY $DEVAI_API_KEY

أكِّد ذلك من خلال تنفيذ الأمر أدناه:

forge variables list

مثال على الناتج

تعديل بيان تطبيق Forge ورمزه

يمكن العثور على مقتطفات الرموز هذه في المستودع ضمن المجلد sample-devai-jira-ui.

افتح ملف البيان في المحرّر: devai-jira-ui-qwiklabs/manifest.yml

أضِف الأسطر أدناه في نهاية الملف، واستبدِل نقطة نهاية Cloud Run بالنقطة التي نشرتها.

permissions:
  scopes:
    - read:jira-work
    - write:jira-work
  external:
    fetch:
      client:
        - devai-api-gjerpi6qqq-uc.a.run.app/create-gitlab-mr # replace with YOUR CLOUD RUN URL

افتح ملف أدوات تحليل الاسم/الفهرس في المحرِّر: devai-jira-ui-qwiklabs/src/resolvers/index.js

أضِف الأسطر أدناه بعد الدالة getText الحالية.

resolver.define('getApiKey', (req) => {
  return process.env.DEVAI_API_KEY;
});

resolver.define('getDevAIApiUrl', (req) => {
  return process.env.DEVAI_API_URL;
});

افتح ملف frontend/index في المحرّر: devai-jira-ui-qwiklabs/src/frontend/index.jsx

استبدِل index.jsx بالمحتوى أدناه. عدِّل الرابط إلى معرّف المستخدم/المستودع في GitLab.

هناك مكانان عليك تعديل YOUR-GIT-USERID وYOUR-GIT-REPO فيهما.

ابحث عن هذا السطر في الملف وأجرِ التغييرات التالية:

https://gitlab.com/YOUR-GIT-USERID/YOUR-GIT-REPO/-/merge_requests

import React from 'react';
import ForgeReconciler, { Text, Link, useProductContext } from '@forge/react';
import { requestJira } from '@forge/bridge';
import { invoke } from '@forge/bridge';
import api, { route, assumeTrustedRoute } from '@forge/api';

const devAIApiKey = await invoke("getApiKey")
const devAIApiUrl = await invoke("getDevAIApiUrl")


const App = () => {
  const context = useProductContext();

  const [description, setDescription] = React.useState();

  const fetchDescriptionForIssue = async () => {
    const issueId = context?.extension.issue.id;
  
    const res = await requestJira(`/rest/api/2/issue/${issueId}`);
    const data = await res.json();
    
    const bodyGenerateData = `{"prompt": ${JSON.stringify(data.fields.description)}}`;

    const generateRes = await api.fetch(devAIApiUrl+'/create-gitlab-mr,
      {
        body: bodyGenerateData,
        method: 'post',
        headers: {
          'Content-Type': 'application/json',
          'x-devai-api-key': devAIApiKey,
         },
      }
    )

    const resData = await generateRes.text();

    // Add link to the GitLab merge request page as a comment
    await requestJira(`/rest/api/2/issue/${issueId}/comment`, {
      method: 'POST',
      headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json'
      },
      body: `{"body": "[GitLab Merge Request|https://gitlab.com/YOUR-GIT-USERID/YOUR-GIT-REPO/-/merge_requests]"}`
    });


    return "Response will be added as a comment. Please refresh in a few moments.";
  };

  React.useEffect(() => {
    if (context) {
      fetchDescriptionForIssue().then(setDescription);
    }
  }, [context]);

  return (
    <>
      <Text>{description}</Text>
      <Link href='https://gitlab.com/YOUR-GIT-USERID/YOUR-GIT-REPO/-/merge_requests' openNewTab={true}>GitLab Merge Request</Link>
    </>
  );
};

ForgeReconciler.render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

إعادة نشر تطبيق Forge

إضافة التبعيات في ملف package.json:

"@forge/api": "4.0.0",

شغِّل الأمر التالي لتثبيت الاعتماديات:

npm install

نشر التطبيق المعدَّل:

forge deploy

مثال على الناتج:

ℹ Uploading app
ℹ Validating manifest
ℹ Snapshotting functions
ℹ Deploying to environment

✔ Deployed

Deployed devai-jira-ui-qwiklabs to the development environment.

We've detected new scopes or egress URLs in your app.
Run forge install --upgrade and restart your tunnel to put them into effect.

تثبيت التطبيق المُحدَّث:

forge install --upgrade

مثال على الناتج:

Upgrading your app on the Atlassian site.

Your app will be upgraded with the following additional scopes:
- read:jira-work
- write:jira-work

Your app will exchange data with the following urls:
- devai-api-7su2ctuqpq-uc.a.run.app

? Do you want to continue? Yes

✔ Upgrade complete!

Your app in the development environment is now the latest in Jira on genai-for-developers.atlassian.net.

اختبار تطبيق Forge

افتح مهمة JIRA حالية أو أنشئ مهمة جديدة في مشروع JIRA.

عليك إزالة اللوحة السابقة إذا تمت إضافتها من قبل.

انقر على "..." واختَر "إزالة" من القائمة. بعد ذلك، يمكنك النقر على الزر مرة أخرى.

الاطّلاع على تعليقات Jira

بعد تلقّي ردّ من DEVAI API، ستتم إضافة تعليق على مشكلة JIRA.

رابط طلب الدمج في GitLab

يمكنك التبديل بين علامتَي التبويب "History" و "Comments" لإعادة تحميل طريقة العرض.

تأكيد طلب دمج GitLab

افتح GitLab وابحث عن طلبات دمج جديدة في مشروعك.

عمليات تتبُّع النماذج اللغوية الكبيرة في LangSmith

إذا كنت قد أعددت تتبُّع نموذج اللغة الكبير، افتح بوابة LangSmith وراجِع تتبُّع نموذج اللغة الكبير لطلب إنشاء طلب دمج في GitLab.

عيّنة من عملية تتبُّع نموذج لغوي كبير في LangSmith

9- نقل التغييرات إلى مستودع GitHub

(OPTIONAL SECTION)

انتقِل إلى موقع GitHub الإلكتروني وأنشئ مستودعًا جديدًا لنقل التغييرات الخاصة بهذا الدرس التطبيقي إلى مستودعك الشخصي.

ارجع إلى Cloud Console واضبط اسم مستخدم Git وعنوان البريد الإلكتروني في الوحدة الطرفية.

عدِّل القيم قبل تنفيذ الأوامر.

git config --global user.name "Your Name"
git config --global user.email "your_email@example.com"

أنشئ مفتاح SSH وأضِفه إلى مستودع GitHub.

يُرجى تعديل عنوان بريدك الإلكتروني قبل تنفيذ الأوامر.

لا تُدخِل عبارة المرور وتضغط على مفتاح Enter عدة مرات لإكمال عملية إنشاء المفتاح.

ssh-keygen -t ed25519 -C "your-email-address"

eval "$(ssh-agent -s)"

ssh-add ~/.ssh/id_ed25519

cat ~/.ssh/id_ed25519.pub

أضِف المفتاح العام الذي تم إنشاؤه إلى حسابك على GitHub.

افتح https://github.com/settings/keys وانقر على "New SSH key".

استخدِم "qwiklabs-key" لاسم المفتاح وانسخ/الصق الناتج من الأمر الأخير.

ارجع إلى الوحدة الطرفية، ونفِّذ التغييرات وادفعها.

cd ~/genai-for-developers

git remote rm origin

اضبط المصدر البعيد باستخدام المستودع الذي تم إنشاؤه أعلاه.

استبدِلها بعنوان URL الخاص بالمستودع.

git remote add origin git@github.com:YOUR-GITHUB-USERID/YOUR-GITHUB-REPO.git

أضِف التغييرات وقم بتثبيتها ودفعها.

git add .

git commit -m "lab changes"

git push -u origin main

10. تهانينا!

تهانينا، لقد أكملت الدرس التطبيقي.

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

كيفية نشر تطبيقات Cloud Run لدمجها مع واجهات Gemini API
كيفية إنشاء تطبيق Atlassian Forge ونشره في JIRA
كيفية استخدام وكلاء ReAct في LangChain لأتمتة مهام GitLab
كيفية مراجعة عمليات تتبُّع النماذج اللغوية الكبيرة في LangSmith

الخطوة التالية:

سنقدّم المزيد من الجلسات العملية قريبًا.

تَنظيم

لتجنُّب تحمّل رسوم في حسابك على Google Cloud مقابل الموارد المستخدَمة في هذا البرنامج التعليمي، احذف المشروع الذي يحتوي على الموارد أو احتفظ بالمشروع واحذف الموارد الفردية.

حذف المشروع

أسهل طريقة لإيقاف الفوترة هي حذف المشروع الذي أنشأته لتنفيذ البرنامج التعليمي.