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

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

1. بررسی اجمالی

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

چیزی که یاد خواهید گرفت

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

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

یک پروژه Google Cloud Platform
یک مرورگر، مانند کروم یا فایرفاکس

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

فقط از طریق آن را بخوانید

آن را بخوانید و تمرینات را کامل کنید

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

تازه کار

متوسط

مسلط

2. راه اندازی و الزامات

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

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

dMbN6g9RawQj_VXCSYpdYncY-DbaRzr2GbnwoV7jFf1u3avxJtmGPmKpMYgiaMH-qu80a_NJ9p2IIXFppYk8x3wyymZXavjglNLJJHHXieCvXw5 Zw

ci9Oe6PgnbNuSYlMyvbXF1JdQyiHoEgnhl4PlV_MFagm2ppzhueRkqX4eLjJllZco_2zCp0V0bpTupUSKji9KkQyWqj11pqit1K1faS1V6aTQz5GpG0T

8-tA_Lheyo8SscAVKrGii2coplQp2_D1Iosb2ViABY0UUO1A8cimXUu6Wf1R9zJIRExL5OB2j946aIiFtyKTzxDcNnuznmR45vZ2HMoK3UUO1A8cimXUu6Wf1R9zJIRExL5OB2j946aIiFtyKTzxDcNnuznmR45vZ2HMoK3UUUO1A8cimXUu6Wf1R9zJIRExL5OB2j946aIiFtyKTzxDcNnuznmR45vZ2HMoK3UUUO1A8CXUF

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

در مرحله بعد، برای استفاده از منابع Google Cloud، باید صورت‌حساب را در Cloud Console فعال کنید .

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

Cloud Shell را فعال کنید

از Cloud Console، روی Activate Cloud Shell کلیک کنید .

zlNW0HehB_AFW1qZ4AyebSQUdWm95n7TbnOr7UVm3j9dFcg6oWApJRlC0jnU1Mvb-IQp-trP1Px8xKNwt6o3pP6fyih947sEhOFI4ZIRF6HQWQ2 rbzQ

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

kEPbNAo_w5C_pi9QvhFwWwky1cX8hr_xEMGWySNIoMCdi-Djx9AQRqWn-__DmEpC7vKgUtl-feTcv-wBxJ8NwzzAp7mY65-fi2LJo4tw1Uo6VRh1

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

pTv5mEKzWMWp5VBrg2eGcuRPv9dLInPToS-mohlrqDASyYGWnZ_SwE-MzOWHe76ZdCSmw0kgWogSJv27lrQE8pvA5OD6P1I47nz8vrAdK7PyGWnZ_SwE-MzOWHe76ZdCSmw0kgWogSJv27lrQE8pvA5OD6P1I47nz8vrAdK7PyGWnZ_SwE-MzOWHe76ZdCSmw0kgWogSJv27lrQE8pvA5OD6P1I47nz8vrAdK7PyRvcD

این ماشین مجازی با تمام ابزارهای توسعه که شما نیاز دارید بارگذاری شده است. این دایرکتوری اصلی 5 گیگابایتی دائمی را ارائه می دهد و در Google Cloud اجرا می شود و عملکرد شبکه و احراز هویت را بسیار افزایش می دهد. بیشتر، اگر نه همه، کار شما در این کد لبه را می توان به سادگی با یک مرورگر یا Chromebook انجام داد.

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

برای تایید احراز هویت، دستور زیر را در 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].

3. 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)"

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

از محیط 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 جدید، همراه با Maven's pom.xml ، یک پوشش Maven، و همچنین یک نقطه ورودی برنامه ایجاد می کند.

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

spanner-example/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

5. موجودیت ها را ایجاد کنید

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

ابتدا یک کلاس 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 است.

بعد، یک کلاس سفارش ایجاد کنید:

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 برای ایجاد رابطه یک به چند با موارد سفارش استفاده می کند.

6. رابط 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 را از طریق این رابط فراهم می کند و شما نیازی به ایجاد کد اضافی ندارید.

7. یک REST Controller برای عملیات اصلی ایجاد کنید

کلاس 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();
        }
}

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

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

./mvnw spring-boot:run

این باید به درستی شروع شود و در پورت 8080 گوش کند.

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

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 ← پایگاه داده سفارش → جدول سفارشات → Data بروید.

9. پاکسازی کنید

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

gcloud spanner instances delete spanner-instance -q

10. تبریک می گویم!

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

بیشتر بدانید

آچار ابری: https://cloud.google.com/spanner/
پروژه Spring on GCP: https://googlecloudplatform.github.io/spring-cloud-gcp/reference/html/
Spring در مخزن GCP GitHub: https://github.com/spring-cloud/spring-cloud-gcp
جاوا در Google Cloud Platform: https://cloud.google.com/java/

مجوز

این اثر تحت مجوز Creative Commons Attribution 2.0 Generic مجوز دارد.