این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

برنامه Spring Boot با Cloud Spanner

۱. مرور کلی

Cloud Spanner یک RDBMS با دسترسی بالا، مقیاس‌پذیر افقی و چند منطقه‌ای است. این آزمایشگاه کد از کوچکترین نمونه Cloud Spanner استفاده خواهد کرد، اما فراموش نکنید که پس از اتمام کار، آن را خاموش کنید!

آنچه یاد خواهید گرفت

نحوه استفاده از Cloud Spanner برای ذخیره و بازیابی داده‌ها با Spring Boot

آنچه نیاز دارید

یک پروژه پلتفرم ابری گوگل
یک مرورگر، مانند کروم یا فایرفاکس

چگونه از این آموزش استفاده خواهید کرد؟

فقط تا انتها بخوانید

آن را بخوانید و تمرین‌ها را انجام دهید

تجربه خود را در استفاده از خدمات پلتفرم ابری گوگل چگونه ارزیابی می‌کنید؟

تازه کار

متوسط

ماهر

۲. تنظیمات و الزامات

تنظیم محیط خودتنظیم

وارد Cloud Console شوید و یک پروژه جدید ایجاد کنید یا از یک پروژه موجود دوباره استفاده کنید. (اگر از قبل حساب Gmail یا G Suite ندارید، باید یکی ایجاد کنید .)

dMbN6g9RawQj_VXCSYpdYncY-DbaRzr2GbnwoV7jFf1u3avxJtmGPmKpMYgiaMH-qu80a_NJ9p2IIXFppYk8x3wyymZXavjglNLJJhuXieCem56H30hwXtd8PvXGpXJO9gEUDu3cZw

ci9Oe6PgnbNuSYlMyvbXF1JdQyiHoEgnhl4PlV_MFagm2ppzhueRkqX4eLjJllZco_2zCp0V0bpTupUSKji9KkQyWqj11pqit1K1faS1V6aTQz5GpG0T

8-tA_Lheyo8SscAVKrGii2coplQp2_D1Iosb2ViABY0UUO1A8cimXUu6Wf1R9zJIRExL5 OB2j946aIiFtyKTzxDcNnuznmR45vZ2HMoK3o67jxuoUJCAnqvEX6NgPGFjCVNgASc-lg

شناسه پروژه را به خاطر بسپارید، یک نام منحصر به فرد در تمام پروژه‌های Google Cloud (نام بالا قبلاً گرفته شده و برای شما کار نخواهد کرد، متاسفیم!). بعداً در این آزمایشگاه کد به آن PROJECT_ID گفته خواهد شد.

در مرحله بعد، برای استفاده از منابع گوگل کلود، باید پرداخت را در Cloud Console فعال کنید .

اجرای این آزمایشگاه کد، اگر اصلاً هزینه‌ای نداشته باشد، نباید هزینه زیادی داشته باشد. حتماً دستورالعمل‌های بخش «پاکسازی» را که به شما نحوه خاموش کردن منابع را آموزش می‌دهد، دنبال کنید تا پس از این آموزش، متحمل هزینه نشوید. کاربران جدید Google Cloud واجد شرایط برنامه آزمایشی رایگان ۳۰۰ دلاری هستند.

فعال کردن پوسته ابری

از کنسول ابری، روی فعال کردن پوسته ابری کلیک کنید .

zlNW0HehB_AFW1qZ4AyebSQUdWm95n7TbnOr7UVm3j9dFcg6oWApJRlC0jnU1Mvb-IQp-trP1Px8xKNwt6o3pP6fyih947sEhOFI4IRF0W7WZk6hFqZDUGXQQXrw21GuMm2ecHrbzQ

اگر قبلاً Cloud Shell را شروع نکرده‌اید، یک صفحه میانی (در زیر صفحه) به شما نمایش داده می‌شود که توضیح می‌دهد چیست. در این صورت، روی ادامه کلیک کنید (و دیگر هرگز آن را نخواهید دید). آن صفحه یکبار مصرف به این شکل است:

kEPbNAo_w5C_pi9QvhFwWwky1cX8hr_xEMGWySNIoMCdi-Djx9AQRqWn-__DmEpC7vKgUtl-feTcv-wBxJ8NwzzAp7mY65-fi2LJo4twUoewT1SUjd6Y3h81RG3rKIkqhoVlFR-G7w

آماده‌سازی و اتصال به Cloud Shell فقط چند لحظه طول می‌کشد.

pTv5mEKzWMWp5VBrg2eGcuRPv9dLInPToS-mohlrqDASyYGWnZ_SwE-MzOWHe76ZdCSmw0kgWogSJv27lrQE8pvA5OD6P1I47nz8vrAdK7yR1NseZKJvcxAZrPb8wRxoqyTpD-gbhA

این ماشین مجازی با تمام ابزارهای توسعه‌ای که نیاز دارید، مجهز شده است. این ماشین یک دایرکتوری خانگی ۵ گیگابایتی پایدار ارائه می‌دهد و در فضای ابری گوگل اجرا می‌شود که عملکرد شبکه و احراز هویت را تا حد زیادی بهبود می‌بخشد. بخش عمده‌ای از کار شما در این آزمایشگاه کد، اگر نگوییم همه، را می‌توان به سادگی با یک مرورگر یا کروم‌بوک انجام داد.

پس از اتصال به Cloud Shell، باید ببینید که از قبل احراز هویت شده‌اید و پروژه از قبل روی شناسه پروژه شما تنظیم شده است.

برای تأیید احراز هویت، دستور زیر را در Cloud Shell اجرا کنید:

gcloud auth list

خروجی دستور

 Credentialed Accounts
ACTIVE  ACCOUNT
*       <my_account>@<my_domain.com>

To set the active account, run:
    $ gcloud config set account `ACCOUNT`

gcloud config list project

خروجی دستور

[core]
project = <PROJECT_ID>

اگر اینطور نیست، می‌توانید با این دستور آن را تنظیم کنید:

gcloud config set project <PROJECT_ID>

خروجی دستور

Updated property [core/project].

۳. مقداردهی اولیه Cloud Spanner

فعال کردن Cloud Spanner API با استفاده از gcloud CLI:

gcloud services enable spanner.googleapis.com

یک نمونه Cloud Spanner ایجاد کنید:

gcloud spanner instances create spanner-instance \
 --config=regional-us-central1 \
 --nodes=1 --description="A Spanner Instance"

یک پایگاه داده درون نمونه ایجاد کنید:

gcloud spanner databases create orders \
  --instance=spanner-instance

یک فایل schema.ddl برای توصیف طرحواره داده ایجاد کنید:

cat << EOF > schema.ddl
CREATE TABLE orders (
  order_id STRING(36) NOT NULL,
  description STRING(255),
  creation_timestamp TIMESTAMP,
) PRIMARY KEY (order_id);

CREATE TABLE order_items (
  order_id STRING(36) NOT NULL,
  order_item_id STRING(36) NOT NULL,
  description STRING(255),
  quantity INT64,
) PRIMARY KEY (order_id, order_item_id),
  INTERLEAVE IN PARENT orders ON DELETE CASCADE;
EOF

طرحواره را به پایگاه داده Cloud Spanner اعمال کنید:

gcloud spanner databases ddl update orders \
  --instance=spanner-instance \
  --ddl="$(<schema.ddl)"

۴. بوت‌استرپ کردن یک برنامه جاوای Spring Boot جدید

از محیط Cloud Shell، از دستور زیر برای مقداردهی اولیه و بوت‌استرپ کردن یک برنامه Spring Boot جدید استفاده کنید:

$ curl https://start.spring.io/starter.tgz \
  -d packaging=jar \
  -d dependencies=cloud-gcp,web,lombok \
  -d baseDir=spanner-example \
  -d type=maven-project \
  -d bootVersion=3.2.6 | tar -xzvf -

$ cd spanner-example

این دستور یک دایرکتوری جدید spanner-example/ با یک پروژه جدید Maven، به همراه pom.xml از Maven، یک بسته‌بندی Maven و همچنین یک نقطه ورود به برنامه ایجاد می‌کند.

در فایل pom.xml ، شروع‌کننده‌ی Spring Data Cloud Spanner را اضافه کنید.

مثال-spanner/pom.xml

<project>
  ...
  <dependencies>
        ...
        <!-- Add Spring Cloud GCP Spanner Starter -->
        <dependency>
                <groupId>com.google.cloud</groupId>
                <artifactId>spring-cloud-gcp-starter-data-spanner</artifactId>
        </dependency>

        ...

  </dependencies>

  ...
</project>

در application.properties، اطلاعات اتصال پایگاه داده Spanner را پیکربندی کنید:

spanner-example/src/main/resources/application.properties

spring.cloud.gcp.spanner.instance-id=spanner-instance
spring.cloud.gcp.spanner.database=orders

مطمئن شوید که JAVA_HOME روی نسخه صحیح تنظیم شده است:

export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64/

برای اطمینان از صحت پیکربندی Maven، برنامه را مجدداً بسازید:

./mvnw package

۵. ایجاد موجودیت‌ها

با پشتیبانی Spring Data Spanner در Spring Cloud GCP، می‌توانید به راحتی یک شیء جاوا و نگاشت ORM اصطلاحی را با استفاده از Spring Data به یک جدول Spanner ایجاد کنید.

ابتدا، یک کلاس Order Item ایجاد کنید.

spanner-example/src/main/java/com/example/demo/OrderItem.java

package com.example.demo;

import com.google.cloud.spring.data.spanner.core.mapping.Column;
import com.google.cloud.spring.data.spanner.core.mapping.PrimaryKey;
import com.google.cloud.spring.data.spanner.core.mapping.Table;

@Table(name="order_items")
@Data
class OrderItem {
  @PrimaryKey(keyOrder = 1)
  @Column(name="order_id")
  private String orderId;

  @PrimaryKey(keyOrder = 2)
  @Column(name="order_item_id")
  private String orderItemId;

  private String description;
  private Long quantity;
}

برای روابط والد/فرزند در Spanner، باید از یک کلید اصلی مرکب استفاده کنید. در این مثال، کلید مرکب order_id و order_item_id است.

سپس، یک کلاس Order ایجاد کنید:

spanner-example/src/main/java/com/example/demo/Order.java

package com.example.demo;

import java.time.LocalDateTime;
import java.util.List;
import lombok.Data;
import com.google.cloud.spring.data.spanner.core.mapping.Column;
import com.google.cloud.spring.data.spanner.core.mapping.Interleaved;
import com.google.cloud.spring.data.spanner.core.mapping.PrimaryKey;
import com.google.cloud.spring.data.spanner.core.mapping.Table;

@Table(name="orders")
@Data
public class Order {
  @PrimaryKey
  @Column(name="order_id")
  private String id;

  private String description;

  @Column(name="creation_timestamp")
  private LocalDateTime timestamp;

  @Interleaved
  private List<OrderItem> items;
}

این کلاس از حاشیه‌نویسی @Interleaved برای ایجاد یک رابطه یک به چند با اقلام سفارش استفاده می‌کند.

۶. رابط OrderRepository را ایجاد کنید

کلاس OrderRepository را با محتوای زیر ایجاد کنید:

spanner-example/src/main/java/com/example/demo/OrderRepository.java

package com.example.demo;

import com.google.cloud.spring.data.spanner.repository.SpannerRepository;
import org.springframework.stereotype.Repository;

@Repository
public interface OrderRepository extends SpannerRepository<Order, String> {
}

این رابط از SpannerRepository<Order, String> ارث‌بری می‌کند که در آن Order کلاس دامنه و String نوع کلید اصلی است. Spring Data به طور خودکار دسترسی CRUD را از طریق این رابط فراهم می‌کند و نیازی به ایجاد هیچ کد اضافی نخواهید داشت.

۷. یک کنترلر REST برای عملیات پایه ایجاد کنید

کلاس DemoApplication برنامه اصلی را باز کنید و آن را به شکل زیر تغییر دهید:

spanner-example/src/main/java/com/example/demo/DemoApplication.java

package com.example.demo;

import java.time.LocalDateTime;
import java.util.UUID;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.http.HttpStatus;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.server.ResponseStatusException;

@SpringBootApplication
public class DemoApplication {
        public static void main(String[] args) {
                SpringApplication.run(DemoApplication.class, args);
        }
}

@RestController
class OrderController {
  private final OrderRepository orderRepository;

        OrderController(OrderRepository orderRepository) {
                this.orderRepository = orderRepository;
        }

        @GetMapping("/api/orders/{id}")
        public Order getOrder(@PathVariable String id) {
          return orderRepository.findById(id)
                                .orElseThrow(() -> new ResponseStatusException(HttpStatus.NOT_FOUND, id + " not found"));
        }

        @PostMapping("/api/orders")
        public String createOrder(@RequestBody Order order) {
                // Spanner currently does not auto generate IDs
                // Generate UUID on new orders
                order.setId(UUID.randomUUID().toString());
                order.setTimestamp(LocalDateTime.now());

                order.getItems().forEach(item -> {
                        // Assign parent ID, and also generate child ID
                        item.setOrderId(order.getId());
                        item.setOrderItemId(UUID.randomUUID().toString());
                });

          Order saved = orderRepository.save(order);
          return saved.getId();
        }
}

۸. برنامه را اجرا کنید

برنامه را بازسازی و اجرا کنید!

./mvnw spring-boot:run

این باید به درستی شروع شود و روی پورت ۸۰۸۰ گوش دهد.

شما می‌توانید یک رکورد سفارش (Order) را به نقطه پایانی ارسال کنید:

curl -H"Content-Type: application/json" -d'{"description": "My orders", "items": [{"description": "Android Phone", "quantity": "1"}]}' \
  http://localhost:8080/api/orders

باید با UUID سفارش پاسخ دهد.

سپس می‌توانید سفارش را با UUID بازیابی کنید:

curl http://localhost:8080/api/orders/REPLACE_WITH_ORDER_UUID

برای مشاهده نحوه ذخیره داده‌ها در Cloud Spanner، به Cloud Console بروید و به مسیر Spanner → Spanner Instance → order database → orders table → Data بروید.

۹. تمیز کردن

برای پاکسازی، نمونه‌ی Spanner را حذف کنید تا دیگر هزینه‌ای ایجاد نکند!

gcloud spanner instances delete spanner-instance -q

۱۰. تبریک می‌گویم!

در این آزمایشگاه کد، شما یک برنامه CLI تعاملی ایجاد کرده‌اید که می‌تواند داده‌ها را از Cloud Spanner ذخیره و بازیابی کند!

اطلاعات بیشتر

کلود اسپنر: https://cloud.google.com/spanner/
پروژه Spring روی GCP: https://googlecloudplatform.github.io/spring-cloud-gcp/reference/html/
مخزن گیت‌هاب اسپرینگ روی GCP: https://github.com/spring-cloud/spring-cloud-gcp
جاوا در پلتفرم ابری گوگل: https://cloud.google.com/java/

مجوز

این اثر تحت مجوز عمومی Creative Commons Attribution 2.0 منتشر شده است.