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

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

1. نظرة عامة

تهدف سلسلة دروس الترميز هذه (وهي دروس عملية ذات وتيرة ذاتية) إلى مساعدة المطوّرين في فهم الخيارات المختلفة المتاحة لهم عند نشر تطبيقاتهم. في هذا الدرس التطبيقي حول الترميز، ستتعرّف على كيفية استخدام Google Cloud Translation API مع Python، ويمكنك تشغيلها على الجهاز أو نشرها على منصة الحوسبة السحابية بدون خادم (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، وتحديدًا Cloud Translation API (الإصدار المتقدّم/الإصدار 3)
تشغيل تطبيق ويب أساسي على الجهاز أو نشره على منصّة حوسبة بدون خادم في السحابة الإلكترونية

المتطلبات

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

الاستطلاع

كيف ستستخدم هذا الدليل التعليمي؟

قراءته وإكمال التمارين

قراءته فقط

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

مبتدئ

متوسط

متقدّم

ما مدى رضاك عن تجربتك في استخدام خدمات Google Cloud؟

مبتدئ

متوسط

متقدّم

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

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

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

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

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

3- تفعيل واجهة برمجة التطبيقات Translation API

تفعيل واجهات برمجة تطبيقات Cloud

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

مقدمة

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

الخيار 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 وCloud Artifact Registry وCloud Translation API:

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

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

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

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

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

التكلفة

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

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

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

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

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

ملخّص

بعد أن تعرّفت على كيفية تفعيل واجهات برمجة تطبيقات Google بشكل عام، انتقِل إلى مدير واجهة برمجة التطبيقات وفعِّل Cloud Translation API وCloud Run وCloud 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 من الزر الأخضر الرمز كما هو موضّح في لقطة الشاشة التالية:

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

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 Translation API.
تمثّل المتغيّرات الشاملة تطبيق Flask ورقم تعريف مشروع Cloud وعميل Translation API و "مسار الموقع الجغرافي" الرئيسي لطلبات بيانات Translation API واللغة المصدر واللغة المستهدفة. في هذه الحالة، تكون اللغة الإنجليزية (en) والإسبانية (es)، ولكن يمكنك تغيير هذه القيم إلى رموز لغات أخرى تتوافق مع Cloud Translation 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 Translation API ترجمة عدد محدّد من الأحرف شهريًا مجانًا. توفّر App Engine أيضًا حصة مجانية، وينطبق ذلك أيضًا على Cloud Functions وCloud Run. وسيتم تحصيل رسوم منك في حال تجاوز أي منهما. إذا كنت تنوي الانتقال إلى ورشة رموز البرمجة التالية، ليس عليك إغلاق تطبيقك.

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

ويؤدي نشر التطبيقات على منصة الحوسبة بدون خادم من 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

‫Google Cloud Translation وGoogle ML Kit

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

Python وFlask

Flask

الترخيص

يخضع هذا الدليل التعليمي لترخيص عام من Creative Commons Attribution 2.0، في حين يخضع رمز المصدر في المستودع لترخيص Apache 2.