كيفية ربط تطبيق Node.js على Cloud Run بقاعدة بيانات PostgreSQL

1. نظرة عامة

أداة ربط Node.js في Cloud SQL هي أسهل طريقة لربط تطبيق Node.js بقاعدة بيانات Cloud SQL بشكل آمن. ‫Cloud Run هي منصة مُدارة بالكامل بدون خادم تتيح لك تشغيل حاويات لا يتم تسجيل بياناتها ويمكن استدعاؤها من خلال طلبات HTTP. سيوضّح لك هذا الدرس العملي كيفية ربط تطبيق Node.js على Cloud Run بقاعدة بيانات Cloud SQL for PostgreSQL بشكل آمن باستخدام حساب خدمة من خلال ميزة "مصادقة إدارة الهوية والوصول".

ما ستتعلمه

في هذه الميزة الاختبارية، ستتعرّف على كيفية تنفيذ ما يلي:

  • إنشاء مثيل Cloud SQL لقاعدة بيانات PostgreSQL
  • نشر تطبيق Node.js على Cloud Run
  • ربط تطبيقك بقاعدة البيانات باستخدام مكتبة Cloud SQL Node.js Connector

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

  • يفترض هذا التمرين العملي معرفة بيئتَي Cloud Console وCloud Shell.

2. قبل البدء

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

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

b35bf95b8bf3d5d8.png

a99b7ace416376c4.png

bd84a6d3004737c5.png

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

إعداد البيئة

فعِّل Cloud Shell من خلال النقر على الرمز على يسار شريط البحث.

ecdc43ada29e91b.png

من Cloud Shell، فعِّل واجهات برمجة التطبيقات:

gcloud services enable compute.googleapis.com sqladmin.googleapis.com \
  run.googleapis.com artifactregistry.googleapis.com \
  cloudbuild.googleapis.com servicenetworking.googleapis.com

إذا طُلب منك منح الإذن، انقر على "منح الإذن" للمتابعة.

6356559df3eccdda.png

قد يستغرق تنفيذ هذا الأمر بضع دقائق، ولكن من المفترض أن يعرض في النهاية رسالة نجاح مشابهة لما يلي:

Operation "operations/acf.p2-327036483151-73d90d00-47ee-447a-b600-a6badf0eceae" finished successfully.

3- إعداد حساب خدمة

أنشئ حساب خدمة على Google Cloud وأعدّ إعداداته ليتم استخدامه من قِبل Cloud Run، وذلك لضمان حصوله على الأذونات الصحيحة للاتصال بخدمة Cloud SQL.

  1. نفِّذ الأمر gcloud iam service-accounts create على النحو التالي لإنشاء حساب خدمة جديد:
    gcloud iam service-accounts create quickstart-service-account \
  --display-name="Quickstart Service Account"
  2. نفِّذ الأمر gcloud projects add-iam-policy-binding على النحو التالي لإضافة دور عميل Cloud SQL إلى حساب خدمة Google Cloud الذي أنشأته للتو. في Cloud Shell، سيتم استبدال التعبير ${GOOGLE_CLOUD_PROJECT} باسم مشروعك. يمكنك أيضًا إجراء عملية الاستبدال هذه يدويًا إذا كنت تفضّل ذلك.
    gcloud projects add-iam-policy-binding ${GOOGLE_CLOUD_PROJECT} \
  --member="serviceAccount:quickstart-service-account@${GOOGLE_CLOUD_PROJECT}.iam.gserviceaccount.com" \
  --role="roles/cloudsql.client"
  3. نفِّذ الأمر gcloud projects add-iam-policy-binding على النحو التالي لإضافة دور مستخدم مثيل Cloud SQL إلى حساب خدمة Google Cloud الذي أنشأته للتو.
    gcloud projects add-iam-policy-binding ${GOOGLE_CLOUD_PROJECT} \
  --member="serviceAccount:quickstart-service-account@${GOOGLE_CLOUD_PROJECT}.iam.gserviceaccount.com" \
  --role="roles/cloudsql.instanceUser"
  4. نفِّذ الأمر gcloud projects add-iam-policy-binding على النحو التالي لإضافة دور كاتب السجلّ إلى حساب خدمة Google Cloud الذي أنشأته للتو.
    gcloud projects add-iam-policy-binding ${GOOGLE_CLOUD_PROJECT} \
  --member="serviceAccount:quickstart-service-account@${GOOGLE_CLOUD_PROJECT}.iam.gserviceaccount.com" \
  --role="roles/logging.logWriter"

4. إعداد Cloud SQL

نفِّذ الأمر gcloud sql instances create لإنشاء مثيل Cloud SQL.

  • --database-version: نوع إصدار محرك قاعدة البيانات في حال عدم تحديدها، يتم استخدام القيمة التلقائية لواجهة برمجة التطبيقات. راجِع مستندات إصدارات قاعدة بيانات gcloud للاطّلاع على الإصدارات الحالية المتاحة.
  • --cpu: عدد النوى المطلوب في الجهاز.
  • ‫--memory: قيمة عدد صحيح تشير إلى مقدار الذاكرة المطلوب في الجهاز. يجب تقديم وحدة قياس الحجم (على سبيل المثال، 3072 ميغابايت أو 9 غيغابايت). في حال عدم تحديد الوحدات، سيتم افتراض أنّها غيغابايت.
  • استبدِل --region بالموقع الجغرافي الإقليمي للجهاز الظاهري (على سبيل المثال: us-central1 أو asia-east1 أو us-east1).
  • --database-flags: تتيح ضبط العلامات. في هذه الحالة، سنفعّل cloudsql.iam_authentication للسماح لخدمة Cloud Run بالاتصال بخدمة Cloud SQL باستخدام حساب الخدمة الذي أنشأناه سابقًا.
    gcloud sql instances create quickstart-instance \
  --database-version=POSTGRES_18 \
  --tier=db-custom-1-3840 \
  --region=us-central1 \
  --edition=ENTERPRISE \
  --database-flags=cloudsql.iam_authentication=on

قد يستغرق إكمال هذا الأمر بضع دقائق.

نفِّذ الأمر gcloud sql databases create لإنشاء قاعدة بيانات Cloud SQL ضِمن quickstart-instance.

gcloud sql databases create quickstart_db \
  --instance=quickstart-instance

أنشِئ مستخدمًا لقاعدة بيانات PostgreSQL لحساب الخدمة الذي أنشأته سابقًا للوصول إلى قاعدة البيانات.

gcloud sql users create quickstart-service-account@${GOOGLE_CLOUD_PROJECT}.iam \
  --instance=quickstart-instance \
  --type=cloud_iam_service_account \
  --database-roles=postgres

تحذير: لا تستخدِم --database-roles=postgres في تطبيقات الإنتاج. نستخدم هذا الإذن لتوفير الامتيازات اللازمة لإنشاء الجداول وإسقاطها آليًا للرمز البرمجي في هذا المختبر.

5- تجهيز التطبيق

إعداد تطبيق Node.js يستجيب لطلبات HTTP

  1. في Cloud Shell، أنشئ دليلاً جديدًا باسم helloworld، ثم انتقِل إلى هذا الدليل:
    mkdir helloworld
cd helloworld
  2. تهيئة ملف package.json كوحدة
    npm init -y
npm pkg set type="module"
npm pkg set main="index.mjs"
npm pkg set scripts.start="node index.mjs"
  3. ثبِّت تبعية موصّل Node.js في Cloud SQL.
    npm install @google-cloud/cloud-sql-connector
  4. ثبِّت pg للتفاعل مع قاعدة بيانات PostgreSQL.
    npm install pg
  5. ثبِّت Express لقبول طلبات http الواردة.
    npm install express
  6. أنشئ ملف index.mjs يتضمّن رمز التطبيق. يمكن لهذا الرمز إجراء ما يلي:
    • قبول طلبات HTTP
    • الربط بقاعدة البيانات
    • تخزين وقت طلب HTTP في قاعدة البيانات
    • عرض أوقات آخر خمس طلبات
    نفِّذ الأمر التالي في Cloud Shell:
    cat > index.mjs << "EOF"
import express from 'express';
import pg from 'pg';
import {Connector} from '@google-cloud/cloud-sql-connector';

const {Pool} = pg;

const connector = new Connector();
const clientOpts = await connector.getOptions({
    instanceConnectionName: process.env.INSTANCE_CONNECTION_NAME,
    authType: 'IAM'
});

const pool = new Pool({
    ...clientOpts,
    user: process.env.DB_USER,
    database: process.env.DB_NAME
});

const app = express();

app.get('/', async (req, res) => {
  await pool.query('INSERT INTO visits(created_at) VALUES(NOW())');
  const {rows} = await pool.query('SELECT created_at FROM visits ORDER BY created_at DESC LIMIT 5');
  console.table(rows); // prints the last 5 visits
  res.send(rows);
});

const port = parseInt(process.env.PORT) || 8080;
app.listen(port, async () => {
  console.log('process.env: ', process.env);
  await pool.query(`CREATE TABLE IF NOT EXISTS visits (
    id SERIAL NOT NULL,
    created_at timestamp NOT NULL,
    PRIMARY KEY (id)
  );`);
  console.log(`helloworld: listening on port ${port}`);
});

EOF

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

6. نشر تطبيق Cloud Run

نفِّذ الأمر أدناه لنشر تطبيقك على Cloud Run:

  • استبدِل --region بالموقع الجغرافي الإقليمي للجهاز الظاهري (على سبيل المثال: us-central1 أو asia-east1 أو us-east1).
  • استبدِل --source برمز المصدر الذي سيتم نشره. في هذه الحالة، يشير . إلى رمز المصدر في المجلد الحالي helloworld.
  • --set-env-vars: يضبط متغيرات البيئة التي يستخدمها التطبيق لتوجيهه إلى قاعدة بيانات Cloud SQL.
  • --service-account: يربط عملية نشر Cloud Run بحساب الخدمة الذي لديه أذونات للاتصال بقاعدة بيانات Cloud SQL التي تم إنشاؤها في بداية هذا الدرس العملي.
  • --allow-unauthenticated: يسمح بالطلبات غير المصادَق عليها لكي يكون التطبيق متاحًا على الإنترنت.
gcloud run deploy helloworld \
  --region=us-central1 \
  --source=. \
  --set-env-vars INSTANCE_CONNECTION_NAME="${GOOGLE_CLOUD_PROJECT}:us-central1:quickstart-instance" \
  --set-env-vars DB_NAME="quickstart_db" \
  --set-env-vars DB_USER="quickstart-service-account@${GOOGLE_CLOUD_PROJECT}.iam" \
  --service-account="quickstart-service-account@${GOOGLE_CLOUD_PROJECT}.iam.gserviceaccount.com" \
  --allow-unauthenticated

إذا طُلب منك ذلك، اضغط على y وEnter لتأكيد رغبتك في المتابعة:

Do you want to continue (Y/n)? y

بعد بضع دقائق، من المفترض أن يوفّر لك التطبيق عنوان URL يمكنك الانتقال إليه.

انتقِل إلى عنوان URL للاطّلاع على تطبيقك أثناء عمله. في كل مرة تزور فيها عنوان URL أو تعيد تحميل الصفحة، ستظهر لك آخر خمس زيارات تم إرجاعها بتنسيق JSON.

7. تهانينا

لقد نشرت تطبيق Node.js على Cloud Run يمكنه الاتصال بقاعدة بيانات PostgreSQL تعمل على Cloud SQL.

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

  • إنشاء قاعدة بيانات Cloud SQL for PostgreSQL
  • نشر تطبيق Node.js على Cloud Run
  • ربط تطبيقك بخدمة Cloud SQL باستخدام Cloud SQL Node.js Connector

تَنظيم

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

gcloud projects delete ${GOOGLE_CLOUD_PROJECT}