‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

אפליקציית Spring Spanner עם שירות Cloud Spanner

1. סקירה כללית

‫Cloud Spanner הוא RDBMS זמין מאוד, ניתן להרחבה אופקית ופועל במספר אזורים.בשיעור Codelab הזה נשתמש במכונה הקטנה ביותר של Cloud Spanner, אבל אל תשכחו לכבות אותה בסיום!

מה תלמדו

איך משתמשים ב-Cloud Spanner כדי לשמור ולאחזר נתונים באמצעות Spring Boot

הדרישות

פרויקט ב-Google Cloud Platform
דפדפן, כמו Chrome או Firefox

איך תשתמשו במדריך הזה?

רק לקרוא

לקרוא ולבצע את התרגילים

איזה דירוג מגיע לדעתך לחוויית השימוש שלך בשירותים של Google Cloud Platform?

מתחילים

ביניים

מומחים

2. הגדרה ודרישות

הגדרת סביבה בקצב אישי

נכנסים אל Cloud Console ויוצרים פרויקט חדש או משתמשים בפרויקט קיים. (אם עדיין אין לכם חשבון Gmail או G Suite, אתם צריכים ליצור חשבון).

dMbN6g9RawQj_VXCSYpdYncY-DbaRzr2GbnwoV7jFf1u3avxJtmGPmKpMYgiaMH-qu80a_NJ9p2IIXFppYk8x3wyymZXavjglNLJJhuXieCem56H30hwXtd8PvXGpXJO9gEUDu3cZw ci9Oe6PgnbNuSYlMyvbXF1JdQyiHoEgnhl4PlV_MFagm2ppzhueRkqX4eLjJllZco_2zCp0V0bpTupUSKji9KkQyWqj11pqit1K1faS1V6aFxLGQdkuzGp4rsQTan7F01iePL5DtqQ 8-tA_Lheyo8SscAVKrGii2coplQp2_D1Iosb2ViABY0UUO1A8cimXUu6Wf1R9zJIRExL5OB2j946aIiFtyKTzxDcNnuznmR45vZ2HMoK3o67jxuoUJCAnqvEX6NgPGFjCVNgASc-lg

חשוב לזכור את מזהה הפרויקט, שהוא שם ייחודי בכל הפרויקטים ב-Google Cloud (השם שלמעלה כבר תפוס ולא יתאים לכם, מצטערים!). בהמשך ה-codelab הזה נתייחס אליו כאל PROJECT_ID.

לאחר מכן, תצטרכו להפעיל את החיוב ב-Cloud Console כדי להשתמש במשאבים של Google Cloud.

העלות של התרגול הזה לא אמורה להיות גבוהה, ואולי לא תהיה עלות בכלל. חשוב לפעול לפי ההוראות בקטע 'ניקוי' שבו מוסבר איך להשבית משאבים כדי שלא תחויבו אחרי שתסיימו את המדריך הזה. משתמשים חדשים ב-Google Cloud זכאים לתוכנית תקופת ניסיון בחינם בשווי ‎300 USD.

הפעלת Cloud Shell

ב-Cloud Console, לוחצים על Activate Cloud Shell .

zlNW0HehB_AFW1qZ4AyebSQUdWm95n7TbnOr7UVm3j9dFcg6oWApJRlC0jnU1Mvb-IQp-trP1Px8xKNwt6o3pP6fyih947sEhOFI4IRF0W7WZk6hFqZDUGXQQXrw21GuMm2ecHrbzQ

אם זו הפעם הראשונה שאתם מפעילים את Cloud Shell, יוצג לכם מסך ביניים (מתחת לקו הקיפול) עם תיאור של Cloud Shell. במקרה כזה, לוחצים על המשך (והמסך הזה לא יוצג לכם יותר). כך נראה המסך החד-פעמי:

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

יחלפו כמה רגעים עד שההקצאה והחיבור ל-Cloud Shell יושלמו.

pTv5mEKzWMWp5VBrg2eGcuRPv9dLInPToS-mohlrqDASyYGWnZ_SwE-MzOWHe76ZdCSmw0kgWogSJv27lrQE8pvA5OD6P1I47nz8vrAdK7yR1NseZKJvcxAZrPb8wRxoqyTpD-gbhA

המכונה הווירטואלית הזו כוללת את כל הכלים שדרושים למפתחים. יש בה ספריית בית בנפח מתמיד של 5GB והיא פועלת ב-Google Cloud, מה שמשפר מאוד את הביצועים והאימות של הרשת. אפשר לבצע את רוב העבודה ב-codelab הזה, אם לא את כולה, באמצעות דפדפן או Chromebook.

אחרי שמתחברים ל-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].

3. אתחול Cloud Spanner

מפעילים את Cloud Spanner API באמצעות ה-CLI של gcloud:

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 חדש, בנוסף ל-pom.xml של Maven, ל-Maven Wrapper ולנקודת כניסה לאפליקציה.

בקובץ pom.xml, מוסיפים את Spring Data Cloud Spanner starter.

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, אפשר ליצור בקלות אובייקט Java ומיפוי ORM אידיומטי לטבלת Spanner באמצעות Spring Data.

קודם כול, יוצרים מחלקה של פריט בהזמנה.

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 לפעולות בסיסיות

פותחים את המחלקה הראשית 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 ועוברים אל Spanner → Spanner Instance → order database → orders table → Data.

9. הסרת המשאבים

כדי לנקות, מוחקים את מופע Spanner כדי שלא יחויבו יותר על השימוש בו.

gcloud spanner instances delete spanner-instance -q

10. מעולה!

בשיעור Codelab הזה יצרתם אפליקציית CLI אינטראקטיבית שיכולה לאחסן ולאחזר נתונים מ-Cloud Spanner.

מידע נוסף

Cloud Spanner: ‏ https://cloud.google.com/spanner/
פרויקט Spring ב-GCP: ‏ https://googlecloudplatform.github.io/spring-cloud-gcp/reference/html/
מאגר GitHub של Spring ב-GCP: ‏ https://github.com/spring-cloud/spring-cloud-gcp
‫Java ב-Google Cloud Platform: ‏ https://cloud.google.com/java/

רישיון

העבודה הזו בשימוש במסגרת רישיון Creative Commons שמותנה בייחוס כללי מגרסה 2.0.