بدء استخدام Spanner Cassandra Adapter

1. مقدمة

‫Spanner هي خدمة قواعد بيانات موزّعة عالميًا وقابلة للتوسّع أفقيًا ومُدارة بالكامل، وهي مناسبة تمامًا لأحمال العمل العلائقية وغير العلائقية.

تتيح لك واجهة Cassandra في Spanner الاستفادة من البنية الأساسية المُدارة بالكامل والقابلة للتوسيع والمتوفّرة بدرجة عالية في Spanner باستخدام أدوات وبنية Cassandra المألوفة.

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

  • كيفية إعداد مثيل وقاعدة بيانات في Spanner
  • كيفية تحويل مخطط Cassandra ونموذج البيانات
  • كيفية تصدير بياناتك السابقة بشكل مجمّع من Cassandra إلى Spanner
  • كيفية توجيه تطبيقك إلى Spanner بدلاً من Cassandra

المتطلبات

  • مشروع Google Cloud مرتبط بحساب فوترة
  • الوصول إلى جهاز تم تثبيت gcloud CLI عليه وإعداده، أو استخدام Google Cloud Shell
  • متصفّح ويب، مثل Chrome أو Firefox

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

إنشاء مشروع على Google Cloud

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

fbef9caa1602edd0.png

a99b7ace416376c4.png

5e3ff691252acf41.png

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

إعداد الفوترة

بعد ذلك، عليك اتّباع دليل المستخدم الخاص بإدارة الفوترة وتفعيل الفوترة في Cloud Console. يمكن لمستخدمي Google Cloud الجدد الاستفادة من برنامج الفترة التجريبية المجانية بقيمة 300 دولار أمريكي. لتجنُّب تحمّل تكاليف تتجاوز هذا البرنامج التعليمي، يمكنك إيقاف مثيل Spanner في نهاية البرنامج باتّباع "الخطوة 9: التنظيف".

بدء Cloud Shell

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

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

55efc1aaa7a4d3ad.png

لن يستغرق توفير البيئة والاتصال بها سوى بضع لحظات. عند الانتهاء، من المفترض أن يظهر لك ما يلي:

7ffe5cbb04455448.png

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

التالي

بعد ذلك، عليك نشر مجموعة Cassandra.

3- تفعيل مجموعة Cassandra (المصدر)

في هذا الدرس التطبيقي حول الترميز، سنعدّ مجموعة Cassandra بعقدة واحدة على Compute Engine.

1. إنشاء جهاز GCE افتراضي لـ Cassandra

لإنشاء مثيل، استخدِم الأمر gcloud compute instances create من Cloud Shell الذي تم توفيره سابقًا.

gcloud compute instances create cassandra-origin \
--machine-type=e2-medium \
--image-family=ubuntu-2204-lts \
--image-project=ubuntu-os-cloud \
--tags=cassandra-migration \
--boot-disk-size=20GB \
--zone=us-central1-a

2. تثبيت Cassandra

انتقِل إلى VM Instances من صفحة Navigation menu باتّباع التعليمات التالية: الانتقال إلى مثيلات الأجهزة الافتراضية.

ابحث عن الجهاز الافتراضي cassandra-origin واتّصل به باستخدام بروتوكول النقل الآمن (SSH) كما هو موضّح:

فتح SSH في مثيل جهاز افتراضي.

نفِّذ الأوامر التالية لتثبيت Cassandra على الجهاز الافتراضي الذي أنشأته وفتحت SSH فيه.

تثبيت Java (متطلّبات Cassandra)

sudo apt-get update
sudo apt-get install -y openjdk-11-jre-headless

إضافة مستودع Cassandra

echo "deb [signed-by=/etc/apt/keyrings/apache-cassandra.asc] https://debian.cassandra.apache.org 41x main" | sudo tee -a /etc/apt/sources.list.d/cassandra.sources.list

sudo curl -o /etc/apt/keyrings/apache-cassandra.asc https://downloads.apache.org/cassandra/KEYS

تثبيت Cassandra

sudo apt-get update
sudo apt-get install -y cassandra

اضبط عنوان الاستماع لخدمة Cassandra.

نستخدم هنا عنوان IP الداخلي للجهاز الافتراضي Cassandra لتعزيز الأمان.

دوِّن عنوان IP الخاص بالجهاز المضيف

يمكنك إما استخدام الأمر التالي في Cloud Shell أو الحصول عليه من صفحة VM Instances في Cloud Console.

gcloud compute instances describe cassandra-origin --format="get(networkInterfaces[0].networkIP)" --zone=us-central1-a

أو

فتح SSH في مثيل جهاز افتراضي.

تعديل العنوان في ملف الإعداد

يمكنك استخدام المحرّر الذي تختاره لتعديل ملف إعدادات Cassandra.

sudo vim /etc/cassandra/cassandra.yaml

غيِّر rpc_address: إلى عنوان IP الخاص بالجهاز الظاهري، ثم احفظ الملف وأغلِقه.

تفعيل خدمة Cassandra على الجهاز الافتراضي

sudo systemctl enable cassandra
sudo systemctl stop cassandra
sudo systemctl start cassandra
sudo systemctl status cassandra

3- إنشاء مساحة مفاتيح وجدول {create-keyspace-and-table}

سنستخدم مثالاً لجدول "المستخدمين" وننشئ مساحة مفاتيح باسم "إحصاءات".

export CQLSH_HOST=<IP of the VM added as rpc_address>
/usr/bin/cqlsh

داخل cqlsh:

-- Create keyspace (adjust replication for production)
CREATE KEYSPACE analytics WITH replication = {'class':'SimpleStrategy', 'replication_factor':1};

-- Use the keyspace
USE analytics;

-- Create the users table
CREATE TABLE users (
    id  int PRIMARY KEY,
    active  boolean,
    username  text,
);

-- Insert 5 rows
INSERT INTO users (id, active, username) VALUES (1, true, 'd_knuth');
INSERT INTO users (id, active, username) VALUES (2, true, 'sanjay_ghemawat');
INSERT INTO users (id, active, username) VALUES (3, false, 'gracehopper');
INSERT INTO users (id, active, username) VALUES (4, true, 'brian_kernighan');
INSERT INTO users (id, active, username) VALUES (5, true, 'jeff_dean');
INSERT INTO users (id, active, username) VALUES (6, true, 'jaime_levy');
-- Select all users to verify the inserts.
SELECT * from users;
-- Exit cqlsh
EXIT;

اترك جلسة SSH مفتوحة أو دوِّن عنوان IP الخاص بهذا الجهاز الظاهري (hostname -I).

التالي

بعد ذلك، ستعمل على إعداد مثيل وقاعدة بيانات Cloud Spanner.

4. إنشاء مثيل Spanner (الهدف)

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

التحقّق من إصدار حزمة تطوير البرامج (SDK) في gcloud

قبل إنشاء آلة افتراضية، تأكَّد من تعديل gcloud SDK في Google Cloud Shell إلى الإصدار المطلوب، أي إصدار أكبر من gcloud SDK 531.0.0. يمكنك العثور على إصدار حزمة تطوير البرامج (SDK) الخاصة بأداة gcloud باتّباع الأمر أدناه.

$ gcloud version | grep Google

في ما يلي مثال على الناتج:

Google Cloud SDK 489.0.0

إذا كان الإصدار الذي تستخدمه أقدم من الإصدار 531.0.0 المطلوب (489.0.0 في المثال السابق)، عليك ترقية حزمة تطوير البرامج (SDK) من Google Cloud من خلال تنفيذ الأمر التالي:

sudo apt-get update \
  && sudo apt-get --only-upgrade install google-cloud-cli-anthoscli google-cloud-cli-cloud-run-proxy kubectl google-cloud-cli-skaffold google-cloud-cli-cbt google-cloud-cli-docker-credential-gcr google-cloud-cli-spanner-migration-tool google-cloud-cli-cloud-build-local google-cloud-cli-pubsub-emulator google-cloud-cli-app-engine-python google-cloud-cli-kpt google-cloud-cli-bigtable-emulator google-cloud-cli-datastore-emulator google-cloud-cli-spanner-emulator google-cloud-cli-app-engine-go google-cloud-cli-app-engine-python-extras google-cloud-cli-config-connector google-cloud-cli-package-go-module google-cloud-cli-istioctl google-cloud-cli-anthos-auth google-cloud-cli-gke-gcloud-auth-plugin google-cloud-cli-app-engine-grpc google-cloud-cli-kubectl-oidc google-cloud-cli-terraform-tools google-cloud-cli-nomos google-cloud-cli-local-extract google-cloud-cli-firestore-emulator google-cloud-cli-harbourbridge google-cloud-cli-log-streaming google-cloud-cli-minikube google-cloud-cli-app-engine-java google-cloud-cli-enterprise-certificate-proxy google-cloud-cli

تفعيل Spanner API

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

gcloud config get-value project

gcloud config set project [YOUR-DESIRED-PROJECT-ID]

اضبط منطقتك التلقائية على us-central1. يمكنك تغيير هذه المنطقة إلى منطقة أخرى تتيحها الإعدادات الإقليمية في Spanner.

gcloud config set compute/region us-central1

فعِّل Spanner API:

gcloud services enable spanner.googleapis.com

إنشاء مثيل Spanner

في هذا القسم، ستنشئ إما مثيلاً تجريبيًا مجانيًا أو مثيلاً تم توفيره. في جميع مراحل هذا الدرس التطبيقي، يكون معرّف مثيل "محوّل Spanner Cassandra" المستخدَم هو cassandra-adapter-demo، ويتم ضبطه كمتغير SPANNER_INSTANCE_ID باستخدام سطر الأوامر export. يمكنك اختياريًا اختيار اسم معرّف المثيل.

إنشاء مثيل Spanner لفترة تجريبية مجانية

يتوفّر مثيل تجريبي مجاني من Spanner لمدة 90 يومًا لأي مستخدم لديه حساب Google وتم تفعيل Cloud Billing في مشروعه. لن يتم تحصيل أي رسوم منك إلا إذا اخترت ترقية مثيل الفترة التجريبية المجانية إلى مثيل مدفوع. يتوفّر Spanner Cassandra Adapter في مثيل الفترة التجريبية المجانية. إذا كنت مؤهَّلاً، أنشئ مثيلاً تجريبيًا مجانيًا من خلال فتح Cloud Shell وتنفيذ الأمر التالي:

export SPANNER_INSTANCE_ID=cassandra-adapter-demo
export SPANNER_REGION=regional-us-central1
gcloud spanner instances create $SPANNER_INSTANCE_ID \
  --config=$SPANNER_REGION \
  --instance-type=free-instance \
  --description="Spanner Cassandra Adapter demo"

ناتج الأمر:

gcloud spanner instances create $SPANNER_INSTANCE_ID \
  --config=$SPANNER_REGION \
  --instance-type=free-instance \
  --description="Spanner Cassandra Adapter demo"
Creating instance...done.

5- نقل مخطط Cassandra ونموذج البيانات إلى Spanner

تتضمّن المرحلة الأولية والحاسمة لنقل البيانات من قاعدة بيانات Cassandra إلى Spanner تحويل مخطط Cassandra الحالي ليتوافق مع متطلبات البنية وأنواع البيانات في Spanner.

لتبسيط عملية نقل المخطط المعقّدة هذه، استخدِم إحدى أداتَي المصدر المفتوح القيّمتَين اللتين يوفّرهما Spanner:

  1. أداة نقل البيانات في Spanner: تساعدك هذه الأداة في نقل المخطط من خلال الاتصال بقاعدة بيانات Cassandra حالية ونقل المخطط إلى Spanner. تتوفّر هذه الأداة كجزء من gcloud cli.
  2. أداة مخطط Spanner Cassandra: تساعدك هذه الأداة في تحويل لغة تعريف البيانات (DDL) التي تم تصديرها من Cassandra إلى Spanner. يمكنك استخدام أيّ من هاتين الأداتَين في هذا الدرس العملي. في هذا الدرس العملي، سنستخدم "أداة نقل البيانات في Spanner" لنقل المخطط.

أداة نقل البيانات في Spanner

تساعد أداة نقل البيانات في Spanner في نقل المخطط من مصادر بيانات مختلفة، مثل MySQL وPostgres وCassandra وما إلى ذلك.

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

يُرجى العِلم أنّه في حال تشغيل spanner-migration-tool على Cloud Shell، قد لا يكون بإمكانه الوصول إلى عنوان IP الداخلي لجهاز Cassandra الظاهري. لذا، ننصحك بتنفيذ الأمر نفسه على الجهاز الافتراضي الذي ثبّت عليه Cassandra.

نفِّذ ما يلي على الجهاز الافتراضي الذي ثبّت عليه Cassandra.

تثبيت "أداة نقل البيانات في Spanner"

sudo apt-get update
sudo apt-get install --upgrade google-cloud-sdk-spanner-migration-tool

إذا واجهت أي مشاكل في التثبيت، يُرجى الرجوع إلى installing-spanner-migration-tool للاطّلاع على خطوات تفصيلية.

إعادة تحميل بيانات اعتماد Gcloud

gcloud auth login
gcloud auth application-default login

نقل المخطط

export CASSANDRA_HOST=`<ip address of the VM used as rpc_address above>`
export PROJECT=`<PROJECT_ID>`
gcloud alpha spanner migrate schema \
  --source=cassandra \
  --source-profile="host=${CASSANDRA_HOST},user=cassandra,password=cassandra,port=9042,keyspace=analytics,datacenter=datacenter1" \
  --target-profile="project=${PROJECT},instance=cassandra-adapter-demo,dbName=analytics" \
  --project=${PROJECT}

التحقّق من صحة عبارات DDL في Spanner

gcloud spanner databases ddl describe analytics --instance=cassandra-adapter-demo

في نهاية عملية نقل المخطط، يجب أن تكون نتيجة هذا الأمر كما يلي:

CREATE TABLE users (
  active BOOL OPTIONS (
    cassandra_type = 'boolean'
  ),
  id INT64 NOT NULL OPTIONS (
    cassandra_type = 'int'
  ),
  username STRING(MAX) OPTIONS (
    cassandra_type = 'text'
  ),
) PRIMARY KEY(id);

(اختياري) الاطّلاع على تعريف البيانات المحوَّل

يمكنك الاطّلاع على DDL المحوَّل وإعادة تطبيقه على Spanner (إذا كنت بحاجة إلى تغييرات إضافية).

cat `ls -t cassandra_*schema.ddl.txt  | head -n 1`

سيكون ناتج هذا الأمر

CREATE TABLE `users` (
        `active` BOOL OPTIONS (cassandra_type = 'boolean'),
        `id` INT64 NOT NULL  OPTIONS (cassandra_type = 'int'),
        `username` STRING(MAX) OPTIONS (cassandra_type = 'text'),
) PRIMARY KEY (`id`)

(اختياري) الاطّلاع على تقرير الإحالات الناجحة

cat `ls -t cassandra_*report.txt  | head -n 1`

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

6. تصدير بياناتك السابقة بشكل مجمّع

لإجراء عملية نقل البيانات المجمّعة، عليك تنفيذ ما يلي:

  1. توفير أو إعادة استخدام حزمة GCS حالية
  2. تحميل ملف إعداد Cassandra Driver إلى الحزمة
  3. ابدأ عملية النقل المجمّع.

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

توفير حزمة GCS

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

if [ -z ${CASSANDRA_BUCKET_NAME} ]; then
  export CASSANDRA_BUCKET_NAME="gs://cassandra-demo-$(date +%Y-%m-%d-%H-%M-%S)-$(head /dev/urandom | tr -dc a-z | head -c 20)"
  gcloud storage buckets create "${CASSANDRA_BUCKET_NAME}"
else
  echo "using existing bucket ${CASSANDRA_BUCKET_NAME}"
fi

إنشاء ملف إعداد برنامج التشغيل وتحميله

هنا، نحمّل ملف إعداد أساسيًا جدًا لبرنامج تشغيل Cassandra. يُرجى الرجوع إلى هذا الرابط لمعرفة التنسيق الكامل للملف.

# Configuration for the Cassandra instance and GCS bucket
INSTANCE_NAME="cassandra-origin"
ZONE="us-central1-a"
CASSANDRA_PORT="9042"

# Retrieve the internal IP address of the Cassandra instance
CASSANDRA_IP=$(gcloud compute instances describe "${INSTANCE_NAME}" \
    --format="get(networkInterfaces[0].networkIP)" \
    --zone="${ZONE}")

# Check if the IP was successfully retrieved
if [[ -z "${CASSANDRA_IP}" ]]; then
    echo "Error: Could not retrieve Cassandra instance IP."
    exit 1
fi

# Define the full contact point
CONTACT_POINT="${CASSANDRA_IP}:${CASSANDRA_PORT}"

# Create a temporary file with the specified content
TMP_FILE=$(mktemp)
cat <<EOF > "${TMP_FILE}"
# Reference configuration for the DataStax Java driver for Apache Cassandra®.
# This file is in HOCON format, see https://github.com/typesafehub/config/blob/master/HOCON.md.
datastax-java-driver {
  basic.contact-points = ["${CONTACT_POINT}"]
  basic.session-keyspace = analytics
  basic.load-balancing-policy.local-datacenter = datacenter1
  advanced.auth-provider {
    class = PlainTextAuthProvider
    username = cassandra
    password = cassandra
  }
}
EOF

# Upload the temporary file to the specified GCS bucket
if gsutil cp "${TMP_FILE}" "${CASSANDRA_BUCKET_NAME}/cassandra.conf"; then
    echo "Successfully uploaded ${TMP_FILE} to ${CASSANDRA_BUCKET_NAME}/cassandra.conf"

    # Concatenate (cat) the uploaded file from GCS
    echo "Displaying the content of the uploaded file:"
    gsutil cat "${CASSANDRA_BUCKET_NAME}/cassandra.conf"
else
    echo "Error: Failed to upload file to GCS."
fi

# Clean up the temporary file
rm "${TMP_FILE}"

تنفيذ عملية نقل بيانات مجمّعة

هذا نموذج أمر لتنفيذ عملية نقل مجمّعة لبياناتك إلى Spanner. بالنسبة إلى حالات الاستخدام الفعلي للإنتاج، عليك تعديل نوع الآلة وعددها وفقًا للمقياس والإنتاجية المطلوبَين. يُرجى الانتقال إلى README_Sourcedb_to_Spanner.md#cassandra-to-spanner-bulk-migration للاطّلاع على القائمة الكاملة بالخيارات.

gcloud dataflow flex-template run "sourcedb-to-spanner-flex-job" \
  --project "`gcloud config get-value project`" \
  --region "us-central1" \
  --max-workers "2" \
  --num-workers "1" \
  --worker-machine-type "e2-standard-8" \
  --template-file-gcs-location "gs://dataflow-templates-us-central1/latest/flex/Sourcedb_to_Spanner_Flex" \
  --additional-experiments="[\"disable_runner_v2\"]" \
  --parameters "sourceDbDialect=CASSANDRA" \
  --parameters "insertOnlyModeForSpannerMutations=true" \
  --parameters "sourceConfigURL=$CASSANDRA_BUCKET_NAME/cassandra.conf" \
  --parameters "instanceId=cassandra-adapter-demo" \
  --parameters "databaseId=analytics" \
  --parameters "projectId=`gcloud config get-value project`" \
  --parameters "outputDirectory=$CASSANDRA_BUCKET_NAME/output" \
  --parameters "batchSizeForSpannerMutations=1"

سيؤدي ذلك إلى إنشاء نتيجة مثل ما يلي. دوِّن id الذي تم إنشاؤه واستخدِمه للاستعلام عن حالة مهمة تدفّق البيانات.

job:
  createTime: '2025-08-08T09:41:09.820267Z'
  currentStateTime: '1970-01-01T00:00:00Z'
  id: 2025-08-08_02_41_09-17637291823018196600
  location: us-central1
  name: sourcedb-to-spanner-flex-job
  projectId: span-cloud-ck-testing-external
  startTime: '2025-08-08T09:41:09.820267Z'

نفِّذ الأمر أدناه للتحقّق من حالة المهمة وانتظِر إلى أن تتغيّر الحالة إلى JOB_STATE_DONE.

gcloud dataflow jobs describe --region=us-central1 <dataflow job id> | grep "currentState:"

في البداية، ستكون المهمة في حالة انتظار مثل

currentState: JOB_STATE_QUEUED

أثناء وضع المهمة في قائمة الانتظار أو تنفيذها، ننصحك بشدة باستكشاف صفحة Dataflow/Jobs في واجهة مستخدم Cloud Console لتتبُّع المهمة.

بعد الانتهاء، ستتغيّر حالة المهمة إلى:

currentState: JOB_STATE_DONE

7. توجيه تطبيقك إلى Spanner (عملية الانتقال)

بعد التحقّق بدقة من صحة بياناتك وسلامتها بعد مرحلة النقل، تتمثّل الخطوة الأساسية في نقل التركيز التشغيلي لتطبيقك من نظام Cassandra القديم إلى قاعدة بيانات Spanner التي تمّت تعبئتها حديثًا. يُشار إلى فترة الانتقال المهمة هذه عادةً باسم "التحويل".

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

باستخدام واجهة Spanner Cassandra، يتم تبسيط عملية الانتقال. يتضمّن ذلك في المقام الأول ضبط إعدادات تطبيقات العميل للاستفادة من Spanner Cassandra Client الأصلي في جميع تفاعلات البيانات. بدلاً من التواصل مع قاعدة بيانات Cassandra (المصدر)، ستبدأ تطبيقاتك في قراءة البيانات وكتابتها مباشرةً في Spanner (الهدف) بسلاسة. يتم عادةً تحقيق هذا التغيير الأساسي في الاتصال من خلال استخدام SpannerCqlSessionBuilder، وهو مكوّن رئيسي في مكتبة Spanner Cassandra Client يسهّل إنشاء اتصالات بمثيل Spanner. يؤدي ذلك إلى إعادة توجيه تدفّق بيانات تطبيقك بالكامل إلى Spanner.

بالنسبة إلى تطبيقات Java التي تستخدم مكتبة cassandra-java-driver حاليًا، لا يتطلّب دمج Spanner Cassandra Java Client سوى إجراء تغييرات بسيطة على عملية إعداد CqlSession.

الحصول على تبعية google-cloud-spanner-cassandra

لبدء استخدام Spanner Cassandra Client، عليك أولاً دمج التبعية في مشروعك. يتم نشر عناصر google-cloud-spanner-cassandra في Maven Central، ضِمن معرّف المجموعة com.google.cloud. أضِف التبعية الجديدة التالية ضمن القسم <dependencies> الحالي في مشروع Java. في ما يلي مثال مبسَّط على كيفية تضمين التبعية google-cloud-spanner-cassandra:

<!-- native Spanner Cassandra Client -->
<dependencies>
  <dependency>
    <groupId>com.google.cloud</groupId>
    <artifactId>google-cloud-spanner-cassandra</artifactId>
    <version>0.2.0</version>
  </dependency>
</dependencies>

تغيير إعدادات الاتصال للربط بـ Spanner

بعد إضافة التبعية اللازمة، تكون الخطوة التالية هي تغيير إعدادات الاتصال للربط بقاعدة بيانات Spanner.

يستخدم تطبيق نموذجي يتفاعل مع مجموعة Cassandra غالبًا رمزًا مشابهًا لما يلي لإنشاء اتصال:

CqlSession session = CqlSession.builder()
        .addContactPoint(new InetSocketAddress("127.0.0.1", 9042))
        .withLocalDatacenter("datacenter1")
        .withAuthCredentials("username", "password")
        .build();

لإعادة توجيه عملية الربط هذه إلى Spanner، عليك تعديل منطق إنشاء CqlSession. بدلاً من استخدام CqlSessionBuilder العادية مباشرةً من cassandra-java-driver، ستستخدم SpannerCqlSession.builder() التي يوفّرها Spanner Cassandra Client. في ما يلي مثال توضيحي على كيفية تعديل رمز الربط:

String databaseUri = "projects/<your-gcp-project>/instances/<your-spanner-instance>/databases/<your-spanner-database>";

CqlSession session = SpannerCqlSession.builder()
        .setDatabaseUri(databaseUri)
        .addContactPoint(new InetSocketAddress("localhost", 9042))
        .withLocalDatacenter("datacenter1")
        .build();

من خلال إنشاء مثيل CqlSession باستخدام SpannerCqlSession.builder() وتقديم databaseUri الصحيح، سيتمكّن تطبيقك الآن من إنشاء اتصال من خلال Spanner Cassandra Client بقاعدة بيانات Spanner المستهدَفة. يضمن هذا التغيير المحوري توجيه جميع عمليات القراءة والكتابة اللاحقة التي ينفّذها تطبيقك إلى Spanner وخدمتها من خلاله، ما يؤدي إلى إكمال عملية النقل الأولية بشكل فعّال. في هذه المرحلة، من المفترض أن يستمر تطبيقك في العمل على النحو المتوقّع، ولكن الآن سيستفيد من قابلية التوسّع والموثوقية التي توفّرها Spanner.

الخيارات المتقدّمة: طريقة عمل برنامج Spanner Cassandra Client

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

26D34akkBHcMFFe.png

بعد التأكّد من أنّ Spanner يعالج جميع الزيارات بشكل صحيح، يمكنك في النهاية إجراء ما يلي:

  • إيقاف تشغيل مجموعة Cassandra الأصلية

8. التنظيف (اختياري)

لإجراء عملية التنظيف، ما عليك سوى الانتقال إلى قسم Spanner في Cloud Console وحذف مثيل cassandra-adapter-demo الذي أنشأناه في برنامج التدريب العملي.

76D34akkJRcMFMr.png

حذف قاعدة بيانات Cassandra (في حال تثبيتها محليًا أو استمرارها)

إذا ثبّت Cassandra خارج جهاز Compute Engine الظاهري الذي تم إنشاؤه هنا، اتّبِع الخطوات المناسبة لإزالة البيانات أو إلغاء تثبيت Cassandra.

9- تهانينا!

ما هي الخطوات التالية؟