1. قبل البدء
يوضّح لك هذا الدرس العملي كيفية إنشاء مشروع على Google Cloud ثم طلب واجهات برمجة التطبيقات Google Cloud APIs من هذا المشروع.
المتطلبات الأساسية
- القدرة على التنقّل في Google Cloud Console
أهداف الدورة التعليمية
- كيفية إنشاء مشروع على Google Cloud
- كيفية إعداد حساب فوترة
- كيفية إعداد Cloud Shell
- كيفية تفعيل واجهة برمجة تطبيقات
- كيفية منح إذن لواجهة برمجة تطبيقات باستخدام مفتاح واجهة برمجة تطبيقات
- كيفية تفويض واجهة برمجة تطبيقات باستخدام حساب خدمة
المتطلبات
- حساب Google، مثل حساب Gmail أو حساب Google Workspace
- الوصول إلى حساب فوترة Cloud أو بطاقة ائتمان للاشتراك في برنامج الفترة التجريبية المجانية
2. طريقة الإعداد
يوضّح لك هذا القسم كيفية إنشاء مشروع على Google Cloud وإعداد حساب فوترة وإعداد Cloud Shell.
إنشاء مشروع على Google Cloud وإعداد حساب فوترة
- سجِّل الدخول إلى Cloud Console واختَر مشروعًا أو أنشِئ مشروعًا.
تذكَّر رقم تعريف المشروع الظاهر تحت حقل اسم المشروع. المعرّف هو اسم فريد في جميع مشاريع Google Cloud (الاسم أعلاه مستخدَم حاليًا)، ويُشار إليه لاحقًا في هذا الدرس العملي باسم PROJECT_ID.
- بعد ذلك، عليك تفعيل الفوترة في Cloud Console من أجل استخدام موارد Google Cloud.
على الرغم من أنّ هذا الدرس التطبيقي العملي لن يكلّفك الكثير، إن وُجدت تكلفة، اتّبِع التعليمات الواردة في قسم التنظيف لإيقاف الموارد وتجنُّب التكاليف التي تتجاوز هذا الدرس التطبيقي العملي. يُرجى العِلم أنّ مستخدمي Google Cloud الجدد مؤهّلون للاستفادة من فترة تجريبية مجانية بقيمة 300 دولار أمريكي.
إعداد Cloud Shell
في هذا الدرس التطبيقي حول الترميز، ستستخدم Cloud Shell، وهي بيئة سطر أوامر تعمل في Google Cloud. Cloud Shell هو جهاز افتراضي مستند إلى Debian ومحمّل بجميع أدوات التطوير التي تحتاج إليها. ويوفّر دليلًا منزليًا دائمًا بسعة 5 غيغابايت، ما يحسّن بشكل كبير أداء الشبكة والمصادقة. يعني هذا أنّه لا تحتاج إلى أي شيء سوى متصفّح لإكمال هذا الدرس التطبيقي حول الترميز.
لتفعيل Cloud Shell من Cloud Console، اتّبِع الخطوات التالية:
- انقر على
تفعيل Cloud Shell.
قد يستغرق توفير البيئة والاتصال بها بضع لحظات.
بعد الاتصال بـ Cloud Shell، من المفترض أن يظهر لك أنّه تمّت مصادقتك وأنّ المشروع تمّ ضبطه مسبقًا على PROJECT_ID.
- إنشاء قائمة بالحسابات التي لديها بيانات اعتماد:
gcloud auth list
من المفترض أن يظهر لك الناتج التالي:
Credentialed accounts:
- <MY_ACCOUNT>@<MY_DOMAIN>.com (active)
- للاطّلاع على قائمة بمشاريعك، أدخِل هذا الأمر.
gcloud config list project
من المفترض أن يظهر لك الناتج التالي:
[core]
project = <PROJECT_ID>
إذا لم يتم ضبط المشروع لسبب ما، نفِّذ هذا الأمر لإعداده.
gcloud config set project <PROJECT_ID>
PROJECT_ID هو المعرّف الذي استخدمته في خطوات الإعداد. يمكنك أيضًا البحث عنه في لوحة بيانات Cloud Console:
يضبط Cloud Shell أيضًا بعض متغيرات البيئة تلقائيًا، ما قد يكون مفيدًا عند تنفيذ الأوامر المستقبلية.
- للاطّلاع على رقم تعريف مشروعك، أدخِل الأمر التالي.
echo $GOOGLE_CLOUD_PROJECT
من المفترض أن يظهر لك الناتج التالي:
<PROJECT_ID>
- أخيرًا، اضبط المنطقة التلقائية وإعدادات المشروع.
gcloud config set compute/zone us-central1-f
يمكنك اختيار مجموعة متنوعة من المناطق المختلفة. لمزيد من المعلومات، يُرجى الاطّلاع على الأقاليم والمناطق.
3- استدعاء واجهة برمجة تطبيقات من مشروع
يوضّح لك هذا الدرس التطبيقي كيفية استخدام مثال لواجهة برمجة التطبيقات (Natural Language API) للعثور على عناصر (مثل الأشخاص والأماكن والأحداث) في النص، وكيفية تحديد النبرة العاطفية (مستوى الاستحسان) لهذا النص. ستتعرّف على كيفية:
- فعِّل واجهات Google Cloud API.
- الحصول على إذن باستخدام واجهة برمجة التطبيقات من خلال مفاتيح واجهة برمجة التطبيقات وحسابات الخدمة
- استدعِ واجهة برمجة التطبيقات باستخدام
curlومكتبات البرامج.
تفعيل واجهة برمجة تطبيقات
- اختَر واجهات برمجة التطبيقات والخدمات من القائمة الرئيسية في Cloud Console.
- انقر على تفعيل واجهات برمجة التطبيقات والخدمات في أعلى الشاشة.
- في هذه المرحلة، يمكنك فلترة واجهات برمجة التطبيقات وتصفّحها، أو الانتقال مباشرةً إلى واجهة برمجة تطبيقات باستخدام مربّع البحث. ابحث عن
Natural Languageواختَر Cloud Natural Language API.
- انقر على تجربة واجهة برمجة التطبيقات هذه.
إذا لم يظهر زر تجربة واجهة برمجة التطبيقات هذه، انقر على إحدى الطرق المُدرَجة لتجربتها.
إنشاء مفتاح واجهة برمجة تطبيقات
بما أنّك تستخدم curl لإرسال طلب إلى Natural Language API، عليك إنشاء مفتاح واجهة برمجة تطبيقات لتضمينه في عنوان URL الخاص بالطلب.
- في Cloud Console، اختَر قائمة التنقّل > واجهات برمجة التطبيقات والخدمات > بيانات الاعتماد.
- انقر على إنشاء بيانات الاعتماد، ثمّ اختَر مفتاح واجهة برمجة التطبيقات:
- انسخ مفتاح واجهة برمجة التطبيقات الذي تم إنشاؤه، ثم انقر على إغلاق.
استخدام مفتاح واجهة برمجة التطبيقات لطلب بيانات من الواجهة
- في سطر أوامر Cloud Shell، صدِّر مفتاح واجهة برمجة التطبيقات.
export API_KEY=<YOUR_API_KEY>
استبدِل <YOUR_API_KEY> بالمفتاح الذي أنشأته سابقًا.
- أنشئ طلبًا لواجهة برمجة التطبيقات في "محرِّر Cloud Shell" أو باستخدام محرِّر Linux، مثل Vim أو Emacs. يمكنك الاطّلاع على تفاصيل المَعلمات في الطريقة: documents.analyzeEntities. احفظ الناتج في ملف باسم
request.json:
{
"document":{
"type":"PLAIN_TEXT",
"content":"Google, headquartered in Mountain View (1600 Amphitheatre Pkwy, Mountain View, CA 940430), unveiled the new Android phone for $799 at the Consumer Electronic Show. Sundar Pichai said in his keynote that users love their new Android phones."
},
"encodingType":"UTF8"
}
- استدعاء واجهة برمجة التطبيقات باستخدام معلومات الطلب
curl "https://language.googleapis.com/v1/documents:analyzeEntities?key=${API_KEY}" \
-s -X POST -H "Content-Type: application/json" --data-binary @request.json
- أعِد تنفيذ الأمر وأعِد توجيه الناتج إلى ملف وافحص النتيجة. تتوفّر تفاصيل حول ناتج ملف JSON أيضًا في الطريقة: documents.analyzeEntities.
- لتغيير النص الذي سيتم تحليله في الملف
request.json، استبدِل القيمةcontentبالنص الذي تختاره.
4. التفويض باستخدام حساب خدمة
غالبًا ما يتم تفضيل حسابات الخدمة على مفاتيح واجهة برمجة التطبيقات لأنّها توفّر المصادقة والتفويض. يمكنك اعتبار حسابات الخدمة كعناوين بريد إلكتروني لتطبيقك.
- ارجع إلى قسم "بيانات الاعتماد" في قائمة واجهات برمجة التطبيقات والخدمات.
- انقر على إنشاء بيانات اعتماد، ولكن اختَر حساب الخدمة هذه المرة.
- أدخِل اسم حساب خدمة يصف الغرض منه، مثل "
Natural Language Service Account". يقترح النظام رقم تعريف. يمكنك أيضًا إضافة وصف. عند التعرّف على المزيد من المعلومات حول حسابات الخدمة، يمكنك منح حساب الخدمة إذن الوصول إلى المشاريع ومنح المستخدمين إذن الوصول إلى حساب الخدمة، ولكن في الوقت الحالي، ما عليك سوى النقر على تم لإنشاء حساب الخدمة. - لإنشاء زوج مفاتيح يستخدمه حساب الخدمة، انقر على رمز التعديل
.
تظهر تفاصيل حساب الخدمة.
- انسخ عنوان البريد الإلكتروني لحساب الخدمة وارجع إلى Cloud Shell.
- في Cloud Shell، أنشئ مفتاحَي تشفير لحساب الخدمة واضبط متغيّر بيئة للإشارة إليهما:
gcloud iam service-accounts keys create ~/key.json \
--iam-account <your service account email>
export GOOGLE_APPLICATION_CREDENTIALS="/home/$USER/key.json"
تستخدم Google Cloud متغيّر البيئة هذا للعثور على بيانات الاعتماد، لذا ليس من الضروري تضمينها في طلب البيانات من واجهة برمجة التطبيقات.
- يمكنك الآن طلب بيانات من واجهة برمجة التطبيقات باستخدام الأمر:
gcloud ml language analyze-entities --content="Michelangelo Caravaggio, Italian painter, is known for 'The Calling of Saint Matthew'."
يجب أن تكون النتيجة مماثلة لما كانت عليه من قبل.
تتضمّن العديد من واجهات برمجة التطبيقات مكتبات عملاء شاملة لاستخراج هذه التفاصيل. لمزيد من المعلومات عن مكتبات البرامج، يُرجى الاطّلاع على مكتبات برامج Cloud. يمكنك أيضًا قراءة المستندات الخاصة بواجهات برمجة التطبيقات التي تستخدمها لمعرفة مكتبات البرامج المتاحة لها.
5- تَنظيم
من الممارسات السيئة استخدام مفتاح واجهة برمجة تطبيقات غير مقيّد للمشاريع. وإذا تمكّن شخص من الوصول إليه، يمكنه استخدامه بدون الحاجة إلى مصادقة إضافية.
لحذف مفتاح واجهة برمجة التطبيقات هذا، اتّبِع الخطوات التالية:
- انقر على
قائمة التنقل > واجهات برمجة التطبيقات والخدمات > بيانات الاعتماد. - ضمن مفاتيح واجهة برمجة التطبيقات، اختَر المفتاح الذي تريد حذفه، ثم انقر على
حذف. - وبالمثل، بدلاً من القلق بشأن عدم حماية المفتاح الخاص لحساب الخدمة، ضمن حسابات الخدمة، اختَر حساب الخدمة الذي تريد حذفه، ثم انقر على حذف.
6. تهانينا
تهانينا! تعرّفت على كيفية إنشاء مشروع على Google Cloud وكيفية طلب واجهة برمجة تطبيقات من داخل المشروع.