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

لمحة عن هذا الدرس التطبيقي حول الترميز

تاريخ التعديل الأخير: مارس 24, 2025

تأليف: Andrey Shakirov

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

1. نظرة عامة

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

ما ستتعرّف عليه

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

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

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

يفترض هذا التمرين أنّك على دراية ببيئة Cloud Console وCloud Shell.

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

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

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

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

إعداد البيئة

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

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

تفعيل Gemini لـ Google Cloud API:

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

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

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

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

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

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

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

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

تُعرف الأسئلة التي تطرحها على 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)

تطبيق 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 وGemini Chat.

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

فعِّل الخدمات المطلوبة لاستخدام واجهات برمجة تطبيقات Vertex AI وGemini Chat.

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 Toolkits الشائعة ما يلي:

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

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

تحتوي حزمة أدوات Gitlab على أدوات تتيح لوكيل LLM التفاعل مع مستودع gitlab. الأداة هي حزمة لـ مكتبة python-gitlab.

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

إنشاء ملف: لإنشاء ملف جديد في المستودع
قراءة ملف: لقراءة ملف من المستودع
تعديل ملف: لتعديل ملف في المستودع
إنشاء طلب سحب: لإنشاء طلب سحب من فرع العمل الخاص بالبوت إلى الفرع الأساسي.
الحصول على المشاكل: تُستخدَم هذه الوظيفة لجلب المشاكل من المستودع.
الحصول على مشكلة: لعرض تفاصيل عن مشكلة معيّنة.
التعليق على مشكلة: لنشر تعليق بشأن مشكلة معيّنة.
حذف ملف: لحذف ملف من المستودع

إعداد مشروع 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

لتجنُّب الكشف عن معلومات حسّاسة في وحدة التحكّم، من أفضل الممارسات استخدام read -s GITLAB_PERSONAL_ACCESS_TOKEN، وهي طريقة آمنة لضبط متغيّرات البيئة بدون ظهور القيمة في سجلّ أوامر وحدة التحكّم. بعد تشغيله، عليك لصق القيمة والنقر على مفتاح Enter. عليك أيضًا تصدير متغيّر البيئة: 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 LLM

يمكنك إعداد الحساب إذا كنت تريد عرض معلومات تتبُّع موظّفي الدعم في 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

إنشاء مفاتيح سرية في أداة "إدارة الأسرار"

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

أنشئ الأسرار المطلوبة واحفظها في أداة "إدارة الأسرار".

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) - "Try it now" (تجربته الآن). اتّبِع التعليمات لإكمال عملية إنشاء المشروع أو الموقع الإلكتروني.

اختَر JIRA Software.

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

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

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

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

انتقِل إلى 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 CLI من خلال تنفيذ الأمر أدناه. أدخِل "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" لشرح الإعدادات.

راجِع التفسير.

افتح الملفات التالية واطلب من 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;
});

افتح ملف الواجهة الأمامية/الفهرس في المحرِّر: 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.

تطبيق Test Forge

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

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

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

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

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

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

يمكنك التبديل بين علامتَي التبويب "History" و "Comments" لإعادة تحميل الصفحة.

التحقّق من طلب الدمج في GitLab

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

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

إذا أعددت تتبُّع LLM، افتح بوابة LangSmith وراجِع تتبُّع LLM لطلب دمج GitLab.

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

9. دفع التغييرات إلى مستودع GitHub

(قسم اختياري)

انتقِل إلى الموقع الإلكتروني 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
كيفية إنشاء تطبيق Atlassian Forge ونشره في JIRA
كيفية استخدام LangChain ReAct Agents لأتمتة مهام GitLab
كيفية مراجعة عمليات تتبُّع النماذج اللغوية الكبيرة في LangSmith

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

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

تَنظيم

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

حذف المشروع

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

الإبلاغ عن خطأ