۱. مرور کلی
Spanner یک سرویس پایگاه داده توزیعشده جهانی، کاملاً مدیریتشده، مقیاسپذیر افقی و مناسب برای بارهای کاری عملیاتی رابطهای و غیررابطهای است. Spanner فراتر از قابلیتهای اصلی خود، ویژگیهای پیشرفته و قدرتمندی را ارائه میدهد که امکان ساخت برنامههای هوشمند و دادهمحور را فراهم میکند.
این آزمایشگاه کد بر اساس درک بنیادی Spanner بنا شده و با استفاده از یک برنامه بانکداری آنلاین به عنوان پایه، به استفاده از ادغامهای پیشرفته آن برای افزایش پردازش دادهها و قابلیتهای تحلیلی شما میپردازد.
ما بر روی سه ویژگی پیشرفته کلیدی تمرکز خواهیم کرد:
- ادغام هوش مصنوعی ورتکس : نحوه ادغام یکپارچه Spanner با پلتفرم هوش مصنوعی گوگل کلود، Vertex AI، را کشف کنید. شما یاد خواهید گرفت که چگونه مدلهای هوش مصنوعی ورتکس را مستقیماً از درون کوئریهای SQL اسپنر فراخوانی کنید، که امکان تبدیلها و پیشبینیهای قدرتمند درون پایگاه داده را فراهم میکند و به برنامه بانکی ما اجازه میدهد تا به طور خودکار تراکنشها را برای موارد استفاده مانند ردیابی بودجه و تشخیص ناهنجاری دستهبندی کند.
- جستجوی متن کامل : یاد بگیرید که چگونه قابلیت جستجوی متن کامل را در Spanner پیادهسازی کنید. شما با نمایهسازی دادههای متنی و نوشتن پرسوجوهای کارآمد برای انجام جستجوهای مبتنی بر کلمات کلیدی در دادههای عملیاتی خود آشنا خواهید شد و امکان کشف قدرتمند دادهها، مانند یافتن کارآمد مشتریان از طریق آدرس ایمیل در سیستم بانکی ما را فراهم میکنید.
- پرسوجوهای فدرال BigQuery : بررسی کنید که چگونه از قابلیتهای پرسوجوی فدرال Spanner برای پرسوجوی مستقیم از دادههای موجود در BigQuery استفاده کنید. این به شما امکان میدهد دادههای عملیاتی بلادرنگ Spanner را با مجموعه دادههای تحلیلی BigQuery ترکیب کنید تا بینشها و گزارشهای جامعی بدون تکرار دادهها یا فرآیندهای پیچیده ETL داشته باشید و موارد استفاده مختلف را در برنامه بانکی خود مانند کمپینهای بازاریابی هدفمند با ترکیب دادههای بلادرنگ مشتری با روندهای تاریخی گستردهتر از BigQuery تقویت کنید.
آنچه یاد خواهید گرفت
- نحوه تنظیم یک نمونه Spanner.
- نحوه ایجاد پایگاه داده و جداول.
- نحوه بارگذاری دادهها در جداول پایگاه داده Spanner.
- نحوه فراخوانی مدلهای هوش مصنوعی Vertex از Spanner.
- نحوه پرس و جو در پایگاه داده Spanner با استفاده از جستجوی فازی و جستجوی متن کامل.
- نحوه انجام کوئریهای فدرال علیه Spanner از BigQuery.
- چگونه نمونه Spanner خود را حذف کنیم.
آنچه نیاز دارید
۲. تنظیمات و الزامات
ایجاد یک پروژه
اگر از قبل یک پروژه گوگل کلود با قابلیت پرداخت فعال دارید، روی منوی کشویی انتخاب پروژه در سمت چپ بالای کنسول کلیک کنید:

با یک پروژه انتخاب شده، از بخش فعال کردن API های مورد نیاز (Enable the required APIs) صرف نظر کنید.
اگر از قبل حساب گوگل (جیمیل یا برنامههای گوگل) ندارید، باید یکی ایجاد کنید . وارد کنسول پلتفرم ابری گوگل ( console.cloud.google.com ) شوید و یک پروژه جدید ایجاد کنید.
برای ایجاد یک پروژه جدید، روی دکمه "NEW PROJECT" در کادر محاورهای ظاهر شده کلیک کنید:

اگر از قبل پروژهای ندارید، باید پنجرهای مانند این را برای ایجاد اولین پروژه خود ببینید:

پنجرهی بعدیِ ایجاد پروژه به شما امکان میدهد جزئیات پروژهی جدید خود را وارد کنید.
شناسه پروژه را به خاطر بسپارید، که یک نام منحصر به فرد در تمام پروژههای Google Cloud است. بعداً در این آزمایشگاه کد به عنوان PROJECT_ID به آن اشاره خواهد شد.

در مرحله بعد، اگر قبلاً این کار را نکردهاید، باید صورتحساب را در کنسول توسعهدهندگان فعال کنید تا بتوانید از منابع Google Cloud استفاده کنید و Spanner API ، Vertex AI API ، BigQuery API و BigQuery Connection API را فعال کنید.

قیمتگذاری آچار فرانسه در اینجا مستند شده است. سایر هزینههای مرتبط با سایر منابع در صفحات قیمتگذاری خاص خود مستند خواهند شد.
کاربران جدید پلتفرم ابری گوگل واجد شرایط دریافت یک دوره آزمایشی رایگان ۳۰۰ دلاری هستند.
راهاندازی پوسته ابری گوگل
در این آزمایشگاه کد، ما از Google Cloud Shell ، یک محیط خط فرمان که در فضای ابری اجرا میشود، استفاده خواهیم کرد.
این ماشین مجازی مبتنی بر دبیان، تمام ابزارهای توسعه مورد نیاز شما را در خود جای داده است. این ماشین مجازی یک دایرکتوری خانگی دائمی ۵ گیگابایتی ارائه میدهد و در فضای ابری گوگل اجرا میشود که عملکرد شبکه و احراز هویت را تا حد زیادی بهبود میبخشد. این بدان معناست که تنها چیزی که برای این آزمایشگاه کد نیاز دارید، یک مرورگر است.
برای فعال کردن Cloud Shell از کنسول Cloud، کافیست روی Activate Cloud Shell کلیک کنید.
(فقط چند لحظه طول میکشد تا آماده شود و به محیط متصل شود).

پس از اتصال به Cloud Shell، باید ببینید که از قبل احراز هویت شدهاید و پروژه از قبل روی PROJECT_ID شما تنظیم شده است.
gcloud auth list
خروجی مورد انتظار:
Credentialed Accounts ACTIVE: * ACCOUNT: <myaccount>@<mydomain>.com
gcloud config list project
خروجی مورد انتظار:
[core] project = <PROJECT_ID>
اگر به هر دلیلی پروژه تنظیم نشده باشد، دستور زیر را اجرا کنید:
gcloud config set project <PROJECT_ID>
به دنبال PROJECT_ID خود هستید؟ بررسی کنید که در مراحل راهاندازی از چه شناسهای استفاده کردهاید یا آن را در داشبورد Cloud Console جستجو کنید:

Cloud Shell همچنین برخی از متغیرهای محیطی را به طور پیشفرض تنظیم میکند که ممکن است هنگام اجرای دستورات بعدی مفید باشند.
echo $GOOGLE_CLOUD_PROJECT
خروجی مورد انتظار:
<PROJECT_ID>
فعال کردن API های مورد نیاز
APIهای Spanner، Vertex AI و BigQuery را برای پروژه خود فعال کنید:
gcloud services enable spanner.googleapis.com
gcloud services enable aiplatform.googleapis.com
gcloud services enable bigquery.googleapis.com
gcloud services enable bigqueryconnection.googleapis.com
خلاصه
در این مرحله، اگر پروژهای نداشتید، آن را راهاندازی کردهاید، Cloud Shell را فعال کردهاید و APIهای مورد نیاز را فعال کردهاید.
بعدی
در مرحله بعد، نمونه Spanner را تنظیم خواهید کرد.
۳. راهاندازی یک نمونه Spanner
نمونه Spanner را ایجاد کنید
در این مرحله، شما یک نمونه Spanner برای codelab تنظیم خواهید کرد. برای انجام این کار، Cloud Shell را باز کنید و این دستور را اجرا کنید:
export SPANNER_INSTANCE=cloudspanner-onlinebanking
gcloud spanner instances create $SPANNER_INSTANCE \
--config=regional-us-central1 \
--description="Spanner Online Banking" \
--nodes=1 \
--edition=ENTERPRISE \
--default-backup-schedule-type=NONE
خروجی مورد انتظار:
Creating instance...done.
خلاصه
در این مرحله، شما نمونه Spanner را ایجاد کردهاید.
بعدی
در مرحله بعد، برنامه اولیه را آماده کرده و پایگاه داده و طرحواره را ایجاد خواهید کرد.
۴. ایجاد پایگاه داده و طرحواره
آماده سازی درخواست اولیه
در این مرحله، پایگاه داده و طرحواره را از طریق کد ایجاد خواهید کرد.
ابتدا، با استفاده از Maven یک برنامه جاوا با نام onlinebanking ایجاد کنید:
mvn -B archetype:generate \
-DarchetypeGroupId=org.apache.maven.archetypes \
-DgroupId=com.google.codelabs \
-DartifactId=onlinebanking \
-DjavaCompilerVersion=1.8 \
-DjunitVersion=4.13.2 \
-DarchetypeVersion=1.5
فایلهای دادهای که به پایگاه داده اضافه خواهیم کرد را بررسی و کپی کنید (برای مشاهده مخزن کد اینجا را ببینید):
git clone https://github.com/GoogleCloudPlatform/cloud-spanner-samples.git
cp -r ./cloud-spanner-samples/banking/data ./onlinebanking
به پوشه برنامه بروید:
cd onlinebanking
فایل pom.xml مربوط به Maven را باز کنید. بخش مدیریت وابستگیها را اضافه کنید تا بتوانید از Maven BOM برای مدیریت نسخه کتابخانههای Google Cloud استفاده کنید:
<dependencyManagement>
<dependencies>
<dependency>
<groupId>com.google.cloud</groupId>
<artifactId>libraries-bom</artifactId>
<version>26.56.0</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
ویرایشگر و فایل به این شکل خواهند بود: 
مطمئن شوید که بخش dependencies شامل کتابخانههایی است که برنامه از آنها استفاده خواهد کرد:
<dependencies>
<dependency>
<groupId>junit</groupId>
<artifactId>junit</artifactId>
<version>4.13.2</version>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.slf4j</groupId>
<artifactId>slf4j-nop</artifactId>
<version>2.0.9</version>
</dependency>
<dependency>
<groupId>com.opencsv</groupId>
<artifactId>opencsv</artifactId>
<version>5.10</version>
</dependency>
<dependency>
<groupId>com.google.cloud</groupId>
<artifactId>google-cloud-spanner</artifactId>
</dependency>
<dependency>
<groupId>com.google.cloud</groupId>
<artifactId>google-cloud-bigquery</artifactId>
</dependency>
<dependency>
<groupId>com.google.cloud</groupId>
<artifactId>google-cloud-bigqueryconnection</artifactId>
</dependency>
</dependencies>
در نهایت، افزونههای ساخت را جایگزین کنید تا برنامه در یک JAR قابل اجرا بستهبندی شود:
<build>
<plugins>
<plugin>
<artifactId>maven-resources-plugin</artifactId>
<version>3.3.1</version>
<executions>
<execution>
<id>copy-resources</id>
<phase>process-resources</phase>
<goals>
<goal>copy-resources</goal>
</goals>
<configuration>
<outputDirectory>${project.build.directory}/${project.artifactId}-resources</outputDirectory>
<resources>
<resource>
<directory>resources</directory>
<filtering>true</filtering>
</resource>
</resources>
</configuration>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-dependency-plugin</artifactId>
<version>3.8.1</version>
<executions>
<execution>
<id>copy-dependencies</id>
<phase>prepare-package</phase>
<goals>
<goal>copy-dependencies</goal>
</goals>
<configuration>
<outputDirectory>${project.build.directory}/${project.artifactId}-resources/lib</outputDirectory>
<overWriteReleases>false</overWriteReleases>
<overWriteSnapshots>false</overWriteSnapshots>
<overWriteIfNewer>true</overWriteIfNewer>
</configuration>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-jar-plugin</artifactId>
<version>3.4.2</version>
<configuration>
<finalName>${project.artifactId}</finalName>
<outputDirectory>${project.build.directory}</outputDirectory>
<archive>
<index>false</index>
<manifest>
<mainClass>com.google.codelabs.App</mainClass>
<addClasspath>true</addClasspath>
<classpathPrefix>${project.artifactId}-resources/lib/</classpathPrefix>
</manifest>
</archive>
</configuration>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-failsafe-plugin</artifactId>
<version>3.2.5</version>
<executions>
<execution>
<goals>
<goal>integration-test</goal>
</goals>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<version>3.2.5</version>
<configuration>
<useSystemClassLoader>false</useSystemClassLoader>
</configuration>
</plugin>
</plugins>
</build>
با انتخاب «ذخیره» در منوی «فایل» ویرایشگر Cloud Shell یا با فشار دادن Ctrl+S ، تغییراتی را که در فایل pom.xml ایجاد کردهاید، ذخیره کنید.
اکنون که وابستگیها آماده هستند، کدی را به برنامه اضافه خواهید کرد تا یک طرحواره، برخی از شاخصها (از جمله جستجو) و یک مدل هوش مصنوعی متصل به یک نقطه پایانی از راه دور ایجاد کنید. شما بر اساس این مصنوعات، متدهای بیشتری را در طول این آزمایشگاه کد به این کلاس اضافه خواهید کرد.
App.java در مسیر onlinebanking/src/main/java/com/google/codelabs باز کنید و محتویات آن را با کد زیر جایگزین کنید:
package com.google.codelabs;
import java.util.Arrays;
import java.util.List;
import java.util.concurrent.ExecutionException;
import com.google.api.gax.longrunning.OperationFuture;
import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.spanner.Database;
import com.google.cloud.spanner.DatabaseAdminClient;
import com.google.cloud.spanner.DatabaseClient;
import com.google.cloud.spanner.DatabaseId;
import com.google.cloud.spanner.Spanner;
import com.google.cloud.spanner.SpannerException;
import com.google.cloud.spanner.SpannerExceptionFactory;
import com.google.cloud.spanner.SpannerOptions;
import com.google.spanner.admin.database.v1.CreateDatabaseMetadata;
public class App {
// Create the Spanner database and schema
public static void create(DatabaseAdminClient dbAdminClient, DatabaseId db,
String location, String model) {
System.out.println("Creating Spanner database...");
List<String> statements = Arrays.asList(
"CREATE TABLE Customers (\n"
+ " CustomerId INT64 NOT NULL,\n"
+ " FirstName STRING(256) NOT NULL,\n"
+ " LastName STRING(256) NOT NULL,\n"
+ " FullName STRING(512) AS (FirstName || ' ' || LastName) STORED,\n"
+ " Email STRING(512) NOT NULL,\n"
+ " EmailTokens TOKENLIST AS\n"
+ " (TOKENIZE_SUBSTRING(Email, ngram_size_min=>2, ngram_size_max=>3,\n"
+ " relative_search_types=>[\"all\"])) HIDDEN,\n"
+ " Address STRING(MAX)\n"
+ ") PRIMARY KEY (CustomerId)",
"CREATE INDEX CustomersByEmail