صورة يومية: التمرين المعملي 4: إنشاء واجهة أمامية للويب

1. نظرة عامة

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

21741cd63b425aeb.png

سيستخدم تطبيق الويب هذا إطار عمل CSS يُسمى Bulma للحصول على واجهة مستخدم جيدة المظهر، بالإضافة إلى إطار عمل الواجهة الأمامية Vue.JS JavaScript لطلب واجهة برمجة التطبيقات التي ستنشئها.

سيتألف هذا التطبيق من ثلاث علامات تبويب:

  • صفحة رئيسية تعرض الصور المصغّرة لجميع الصور التي تم تحميلها، بالإضافة إلى قائمة التصنيفات التي تصف الصورة (التي رصدتها واجهة Cloud Vision API في معمل سابق).
  • صفحة صورة مجمّعة تعرض الصورة المجمّعة المكوّنة من آخر 4 صور تم تحميلها
  • صفحة تحميل، حيث يمكن للمستخدمين تحميل صور جديدة.

تظهر الواجهة الأمامية الناتجة على النحو التالي:

6a4d5e5603ba4b73.png

هذه الصفحات الثلاث هي صفحات HTML بسيطة:

  • تستدعي الصفحة الرئيسية (index.html) رمز الواجهة الخلفية لتطبيق Node App Engine للحصول على قائمة الصور المصغّرة وتصنيفاتها، وذلك من خلال طلب AJAX إلى عنوان URL‏ /api/pictures. تستخدم الصفحة الرئيسية Vue.js لجلب هذه البيانات.
  • تشير صفحة الصورة المجمّعة (collage.html) إلى الصورة collage.png التي تجمع آخر 4 صور.
  • توفّر صفحة التحميل (upload.html) نموذجًا بسيطًا لتحميل صورة من خلال طلب POST إلى عنوان URL‏ /api/pictures.

أهداف الدورة التعليمية

  • App Engine
  • Cloud Storage
  • Cloud Firestore

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

إعداد بيئة ذاتية التعلّم

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

b35bf95b8bf3d5d8.pnga99b7ace416376c4.pngbd84a6d3004737c5.png

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

بدء Cloud Shell

على الرغم من إمكانية تشغيل Google Cloud عن بُعد من الكمبيوتر المحمول، ستستخدم في هذا الدرس التطبيقي حول الترميز Google Cloud Shell، وهي بيئة سطر أوامر تعمل في السحابة الإلكترونية.

من Google Cloud Console، انقر على رمز Cloud Shell في شريط الأدوات في أعلى يسار الصفحة:

55efc1aaa7a4d3ad.png

من المفترض أن يستغرق توفير البيئة والاتصال بها بضع ثوانٍ فقط. عند الانتهاء، من المفترض أن يظهر لك شيء مثل هذا:

7ffe5cbb04455448.png

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

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

يتطلّب App Engine استخدام Compute Engine API. تأكَّد من تفعيله:

gcloud services enable compute.googleapis.com

من المفترض أن تظهر لك رسالة تفيد باكتمال العملية بنجاح:

Operation "operations/acf.5c5ef4f6-f734-455d-b2f0-ee70b5a17322" finished successfully.

4. استنساخ الرمز

تحقَّق من الرمز، إذا لم يسبق لك ذلك:

git clone https://github.com/GoogleCloudPlatform/serverless-photosharing-workshop

يمكنك بعد ذلك الانتقال إلى الدليل الذي يحتوي على الواجهة الأمامية:

cd serverless-photosharing-workshop/frontend

سيكون لديك تخطيط الملف التالي للواجهة الأمامية:

frontend
 |
 ├── index.js
 ├── package.json
 ├── app.yaml
 |
 ├── public
      |
      ├── index.html
      ├── collage.html
      ├── upload.html
      |
      ├── app.js
      ├── script.js
      ├── style.css

في جذر المشروع، لديك 3 ملفات:

  • يحتوي index.js على رمز Node.js
  • تحدّد السمة package.json تبعيات المكتبة
  • ‫app.yaml هو ملف الإعداد لـ Google App Engine

يحتوي المجلد public على الموارد الثابتة:

  • ‫index.html هي الصفحة التي تعرض جميع الصور المصغّرة والتصنيفات
  • يعرض "collage.html" الصورة المجمّعة للصور الحديثة
  • يحتوي "upload.html" على نموذج لتحميل صور جديدة
  • يستخدم "app.js" Vue.js لتعبئة صفحة "index.html" بالبيانات
  • ‫script.js يعالج قائمة التنقّل ورمز "الهامبرغر" على الشاشات الصغيرة
  • ‫style.css يحدّد بعض توجيهات CSS

5- استكشاف الرمز البرمجي

الاعتمادية

يحدّد ملف package.json اعتماديات المكتبة المطلوبة:

{
  "name": "frontend",
  "version": "0.0.1",
  "main": "index.js",
  "scripts": {
    "start": "node index.js"
  },
  "dependencies": {
    "@google-cloud/firestore": "^3.4.1",
    "@google-cloud/storage": "^4.0.0",
    "express": "^4.16.4",
    "dayjs": "^1.8.22",
    "bluebird": "^3.5.0",
    "express-fileupload": "^1.1.6"
  }
}

يعتمد تطبيقنا على:

  • firestore: للوصول إلى Cloud Firestore باستخدام البيانات الوصفية للصور
  • storage: للوصول إلى Google Cloud Storage حيث يتم تخزين الصور
  • ‫express: إطار عمل الويب لـ Node.js
  • dayjs: مكتبة صغيرة لعرض التواريخ بطريقة سهلة الاستخدام
  • bluebird: مكتبة JavaScript promise
  • express-fileupload: مكتبة للتعامل مع عمليات تحميل الملفات بسهولة.

واجهة Express الأمامية

في بداية وحدة التحكّم index.js، ستحتاج إلى جميع العناصر التابعة المحدّدة في package.json سابقًا:

const express = require('express');
const fileUpload = require('express-fileupload');
const Firestore = require('@google-cloud/firestore');
const Promise = require("bluebird");
const {Storage} = require('@google-cloud/storage');
const storage = new Storage();
const path = require('path');
const dayjs = require('dayjs');
const relativeTime = require('dayjs/plugin/relativeTime')
dayjs.extend(relativeTime)

بعد ذلك، يتم إنشاء مثيل تطبيق Express.

يتم استخدام برمجيتين وسيطتين من Express:

  • يشير استدعاء express.static() إلى أنّ الموارد الثابتة ستكون متاحة في الدليل الفرعي public.
  • ويضبط fileUpload() تحميل الملفات على الحدّ الأقصى لحجم الملف وهو 10 ميغابايت، لتحميل الملفات على الجهاز في نظام الملفات في الذاكرة في الدليل /tmp.
const app = express();
app.use(express.static('public'));
app.use(fileUpload({
    limits: { fileSize: 10 * 1024 * 1024 },
    useTempFiles : true,
    tempFileDir : '/tmp/'
}))

من بين الموارد الثابتة، لديك ملفات HTML للصفحة الرئيسية وصفحة الملصقات وصفحة التحميل. ستستدعي هذه الصفحات الخلفية لواجهة برمجة التطبيقات. ستتضمّن واجهة برمجة التطبيقات هذه نقاط النهاية التالية:

  • POST /api/pictures من خلال النموذج في upload.html، سيتم تحميل الصور عبر طلب POST
  • GET /api/pictures تعرض نقطة النهاية هذه مستند JSON يحتوي على قائمة الصور وتصنيفاتها
  • GET /api/pictures/:name يعيد عنوان URL هذا التوجيه إلى موقع التخزين في السحابة الإلكترونية للصورة بالحجم الكامل
  • GET /api/thumbnails/:name يعيد عنوان URL هذا التوجيه إلى موقع التخزين في السحابة الإلكترونية للصورة المصغّرة
  • GET /api/collage يعيد عنوان URL الأخير هذا التوجيه إلى موقع التخزين في السحابة الإلكترونية لصورة الكولاج التي تم إنشاؤها

تحميل صورة

قبل استكشاف رمز Node.js لتحميل الصور، ألقِ نظرة سريعة على public/upload.html.

... 
<form method="POST" action="/api/pictures" enctype="multipart/form-data">
    ... 
    <input type="file" name="pictures">
    <button>Submit</button>
    ... 
</form>
... 

يشير عنصر النموذج إلى نقطة النهاية /api/pictures، باستخدام طريقة HTTP POST وتنسيق متعدد الأجزاء. يجب الآن أن يستجيب index.js لنقطة النهاية والطريقة هذه، وأن يستخرج الملفات:

app.post('/api/pictures', async (req, res) => {
    if (!req.files || Object.keys(req.files).length === 0) {
        console.log("No file uploaded");
        return res.status(400).send('No file was uploaded.');
    }
    console.log(`Receiving files ${JSON.stringify(req.files.pictures)}`);

    const pics = Array.isArray(req.files.pictures) ? req.files.pictures : [req.files.pictures];

    pics.forEach(async (pic) => {
        console.log('Storing file', pic.name);
        const newPicture = path.resolve('/tmp', pic.name);
        await pic.mv(newPicture);

        const pictureBucket = storage.bucket(process.env.BUCKET_PICTURES);
        await pictureBucket.upload(newPicture, { resumable: false });
    });


    res.redirect('/');
});

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

جارٍ إدراج الصور

حان الوقت لعرض صورك الجميلة.

في معالج /api/pictures، يمكنك الاطّلاع على مجموعة pictures في قاعدة بيانات Firestore لاسترداد جميع الصور (التي تم إنشاء صورها المصغّرة)، مرتّبة حسب تاريخ الإنشاء تنازليًا.

يمكنك إرسال كل صورة في مصفوفة JavaScript، مع اسمها والتصنيفات التي تصفها (من Cloud Vision API) واللون السائد وتاريخ إنشاء مألوف (باستخدام dayjs، نستخدم إزاحات زمنية نسبية مثل "بعد 3 أيام من الآن").

app.get('/api/pictures', async (req, res) => {
    console.log('Retrieving list of pictures');

    const thumbnails = [];
    const pictureStore = new Firestore().collection('pictures');
    const snapshot = await pictureStore
        .where('thumbnail', '==', true)
        .orderBy('created', 'desc').get();

    if (snapshot.empty) {
        console.log('No pictures found');
    } else {
        snapshot.forEach(doc => {
            const pic = doc.data();
            thumbnails.push({
                name: doc.id,
                labels: pic.labels,
                color: pic.color,
                created: dayjs(pic.created.toDate()).fromNow()
            });
        });
    }
    console.table(thumbnails);
    res.send(thumbnails);
});

تعرض وحدة التحكّم هذه نتائج بالشكل التالي:

[
   {
      "name": "IMG_20180423_163745.jpg",
      "labels": [
         "Dish",
         "Food",
         "Cuisine",
         "Ingredient",
         "Orange chicken",
         "Produce",
         "Meat",
         "Staple food"
      ],
      "color": "#e78012",
      "created": "a day ago"
   },
   ...
]

يتم استخدام بنية البيانات هذه من خلال مقتطف Vue.js صغير من صفحة index.html. في ما يلي نسخة مبسّطة من الترميز من تلك الصفحة:

<div id="app">
        <div class="container" id="app">
                <div id="picture-grid">
                        <div class="card" v-for="pic in pictures">
                                <div class="card-content">
                                        <div class="content">
                                                <div class="image-border" :style="{ 'border-color': pic.color }">
                                                        <a :href="'/api/pictures/' + pic.name">
                                                                <img :src="'/api/thumbnails/' + pic.name">
                                                        </a>
                                                </div>
                                                <a class="panel-block" v-for="label in pic.labels" :href="'/?q=' + label">
                                                        <span class="panel-icon">
                                                                <i class="fas fa-bookmark"></i> &nbsp;
                                                        </span>
                                                        {{ label }}
                                                </a>
                                        </div>
                                </div>
                        </div>
            </div>
        </div>
</div>

سيشير معرّف div إلى Vue.js بأنّه جزء من الترميز الذي سيتم عرضه ديناميكيًا. يتم تنفيذ التكرارات بفضل توجيهات v-for.

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

أخيرًا، ندرج التصنيفات التي تصف الصورة.

في ما يلي رمز JavaScript لمقتطف Vue.js (في ملف public/app.js الذي تم استيراده في أسفل صفحة index.html):

var app = new Vue({
  el: '#app',
  data() {
    return { pictures: [] }
  },
  mounted() {
    axios
      .get('/api/pictures')
      .then(response => { this.pictures = response.data })
  }
})

يستخدم رمز Vue مكتبة Axios لإجراء طلب AJAX إلى نقطة نهاية /api/pictures. بعد ذلك، يتم ربط البيانات التي تم عرضها برمز العرض في الترميز الذي رأيته سابقًا.

عرض الصور

من index.html، يمكن للمستخدمين الاطّلاع على الصور المصغّرة للصور، والنقر عليها لعرض الصور بالحجم الكامل، ومن collage.html، يمكن للمستخدمين الاطّلاع على صورة collage.png.

في ترميز HTML لتلك الصفحات، تشير الصورة src والرابط href إلى نقاط النهاية الثلاث هذه، والتي تعيد التوجيه إلى مواقع Cloud Storage للصور والصور المصغّرة والصور المجمّعة. لا حاجة إلى تضمين المسار كبيانات غير قابلة للتغيير في البرنامج في ترميز HTML.

app.get('/api/pictures/:name', async (req, res) => {
    res.redirect(`https://storage.cloud.google.com/${process.env.BUCKET_PICTURES}/${req.params.name}`);
});

app.get('/api/thumbnails/:name', async (req, res) => {
    res.redirect(`https://storage.cloud.google.com/${process.env.BUCKET_THUMBNAILS}/${req.params.name}`);
});

app.get('/api/collage', async (req, res) => {
    res.redirect(`https://storage.cloud.google.com/${process.env.BUCKET_THUMBNAILS}/collage.png`);
});

تشغيل تطبيق Node

بعد تحديد جميع نقاط النهاية، يصبح تطبيق Node.js جاهزًا للإطلاق. يستمع تطبيق Express إلى المنفذ 8080 تلقائيًا، وهو جاهز لخدمة الطلبات الواردة.

const PORT = process.env.PORT || 8080;

app.listen(PORT, () => {
    console.log(`Started web frontend service on port ${PORT}`);
    console.log(`- Pictures bucket = ${process.env.BUCKET_PICTURES}`);
    console.log(`- Thumbnails bucket = ${process.env.BUCKET_THUMBNAILS}`);
});

6. الاختبار محليًا

اختبِر الرمز البرمجي على جهازك للتأكّد من أنّه يعمل قبل نشره على السحابة الإلكترونية.

عليك تصدير متغيّرَي البيئة المقابلَين لحزمتَي Cloud Storage:

export BUCKET_THUMBNAILS=thumbnails-${GOOGLE_CLOUD_PROJECT}
export BUCKET_PICTURES=uploaded-pictures-${GOOGLE_CLOUD_PROJECT}

داخل المجلد frontend، ثبِّت تبعيات npm وابدأ تشغيل الخادم:

npm install; npm start

إذا سارت الأمور على ما يرام، من المفترض أن يبدأ الخادم على المنفذ 8080:

Started web frontend service on port 8080
- Pictures bucket = uploaded-pictures-${GOOGLE_CLOUD_PROJECT}
- Thumbnails bucket = thumbnails-${GOOGLE_CLOUD_PROJECT}

ستظهر الأسماء الحقيقية للحِزم في هذه السجلّات، وهو أمر مفيد لأغراض تصحيح الأخطاء.

من Cloud Shell، يمكنك استخدام ميزة معاينة الويب لتصفّح التطبيق الذي يتم تشغيله محليًا:

82fa3266d48c0d0a.png

استخدِم CTRL-C للخروج.

7. النشر في App Engine

تطبيقك جاهز للنشر.

ضبط App Engine

افحص ملف الإعداد app.yaml لـ App Engine:

runtime: nodejs16
env_variables:
  BUCKET_PICTURES: uploaded-pictures-GOOGLE_CLOUD_PROJECT
  BUCKET_THUMBNAILS: thumbnails-GOOGLE_CLOUD_PROJECT

يُعلن السطر الأول أنّ بيئة التشغيل تستند إلى Node.js 10. يتم تحديد متغيّرَي بيئة للإشارة إلى الحزمتَين، للصور الأصلية والصور المصغّرة.

لاستبدال GOOGLE_CLOUD_PROJECT برقم تعريف مشروعك الفعلي، يمكنك تنفيذ الأمر التالي:

sed -i -e "s/GOOGLE_CLOUD_PROJECT/${GOOGLE_CLOUD_PROJECT}/" app.yaml

نشر

اضبط منطقتك المفضّلة في App Engine، واحرص على استخدام المنطقة نفسها في المختبرات السابقة:

gcloud config set compute/region europe-west1

ونشر:

gcloud app deploy

بعد دقيقة أو دقيقتين، سيتم إعلامك بأنّ التطبيق يعرض عدد الزيارات:

Beginning deployment of service [default]...
╔════════════════════════════════════════════════════════════╗
╠═ Uploading 8 files to Google Cloud Storage                ═╣
╚════════════════════════════════════════════════════════════╝
File upload done.
Updating service [default]...done.
Setting traffic split for service [default]...done.
Deployed service [default] to [https://GOOGLE_CLOUD_PROJECT.appspot.com]
You can stream logs from the command line by running:
  $ gcloud app logs tail -s default
To view your application in the web browser run:
  $ gcloud app browse

يمكنك أيضًا الانتقال إلى قسم App Engine في Cloud Console للاطّلاع على التطبيق الذي تم نشره واستكشاف ميزات App Engine، مثل تحديد الإصدارات وتقسيم عدد الزيارات:

db0e196b00fceab1.png

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

للاختبار، انتقِل إلى عنوان URL التلقائي في App Engine للتطبيق (https://<YOUR_PROJECT_ID>.appspot.com/) وستظهر لك واجهة المستخدم الأمامية قيد التشغيل.

6a4d5e5603ba4b73.png

9. تنظيف (اختياري)

إذا لم تكن تنوي الاحتفاظ بالتطبيق، يمكنك تنظيف الموارد لتوفير التكاليف وأن تكون مواطنًا سحابيًا جيدًا بشكل عام عن طريق حذف المشروع بأكمله:

gcloud projects delete ${GOOGLE_CLOUD_PROJECT} 

10. تهانينا!

تهانينا! يربط تطبيق الويب Node.js هذا المستضاف على App Engine جميع خدماتك معًا، ويتيح للمستخدمين تحميل الصور وعرضها.

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

  • App Engine
  • Cloud Storage
  • Cloud Firestore

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