نشر تطبيق أساسي "ترجمة Google" تطبيق على Python 3 Cloud Run (Docker)

1. نظرة عامة

تهدف سلسلة دروس البرمجة هذه (التي يمكن إكمالها بالوتيرة التي تناسبك، وهي عبارة عن برامج تعليمية عملية) إلى مساعدة المطوّرين في فهم الخيارات المختلفة المتاحة لهم عند نشر تطبيقاتهم. في هذا الدرس التطبيقي حول الترميز، ستتعرّف على كيفية استخدام Google Cloud Translation API مع لغة Python وتشغيلها محليًا أو تفعيلها على منصة حوسبة بدون خادم على Google Cloud (App Engine أو Cloud Functions أو Cloud Run). يمكن نشر التطبيق النموذجي المتوفّر في مستودع هذا البرنامج التعليمي ثماني طرق مختلفة (على الأقل) مع إجراء تغييرات طفيفة فقط في الإعدادات:

خادم Flask المحلي (Python 2)
خادم Flask المحلي (Python 3)
App Engine (Python 2)
App Engine (Python 3)
وظائف السحابة الإلكترونية (Python 3)
‫Cloud Run (Python 2 من خلال Docker)
Cloud Run (Python 3 عبر Docker)
‫Cloud Run (Python 3 من خلال حِزم Cloud Buildpacks)

يركّز هذا الدرس التطبيقي حول الترميز على نشر هذا التطبيق على الأنظمة الأساسية المكتوبة بخط عريض أعلاه.

ستتعرّف على كيفية

استخدام واجهات Google Cloud API، وتحديدًا ترجمة Cloud API (الوضع المتقدّم/الإصدار 3)
تشغيل تطبيق ويب أساسي محليًا أو نشره على منصة حوسبة بدون خادم على السحابة الإلكترونية

المتطلبات

مشروع Google Cloud يتضمّن حساب فوترة نشطًا على Cloud
تثبيت Flask لتشغيله محليًا، أو تفعيل منصة حوسبة بدون خادم على السحابة الإلكترونية لعمليات النشر المستنِدة إلى السحابة الإلكترونية
مهارات أساسية في لغة Python
معرفة عملية بأوامر نظام التشغيل الأساسية

استطلاع الرأي

كيف ستستخدم هذا البرنامج التعليمي؟

قراءة المحتوى وإكمال التمارين

قراءة المحتوى فقط

كيف تقيّم تجربتك مع Python؟

مبتدئ

متوسط

متمكّن

ما هو تقييمك لتجربة استخدام خدمات Google Cloud؟

مبتدئ

متوسط

متقدّم

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

إعداد البيئة بالسرعة التي تناسبك

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

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

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

3- تفعيل Translation API

تفعيل Cloud APIs

في هذا القسم، سنتعرّف على كيفية تفعيل واجهات Google API بشكل عام. بالنسبة إلى نموذج تطبيقنا، عليك تفعيل ترجمة Cloud API وCloud Run وCloud Artifact Registry.

مقدّمة

بغض النظر عن واجهة Google API التي تريد استخدامها في تطبيقك، يجب تفعيلها. يوضّح المثال التالي طريقتَين لتفعيل Cloud Vision API. بعد التعرّف على كيفية تفعيل إحدى واجهات Cloud API، ستتمكّن من تفعيل واجهات برمجة التطبيقات الأخرى لأنّ العملية متشابهة.

الخيار 1: من Cloud Shell أو واجهة سطر الأوامر

على الرغم من أنّ تفعيل واجهات برمجة التطبيقات من Cloud Console هو الإجراء الأكثر شيوعًا، يفضّل بعض المطوّرين تنفيذ كل شيء من سطر الأوامر. لإجراء ذلك، عليك البحث عن "اسم الخدمة" لواجهة برمجة التطبيقات. يبدو أنّها عنوان URL: SERVICE_NAME.googleapis.com. يمكنك العثور على هذه المنتجات في مخطط المنتجات المتوافقة، أو يمكنك طلبها آليًا باستخدام Google Discovery API.

باستخدام هذه المعلومات، يمكنك تفعيل واجهة برمجة تطبيقات باستخدام Cloud Shell (أو بيئة التطوير المحلية مع تثبيت أداة سطر الأوامر gcloud)، وذلك باتّباع الخطوات التالية:

gcloud services enable SERVICE_NAME.googleapis.com

على سبيل المثال، يفعّل هذا الأمر واجهة Cloud Vision API:

gcloud services enable vision.googleapis.com

يؤدي هذا الأمر إلى تفعيل App Engine:

gcloud services enable appengine.googleapis.com

يمكنك أيضًا تفعيل واجهات برمجة تطبيقات متعددة بطلب واحد. على سبيل المثال، يفعّل سطر الأوامر هذا Cloud Run وArtifact Registry وCloud Translation API:

gcloud services enable artifactregistry.googleapis.com run.googleapis.com translate.googleapis.com

الخيار 2: من Cloud Console

يمكنك أيضًا تفعيل Vision API في "إدارة واجهات برمجة التطبيقات". من Cloud Console، انتقِل إلى إدارة واجهات برمجة التطبيقات واختَر المكتبة.

إذا أردت تفعيل Cloud Vision API، ابدأ بإدخال "vision" في شريط البحث، وسيظهر أي شيء يتطابق مع ما أدخلته حتى الآن:

اختَر واجهة برمجة التطبيقات التي تريد تفعيلها وانقر على تفعيل:

التكلفة

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

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

تختلف الأسعار والمستويات المجانية بين واجهات Google API. أمثلة:

Google Cloud/GCP: تتم فوترة كل منتج بشكل مختلف، وعادةً ما تكون الفوترة حسب دورة وحدة المعالجة المركزية الافتراضية (vCPU) أو مستهلك مساحة التخزين أو استخدام الذاكرة أو الدفع حسب الاستخدام. اطّلِع على معلومات الطبقة المجانية أعلاه.
خرائط Google: تتضمّن مجموعة من واجهات برمجة التطبيقات وتوفّر للمستخدمين رصيدًا شهريًا مجانيًا بقيمة 200 دولار أمريكي.
واجهات برمجة التطبيقات في Google Workspace (المعروفة سابقًا باسم G Suite): توفّر استخدامًا مجانيًا (بحدود معيّنة) مشمولاً برسوم الاشتراك الشهري في Workspace، لذا لا تتم فوترة استخدام واجهات برمجة التطبيقات في Gmail و"Google Drive" و"تقويم Google" و"مستندات Google" و"جداول بيانات Google" و"العروض التقديمية من Google" بشكل مباشر.

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

ملخّص

بعد أن تعرّفت على كيفية تفعيل واجهات Google API بشكل عام، انتقِل إلى إدارة واجهات برمجة التطبيقات وفعِّل ترجمة Cloud وCloud Run وArtifact Registry (إذا لم يسبق لك إجراء ذلك). عليك تفعيل الخيار الأول لأنّ تطبيقنا يستخدمه. عليك تفعيل الخيار الأخير لأنّه المكان الذي يتم فيه تخزين صور الحاويات قبل نشرها لبدء خدمة Cloud Run، ولهذا السبب عليك تفعيل هذا الخيار. إذا كنت تفضّل تفعيلها كلها باستخدام أداة gcloud، نفِّذ الأمر التالي بدلاً من ذلك من الوحدة الطرفية:

gcloud services enable artifactregistry.googleapis.com run.googleapis.com translate.googleapis.com

على الرغم من أنّ حصتها الشهرية غير مدرَجة في صفحة الملخّص الشامل "دائمًا مجاني"، فإنّ صفحة أسعار Translation API توضّح أنّ جميع المستخدمين يحصلون على كمية ثابتة من الأحرف المترجَمة شهريًا. لن يتم تحصيل أي رسوم منك مقابل استخدام واجهة برمجة التطبيقات إذا بقيت دون هذا الحدّ. إذا كانت هناك أي رسوم أخرى ذات صلة بخدمة Google Cloud، سيتمّ مناقشتها في النهاية في قسم "التنظيف".

4. الحصول على رمز نموذج التطبيق

استنسِخ الرمز في المستودع محليًا أو في Cloud Shell (باستخدام الأمر git clone)، أو نزِّل ملف ZIP من الزر الأخضر Code (الرمز) كما هو موضّح في لقطة الشاشة التالية:

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

5- جولة في نموذج التطبيق

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

from flask import Flask, render_template, request
import google.auth
from google.cloud import translate

app = Flask(__name__)
_, PROJECT_ID = google.auth.default()
TRANSLATE = translate.TranslationServiceClient()
PARENT = 'projects/{}'.format(PROJECT_ID)
SOURCE, TARGET = ('en', 'English'), ('es', 'Spanish')

# . . . [translate() function definition] . . .

if __name__ == '__main__':
    import os
    app.run(debug=True, threaded=True, host='0.0.0.0',
            port=int(os.environ.get('PORT', 8080)))

توفّر عمليات الاستيراد وظائف Flask والوحدة النمطية google.auth ومكتبة عميل ترجمة Cloud API.
تمثّل المتغيّرات العمومية تطبيق Flask ورقم تعريف مشروع على السحابة الإلكترونية وعميل Translation API ومسار الموقع الجغرافي الرئيسي لطلبات Translation API واللغتَين المصدر واللغة المستهدفة. في هذه الحالة، تكون اللغة الإنجليزية (en) والإسبانية (es)، ولكن يمكنك تغيير هاتين القيمتين إلى رموز لغات أخرى تتيحها ترجمة Cloud API.
يتم استخدام حزمة if الكبيرة في أسفل الصفحة في البرنامج التعليمي لتشغيل هذا التطبيق محليًا، وهي تستخدم خادم تطوير Flask لعرض تطبيقنا. يتوفّر هذا القسم أيضًا في البرامج التعليمية للنشر على Cloud Run في حال عدم تجميع خادم الويب في الحاوية. يُطلب منك تفعيل تجميع الخادم في الحاوية، ولكن في حال تجاهلت ذلك، سيعود رمز التطبيق إلى استخدام خادم تطوير Flask. (لا تتعلّق المشكلة بـ App Engine أو Cloud Functions لأنّهما منصتان مستندتان إلى المصدر، ما يعني أنّ Google Cloud توفّر خادم ويب تلقائيًا وتشغّله).

أخيرًا، في منتصف main.py يوجد جوهر التطبيق، وهو الدالة translate():

@app.route('/', methods=['GET', 'POST'])
def translate(gcf_request=None):
    """
    main handler - show form and possibly previous translation
    """

    # Flask Request object passed in for Cloud Functions
    # (use gcf_request for GCF but flask.request otherwise)
    local_request = gcf_request if gcf_request else request

    # reset all variables (GET)
    text = translated = None

    # if there is data to process (POST)
    if local_request.method == 'POST':
        text = local_request.form['text']
        data = {
            'contents': [text],
            'parent': PARENT,
            'target_language_code': TARGET[0],
        }
        # handle older call for backwards-compatibility
        try:
            rsp = TRANSLATE.translate_text(request=data)
        except TypeError:
            rsp = TRANSLATE.translate_text(**data)
        translated = rsp.translations[0].translated_text

    # create context & render template
    context = {
        'orig':  {'text': text, 'lc': SOURCE},
        'trans': {'text': translated, 'lc': TARGET},
    }
    return render_template('index.html', **context)

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

تحقَّق مما إذا كانت الطلبات واردة من Cloud Functions باستخدام المتغيّر local_request. ترسل Cloud Functions كائن طلب Flask الخاص بها، بينما ستحصل جميع الكائنات الأخرى (التي يتم تشغيلها محليًا أو نشرها على App Engine أو Cloud Run) على كائن الطلب مباشرةً من Flask.
أعِد ضبط المتغيرات الأساسية للنموذج. يتم ذلك بشكل أساسي لطلبات GET لأنّ طلبات POST ستتضمّن بيانات تحلّ محلّها.
إذا كان الطلب POST، احصل على النص المطلوب ترجمته، وأنشئ بنية JSON تمثّل متطلبات البيانات الوصفية لواجهة برمجة التطبيقات. بعد ذلك، يمكنك طلب البيانات من واجهة برمجة التطبيقات، والرجوع إلى إصدار سابق من واجهة برمجة التطبيقات إذا كان المستخدم يستعين بمكتبة أقدم.
في كلتا الحالتين، يجب تنسيق النتائج الفعلية (POST) أو عدم توفّر بيانات (GET) في سياق النموذج وعرضه.

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

<!doctype html>
<html><head><title>My Google Translate 1990s</title><body>
<h2>My Google Translate (1990s edition)</h2>

{% if trans['text'] %}
    <h4>Previous translation</h4>
    <li><b>Original</b>:   {{ orig['text'] }}  (<i>{{ orig['lc'][0] }}</i>)</li>
    <li><b>Translated</b>: {{ trans['text'] }} (<i>{{ trans['lc'][0] }}</i>)</li>
{% endif %}

<h4>Enter <i>{{ orig['lc'][1] }}</i> text to translate to <i>{{ trans['lc'][1] }}</i>:</h4>
<form method="POST"><input name="text"><input type="submit"></form>
</body></html>

6. ضبط Docker لإنشاء صورة Python 3

افتح الآن الملف Dockerfile الذي يظهر على النحو التالي بدون معلومات الترخيص:

#FROM python:3-slim
FROM python:2-slim
WORKDIR /app
COPY . .
RUN pip install -r requirements.txt
ENTRYPOINT ["python", "main.py"]

كما تلاحظ، تم إعدادها تلقائيًا لاستخدام Python 2، لذا لنغيّر ذلك من خلال تعديل السطر FROM من python:2-slim إلى python:3-slim أو إزالة التعليق من السطر العلوي وحذف السطر القديم FROM. عند الانتهاء، من المفترض أن يظهر Dockerfile على النحو التالي:

FROM python:3-slim
WORKDIR /app
COPY . .
RUN pip install -r requirements.txt
ENTRYPOINT ["python", "main.py"]

7. تفعيل الخدمة

أنت الآن جاهز لنشر خدمة الترجمة على Cloud Run من خلال تنفيذ الأمر التالي:

gcloud run deploy translate --source . --allow-unauthenticated --platform managed

يجب أن يبدو الناتج على النحو التالي، وأن يقدّم بعض الطلبات للخطوات التالية:

$ gcloud run deploy translate --source . --allow-unauthenticated --platform managed
Please specify a region:
 [1] asia-east1
 [2] asia-east2
. . . (other regions) . . .
 [28] us-west4
 [29] cancel
Please enter your numeric choice:  REGION_CHOICE

To make this the default region, run `gcloud config set run/region REGION`.

Deploying from source requires an Artifact Registry repository to
store build artifacts. A repository named [cloud-run-source-deploy] in
 region [REGION] will be created.

Do you want to continue (Y/n)?

This command is equivalent to running "gcloud builds submit --pack image=[IMAGE] ." and "gcloud run deploy translate --image [IMAGE]"

Building . . . and deploying container to Cloud Run service [translate] in project [PROJECT_ID] region [REGION]
✓ Building and deploying... Done.
  ✓ Creating Container Repository...
  ✓ Uploading sources...
  ✓ Building Container... Logs are available at [https://console.cloud.google.com/cloud-build/builds/60e1b
  9bb-b991-4b4e-8d8a-HASH?project=PROJECT_NUMBER].
  ✓ Creating Revision...
  ✓ Routing traffic...
  ✓ Setting IAM Policy...
Done.
Service [translate] revision [translate-00001-xyz] has been deployed and is serving 100 percent of traffic.
Service URL: https://SVC_NAME-HASH-REG_ABBR.a.run.app

بعد أن أصبح تطبيقك متاحًا في جميع أنحاء العالم، من المفترض أن تتمكّن من الوصول إليه من خلال عنوان URL الذي يحتوي على رقم تعريف مشروعك كما هو موضّح في ناتج النشر:

ترجمة نص لتجربة هذه الميزة

8. الخاتمة

تهانينا! تعرّفت على كيفية تفعيل Cloud Translation API والحصول على بيانات الاعتماد اللازمة ونشر تطبيق ويب بسيط على Python 3 Cloud Run.

تَنظيم

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

ومع ذلك، إذا لم تكن مستعدًا للانتقال إلى البرنامج التعليمي التالي بعد أو كنت قلقًا بشأن عثور الإنترنت على التطبيق الذي نشرته للتو، يمكنك إيقاف تطبيق App Engine أو حذف Cloud Function أو إيقاف خدمة Cloud Run لتجنُّب تحمّل رسوم. عندما تكون مستعدًا للانتقال إلى درس تطبيقي حول الترميز التالي، يمكنك إعادة تفعيلها. من ناحية أخرى، إذا كنت لن تواصل استخدام هذا التطبيق أو غيره من دروس البرمجة وتريد حذف كل شيء تمامًا، يمكنك إيقاف مشروعك.

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

9- مراجع إضافية

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

دراسة إضافية

بعد أن اكتسبت بعض الخبرة في استخدام Translation API، لننفّذ بعض التمارين الإضافية لتطوير مهاراتك بشكل أكبر. لمواصلة مسار التعلّم، عدِّل تطبيقنا النموذجي لتنفيذ ما يلي:

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

مزيد من المعلومات

Google App Engine

‫Google Cloud Functions

‫Google Cloud Run

‫Google Cloud Buildpacks وContainer Registry وArtifact Registry

‫ترجمة Cloud من Google وحزمة تعلّم الآلة من Google

منتجات/صفحات Google Cloud الأخرى

‫Python وFlask

Flask

الترخيص

يخضع هذا الدليل التوجيهي/التعليمي لترخيص المشاع الإبداعي مع نسب العمل إلى مؤلفه 2.0 Generic License، بينما يخضع الرمز المصدر في المستودع لترخيص Apache 2.