Spring Cloud GCP

1. 简介

Spring Cloud GCP 项目使 Spring Framework 成为 Google Cloud Platform （GCP） 的一等公民。

Spring Cloud GCP 允许您利用 Spring 框架的强大功能和简单性来：

• 发布和订阅 Google Cloud 发布/订阅主题
• 使用一些属性配置 Spring JDBC 以使用 Google Cloud SQL
• 使用 Spring Data Cloud Spanner、Spring Data Cloud Data Store 和 Spring Data Reactive Repository for Cloud Firestore 映射对象、关系和集合
• 从谷歌云存储备份的Spring Resources写入和读取
• 在后台使用 Google Cloud Pub/Sub 与 Spring 集成交换消息
• 使用Spring Cloud Sdetectth和Google Cloud Trace跟踪应用程序的执行
• 使用 Spring Cloud Config 配置您的应用，由 Google Runtime Configuration API 备份
• 通过 Spring Integration GCS Channel Adapter 使用和生成 Google Cloud Storage 数据
• 通过 Google Cloud IAP 使用 Spring 安全性
• 使用 Google Cloud Vision 分析图片中的文字、对象和其他内容

2. 入门

本节介绍如何快速了解 Spring Cloud GCP 库。

2.1. 与 Spring 项目版本的兼容性

Spring Cloud GCP 对 Spring 项目具有依赖性和传递性依赖关系。下表概述了与某些Spring Cloud GCP版本兼容的Spring Cloud，Spring Boot和Spring Framework版本。

2.2. 设置依赖

所有Spring Cloud GCP工件都通过Maven Central提供。 提供了以下资源来帮助您设置项目的库：

• 用于依赖关系管理的 Maven 物料清单
• 依赖于Spring Cloud GCP模块的入门依赖项

您也可以查阅我们的Github 项目来检查代码或直接从源代码构建。

2.2.1. 物料清单

Spring Cloud GCP 物料清单 （BOM） 包含它使用的所有依赖项的版本。

如果您是 Maven 用户，将以下内容添加到您的 pom.xml 文件中将允许您从配置中省略任何 Spring Cloud GCP 依赖项版本号。 相反，您使用的 BOM 版本决定了所用依赖项的版本。

<dependencyManagement>
   <dependencies>
       <dependency>
           <groupId>com.google.cloud</groupId>
           <artifactId>spring-cloud-gcp-dependencies</artifactId>
           <version>3.4.0</version>
           <type>pom</type>
           <scope>import</scope>
       </dependency>
   </dependencies>
</dependencyManagement>

或者，如果您是 Gradle 用户：

dependencies {
    implementation platform("com.google.cloud:spring-cloud-gcp-dependencies:3.4.0")
}

请参阅自述文件中的部分，以选择可用版本和 Maven 存储库。

在以下部分中，将假定您使用的是 Spring Cloud GCP BOM，并且依赖项代码段不包含版本。

2.2.2. 启动器依赖项

Spring Cloud GCP 通过 Maven 提供入门依赖项，以轻松依赖库的不同模块。 每个启动器都包含开始使用其相应的Spring Cloud GCP模块所需的所有依赖项和传递依赖项。

例如，如果您希望使用 Cloud Pub/Sub 编写 Spring 应用程序，则可以在项目中包含依赖项。 您不需要包含底层依赖项，因为依赖项包含它。​​spring-cloud-gcp-starter-pubsub​​​​spring-cloud-gcp-pubsub​​​​starter​​

下面提供了这些工件的摘要。

2.2.3. 弹簧初始化

Spring Initializr是一个为新的 Spring Boot 项目生成脚手架代码的工具。 它处理生成 Maven 或 Gradle 构建文件的工作，因此您不必自己手动添加依赖项。

Spring Initializr 提供了来自 Spring Cloud GCP 的三个模块，您可以使用它们来生成项目。

• GCP 支持：GCP 支持模块包含对每个 Spring Cloud GCP 集成的自动配置支持。 仅当将所需的依赖项添加到项目中时，才会启用大多数自动配置代码。
• GCP 消息传递：Google Cloud Pub/Sub 集成开箱即用。
• GCP Storage：Google Cloud Storage 集成开箱即用。

2.3. 学习春云 GCP

有多种资源可以帮助您学习如何使用 Spring Cloud GCP 库。

2.3.1. 示例应用程序

学习如何使用Spring Cloud GCP的最简单方法是查阅Github上的示例应用程序。 Spring Cloud GCP提供了示例应用程序，演示了如何使用库中的每个集成。 下表重点介绍了 Spring Cloud GCP 中最常用的集成的几个示例。

每个示例应用程序都演示了如何在上下文中使用 Spring Cloud GCP 库以及如何设置项目的依赖项。 这些应用程序功能齐全，也可以部署到Google Cloud Platform。 如果您有兴趣，可以查阅将应用程序部署到AppEngine和Google Kubernetes Engine的指南。

2.3.2. 代码实验室

对于更实际的方法，有几个指南和 Codelab 可以帮助您快速上手。 这些指南提供了使用 Spring Cloud GCP 构建应用程序的分步说明。

一些例子包括：

• 将 Spring Boot 应用程序部署到 App Engine
• 使用 Cloud SQL 和 Cloud Pub/Sub 构建 Kotlin Spring Boot 应用程序
• 使用数据存储构建 Spring 引导应用程序
• 使用 Spring 集成和云发布/订阅进行消息传递

Spring Codelabs 的完整集合可以在Google Developer Codelabs 页面上找到。

3. 春云 GCP 核心

每个Spring Cloud GCP模块都使用和来获取GCP项目ID和访问凭据。​​GcpProjectIdProvider​​​​CredentialsProvider​​

Spring Cloud GCP提供了一个Spring Boot启动器来自动配置核心组件。

Maven 坐标，使用Spring Cloud GCP BOM：

<dependency>
    <groupId>com.google.cloud</groupId>
    <artifactId>spring-cloud-gcp-starter</artifactId>
</dependency>

格拉德尔坐标：

dependencies {
    implementation("com.google.cloud:spring-cloud-gcp-starter")
}

3.1. 配置

可以使用弹簧云核心配置以下选项。

3.2. 项目编号

​​GcpProjectIdProvider​​是返回 GCP 项目 ID 字符串的功能接口。

public interface GcpProjectIdProvider {
    String getProjectId();
}

Spring Cloud GCP 启动器自动配置 a。 如果指定了 aproperty，则提供的返回该属性值。​​GcpProjectIdProvider​​​​spring.cloud.gcp.project-id​​​​GcpProjectIdProvider​​

spring.cloud.gcp.project-id=my-gcp-project-id

否则，将根据​​规则的有序列表​​发现项目 ID：

1. 环境变量指定的项目 IDGOOGLE_CLOUD_PROJECT
2. Google App Engine 项目 ID
3. 环境变量指向的 JSON 凭据文件中指定的项目 IDGOOGLE_APPLICATION_CREDENTIALS
4. Google Cloud SDK 项目 ID
5. Google Compute Engine 项目 ID，来自 Google Compute Engine Metadata Server

3.3. 凭证

​​CredentialsProvider​​是一个功能接口，用于返回凭据以对 Google Cloud 客户端库进行身份验证和授权调用。

public interface CredentialsProvider {
  Credentials getCredentials() throws IOException;
}

Spring Cloud GCP 启动器自动配置 a。 它使用该属性来查找Google服务帐户的OAuth2私钥。 请记住，此属性是一个 Spring 资源，因此可以从许多不同的位置（例如文件系统、类路径、URL 等）获取凭据文件。 下一个示例指定文件系统中的凭据位置属性。​​CredentialsProvider​​​​spring.cloud.gcp.credentials.location​​

spring.cloud.gcp.credentials.location=file:/usr/local/key.json

或者，可以通过直接指定属性来设置凭据。 该值应为 JSON 格式的 base64 编码帐户私钥。​​spring.cloud.gcp.credentials.encoded-key​​

如果未通过属性指定该凭据，则启动器会尝试从多个位置发现凭据：

1. 环境变量指向的凭据文件GOOGLE_APPLICATION_CREDENTIALS
2. Google Cloud SDK命令提供的凭据gcloud auth application-default login
3. 谷歌应用引擎内置凭据
4. Google Cloud Shell 内置凭据
5. Google Compute Engine 内置凭据

如果您的应用在Google App Engine或Google Compute Engine上运行，在大多数情况下，您应该省略该属性，而是让Spring Cloud GCP Starter获取这些环境的正确凭据。 在 App Engine Standard 上，将使用 App Identity 服务帐号凭据，在 App Engine Flexible 上，将使用灵活服务帐号凭据，在 Google Compute Engine 上使用计算引擎默认服务帐号。​​spring.cloud.gcp.credentials.location​​

3.3.1. 作用域

默认情况下，Spring Cloud GCP Starter 提供的凭据包含 Spring Cloud GCP 支持的每个服务的范围。

Spring Cloud GCP 入门器允许您为提供的凭据配置自定义范围列表。 为此，请在属性中指定一个逗号分隔的Google OAuth2 范围列表。​​spring.cloud.gcp.credentials.scopes​​

​​spring.cloud.gcp.credentials.scopes​​是Google Cloud Platform 服务的 Google OAuth2 范围的逗号分隔列表，凭据由提供的支持返回。​​CredentialsProvider​​

spring.cloud.gcp.credentials.scopes=https://www.googleapis.com/auth/pubsub,https://www.googleapis.com/auth/sqlservice.admin

还可以使用占位符作为范围来表示初学者默认范围，并附加需要添加的其他范围。​​DEFAULT_SCOPES​​

spring.cloud.gcp.credentials.scopes=DEFAULT_SCOPES,https://www.googleapis.com/auth/cloud-vision

3.4. 环境

​​GcpEnvironmentProvider​​是一个功能接口，由 Spring Cloud GCP 启动器自动配置，返回 aenum。 提供程序可以帮助以编程方式确定应用程序在哪个 GCP 环境（App Engine Flexible、App Engine Standard、Kubernetes Engine 或 Compute Engine）中部署。​​GcpEnvironment​​

public interface GcpEnvironmentProvider {
    GcpEnvironment getCurrentEnvironment();
}

3.5. 自定义 Bean 范围

Spring Cloud GCP 启动器在默认单例范围内自动配置所有必要的 bean。 如果您需要动态重新创建特定的 Bean 或一组 Bean（例如，轮换凭证），则有两个选项：

1. 注释必要类型的自定义 bean。 如果您的应用程序已经在重新定义这些 bean，则这最有意义。@RefreshScope
2. 通过在 Spring Cloud 属性中列出自动配置的 Bean 来覆盖它们的范围。spring.cloud.refresh.extra-refreshable
   
   例如，Cloud Pub/Sub 订阅中涉及的 Bean 可以标记为可刷新，如下所示：

spring.cloud.refresh.extra-refreshable=com.google.cloud.spring.pubsub.support.SubscriberFactory,\
  com.google.cloud.spring.pubsub.core.subscriber.PubSubSubscriberTemplate

@Autowired
private PubSubInboundChannelAdapter pubSubAdapter;

@EventListener(RefreshScopeRefreshedEvent.class)
public void onRefreshScope(RefreshScopeRefreshedEvent event) {
  this.pubSubAdapter.stop();
  this.pubSubAdapter.start();
}

3.6. 弹簧初始化

这个启动器可以从Spring Initializr通过入口获得。​​GCP Support​​

4. 云存储

谷歌云存储允许在单个或多个区域中存储任何类型的文件。 提供了一个 Spring 引导启动器来自动配置各种存储组件。

Maven 坐标，使用Spring Cloud GCP BOM：

<dependency>
    <groupId>com.google.cloud</groupId>
    <artifactId>spring-cloud-gcp-starter-storage</artifactId>
</dependency>

格拉德尔坐标：

dependencies {
    implementation("com.google.cloud:spring-cloud-gcp-starter-storage")
}

这个启动器也可以从Spring Initializr通过入口获得。​​GCP Storage​​

4.1. 使用云存储

启动器会自动在 Spring 应用程序上下文中配置和注册 abean。 Thebean （Javadoc） 可用于列出/创建/更新/删除存储桶（一组具有类似权限和弹性要求的对象）和对象。​​Storage​​​​Storage​​

@Autowired
private Storage storage;

public void createFile() {
    Bucket bucket = storage.create(BucketInfo.of("my-app-storage-bucket"));

    storage.create(
        BlobInfo.newBuilder("my-app-storage-bucket", "subdirectory/my-file").build(),
            "file contents".getBytes()
    );
}

4.2. 云存储对象作为弹簧资源

Spring 资源是许多低级资源的抽象，例如文件系统文件、类路径文件、servlet 上下文相关文件等。 Spring Cloud GCP添加了一种新的资源类型：Google Cloud Storage （GCS）对象。

Google Cloud Storage 的 Spring Resource Abstraction 允许使用注释通过其 GCS URL 访问 GCS 对象：​​@Value​​

@Value("gs://[YOUR_GCS_BUCKET]/[GCS_FILE_NAME]")
private Resource gcsResource;

...或 Spring 应用程序上下文

SpringApplication.run(...).getResource("gs://[YOUR_GCS_BUCKET]/[GCS_FILE_NAME]");

这将创建一个可用于读取对象以及其他可能操作的对象。​​Resource​​

也可以写入 a，尽管需要 ais。​​Resource​​​​WriteableResource​​

@Value("gs://[YOUR_GCS_BUCKET]/[GCS_FILE_NAME]")
private Resource gcsResource;
...
try (OutputStream os = ((WritableResource) gcsResource).getOutputStream()) {
  os.write("foo".getBytes());
}

要使用 Google 云存储资源，请将其投射到。​​Resource​​​​GoogleStorageResource​​

如果资源路径引用 Google Cloud Storage 上的对象（而不是存储桶），则可以调用该方法来获取Blob。 此类型表示一个 GCS 文件，该文件具有可以设置的关联元数据，例如内容类型。 该方法还可用于获取 GCS 对象的签名 URL。 但是，创建签名 URL 要求使用服务帐户凭据创建资源。​​getBlob​​​​createSignedUrl​​

Google Cloud Storage 的 Spring Boot Starter 根据 Spring Boot GCP 启动器提供的自动配置模块所需的 bean。​​Storage​​​​spring-cloud-gcp-storage​​​​CredentialsProvider​​

4.2.1. 设置内容类型

您可以从相应的对象设置 Google Cloud Storage 文件的内容类型：​​Resource​​

((GoogleStorageResource)gcsResource).getBlob().toBuilder().setContentType("text/html").build().update();

4.3. 配置

Google Cloud Storage 的 Spring Boot Starter 提供以下配置选项：

5. 云 SQL

Spring Cloud GCP增加了与Spring JDBC和Spring R2DBC的集成，因此您可以使用SpringJDBC和其他依赖于它的库（如Spring Data JPA或Spring Data R2DBC）在Google Cloud SQL中运行MySQL或PostgreSQL数据库。

Cloud SQL 支持由 Spring Cloud GCP 以两个 Spring Boot 启动器的形式提供，一个用于 MySQL，另一个用于 PostgreSQL。 启动器的作用是从属性中读取配置并采用默认设置，以便连接到MySQL和PostgreSQL的用户体验尽可能简单。

5.1. JDBC 支持

Maven 和 Gradle 坐标，使用Spring Cloud GCP BOM：

要使用 MySQL：

<dependency>
    <groupId>com.google.cloud</groupId>
    <artifactId>spring-cloud-gcp-starter-sql-mysql</artifactId>
</dependency>

dependencies {
implementation("com.google.cloud:spring-cloud-gcp-starter-sql-mysql")
}

要使用PostgreSQL：

<dependency>
<groupId>com.google.cloud</groupId>
<artifactId>spring-cloud-gcp-starter-sql-postgresql</artifactId>
</dependency>

dependencies {
    implementation("com.google.cloud:spring-cloud-gcp-starter-sql-postgresql")
}

为了使用 Spring Boot Starters for Google Cloud SQL，必须在您的 GCP 项目中启用 Google Cloud SQL API。

为此，请转到Google云控制台的API库页面，搜索“ Cloud SQL API”并启用名为“Cloud SQL”的选项。

适用于 Google Cloud SQL 的 Spring Boot Starters 提供了一个自动配置的数据源对象。 与Spring JDBC相结合，它提供了一个JdbcTemplate对象bean，允许查询和修改数据库等操作。

public List<Map<String, Object>> listUsers() {
    return jdbcTemplate.queryForList("SELECT * FROM user;");
}

您可以依靠Spring 引导数据源自动配置来配置 abean。 换句话说，可以使用 SQL 用户名和密码等属性。 还有一些特定于 Google Cloud SQL 的配置（请参阅下面的“Cloud SQL 配置属性”部分）。​​DataSource​​​​spring.datasource.username​​​​spring.datasource.password​​

数据源创建流程

Spring Boot starter for Google Cloud SQL 寄存器根据上述属性为环境提供正确格式的属性。 它还提供默认值，可以覆盖这些默认值。 启动器还根据以下属性配置 JDBC 连接的凭证。​​CloudSqlEnvironmentPostProcessor​​​​spring.datasource.url​​​​spring.datasource.username​​​​spring.datasource.driver-class-name​​

然后，Spring Boot使用用户属性和提供的属性来创建。 您可以通过将连接池的依赖项添加到类路径来选择连接池的类型（例如，Tomcat、HikariCP 等）。​​CloudSqlEnvironmentPostProcessor​​​​DataSource​​

将创建与Spring JDBC结合使用，为您提供了一个完全配置的操作对象，您可以使用该对象与SQL数据库进行交互。 只需数据库和实例名称即可连接到数据库。​​DataSource​​​​JdbcTemplate​​

5.2. R2DBC 支持

Maven 和 Gradle 坐标，使用Spring Cloud GCP BOM：

要使用 MySQL：

<dependency>
    <groupId>com.google.cloud</groupId>
    <artifactId>spring-cloud-gcp-starter-sql-mysql-r2dbc</artifactId>
</dependency>

dependencies {
    implementation("com.google.cloud:spring-cloud-gcp-starter-sql-mysql-r2dbc")
}

要将 PostgreSQL 与 Spring Boot 2.6 一起使用：

<dependency>
    <groupId>com.google.cloud</groupId>
    <artifactId>spring-cloud-gcp-starter-sql-postgres-r2dbc</artifactId>
</dependency>

dependencies {
    implementation("com.google.cloud:spring-cloud-gcp-starter-sql-postgres-r2dbc")
}

要将PostgreSQL与Spring Boot 2.7一起使用（最新版本的Postgres R2DBC驱动程序更改了其Maven坐标）：

<dependency>
    <groupId>com.google.cloud</groupId>
    <artifactId>spring-cloud-gcp-starter-sql-postgres-r2dbc</artifactId>
    <exclusions>
        <exclusion>
            <groupId>io.r2dbc</groupId>
            <artifactId>r2dbc-postgresql</artifactId>
        </exclusion>
    </exclusions>
</dependency>

<dependency>
    <groupId>org.postgresql</groupId>
    <artifactId>r2dbc-postgresql</artifactId>
    <version>0.9.1.RELEASE</version>
</dependency>

5.2.1. 先决条件

为了使用 Spring Boot Starters for Google Cloud SQL，必须在您的 GCP 项目中启用 Google Cloud SQL API。

为此，请转到Google Cloud Console的API库页面，搜索“Cloud SQL API”并启用名为“Cloud SQL”的选项。

5.2.2. 谷歌云SQL的Spring Boot Starter

Cloud SQL R2DBC 入门器提供了一个自定义的 Bean，用于在 Cloud SQLSocket Factory 的帮助下连接到 Cloud SQL。 与 JDBC 支持类似，您只需使用数据库和实例名称即可连接到数据库。​​io.r2dbc.spi.ConnectionFactory​​

还提供了更高级别的便利对象R2dbcEntityTemplate，用于查询和修改数据库等操作。

@Autowired R2dbcEntityTemplate template;

public Flux<String> listUsers() {
  return template.select(User.class).all().map(user -> user.toString());
}

可以使用标准的 R2DBC 属性，如 SQL 用户名和密码。 还有一些特定于 Google Cloud SQL 的配置（请参阅下面的“Cloud SQL 配置属性”部分）。​​spring.r2dbc.username​​​​spring.r2dbc.password​​

连接工厂创建流程

Spring Cloud GCP starter for Google Cloud SQL 寄存器，根据上述属性为环境提供正确格式的属性。 它还为 提供默认值，可以覆盖该值。 启动器还根据以下属性为 R2DBC 连接配置凭据。​​R2dbcCloudSqlEnvironmentPostProcessor​​​​spring.r2dbc.url​​​​spring.r2dbc.username​​

然后，Spring Boot 使用用户属性和提供的属性来创建。​​R2dbcCloudSqlEnvironmentPostProcessor​​​​ConnectionFactory​​

然后，自定义已准备好连接到云 SQL。其余的Spring Data R2DBC对象构建在它（，）上是自动配置和操作的，准备与SQL数据库进行交互。​​ConnectionFactory​​​​R2dbcEntityTemplate​​​​DatabaseClient​​

5.3. 云 SQL IAM 数据库身份验证

目前，Cloud SQL 仅支持PostgreSQL 的 IAM 数据库身份验证。 它允许您使用 IAM 账户（而不是预定义的数据库用户名和密码）连接到数据库。 您需要执行以下操作才能启用它：

1. 在数据库实例设置中，打开标志。cloudsql.iam_authentication
2. 将 IAM 用户或服务账户添加到数据库用户列表中。
3. 在应用程序设置中，设置。请注意，这还会将数据库协议设置为，因为 IAM 身份验证需要它才能正常工作。 但是，它不会影响通信的安全性，因为连接始终是加密的。spring.cloud.gcp.sql.enableIamAuthtruesslmodedisabled
4. 设置为在步骤 2 中创建的 IAM 用户或服务账户。请注意，在修改或查询数据库之前，仍需要向 IAM 用户或服务账户授予权限。spring.datasource.username

5.4. 云 SQL 配置属性

5.5. 故障排除提示

5.5.1. 连接问题

如果无法连接到数据库并看到无限循环，则可能是在低于记录器级别的级别引发和记录异常。 HikariCP可能就是这种情况，如果您的记录器设置为INFO或更高级别。​​Connecting to Cloud SQL instance […] on IP […]​​

要查看后台发生了什么，您应该将 afile 添加到您的应用程序资源文件夹中，如下所示：​​logback.xml​​

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <include resource="org/springframework/boot/logging/logback/base.xml"/>
  <logger name="com.zaxxer.hikari.pool" level="DEBUG"/>
</configuration>

5.5.2. 像c.g.cloud.sql.core.SslSocketFactory 这样的错误：由于错误后过早尝试刷新实例信息而重新抛出缓存异常

如果您在循环中看到很多此类错误，并且无法连接到您的数据库，这通常是您的凭据权限出现问题或未启用 Google Cloud SQL API 的症状。 验证 Google Cloud SQL API 是否已在云控制台中启用，并且您的服务帐号是否具有必要的 IAM 角色。

若要找出导致问题的原因，可以如上所述启用 DEBUG 日志记录级别。

5.5.3. PostgreSQL：java.net.Socket异常：已经连接的问题

我们发现，如果您的 Maven 项目的父版本是版本版本，或者在任何其他会导致依赖项版本较旧的情况下（例如，），此异常很常见。​​spring-boot​​​​1.5.x​​​​org.postgresql:postgresql​​​​9.4.1212.jre7​​

若要解决此问题，请在正确的版本中重新声明依赖项。 例如，在 Maven 中：

<dependency>
  <groupId>org.postgresql</groupId>
  <artifactId>postgresql</artifactId>
  <version>42.1.1</version>
</dependency>

5.6. 示例

可用的示例应用程序和代码实验室：

• Spring Cloud GCP MySQL
• Spring Cloud GCP PostgreSQL
• Spring Data JPA with Spring Cloud GCP SQL
• Codelab：使用云SQL的春季宠物诊所
• R2DBC： Spring Cloud GCP MySQL
• R2DBC： Spring Cloud GCP PostgreSQL

6. 云发布/订阅

Spring Cloud GCP 提供了一个抽象层，用于发布和订阅 Google Cloud Pub/Sub 主题，以及创建、列出或删除 Google Cloud Pub/Sub 主题和订阅。

提供了一个 Spring 引导启动器来自动配置各种必需的发布/订阅组件。

Maven 坐标，使用Spring Cloud GCP BOM：

<dependency>
    <groupId>com.google.cloud</groupId>
    <artifactId>spring-cloud-gcp-starter-pubsub</artifactId>
</dependency>

格拉德尔坐标：

dependencies {
    implementation("com.google.cloud:spring-cloud-gcp-starter-pubsub")
}

这个启动器也可以从Spring Initializr通过入口获得。​​GCP Messaging​​

6.1. 配置

Google Cloud Pub/Sub 的 Spring Boot 启动器提供了以下配置选项。

6.1.1. 春云 GCP 发布/订阅 API 配置

本节介绍用于启用集成、指定 GCP 项目和凭据以及设置 API 是否应连接到模拟器进行本地测试的选项。

6.1.2. 发布者/订阅者配置

本节介绍用于自定义应用程序的发布/订阅发布者和订阅者行为的配置选项。 订阅者设置可以是全局的，也可以是特定于订阅的。

特定于订阅的配置

6.1.3. GRPC 连接设置

发布/订阅 API 使用GRPC协议向发布/订阅服务发送 API 请求。 本节介绍用于自定义 GRPC 行为的配置选项。

特定于订阅的配置

6.1.4. 编程配置

要应用上述属性未涵盖的发布自定义项，您可以提供类型的自定义 bean，以便在对象构建到 a 之前对其进行后处理。 Thebeans 可以用 Spring Framework 的注释进行注释，以确保它们以特定的顺序应用。​​PublisherCustomizer​​​​Publisher.Builder​​​​Publisher​​​​PublisherCustomizer​​​​@Order​​

6.2. 弹簧启动执行器支持

6.2.1. 云发布/订阅健康指示器

如果您使用的是 Spring 引导执行器，则可以利用调用的云发布/订阅运行状况指示器。 运行状况指示器将验证 Cloud Pub/Sub 是否已启动并可供应用程序访问。 要启用它，您需要做的就是将Spring 启动执行器添加到您的项目中。​​pubsub​​

然后，指示器将汇总到​​在 localhost：8080/actuator/health​​ （使用该属性查看每个指示器的详细信息）可见的整体应用程序状态。​​pubsub​​​​management.endpoint.health.show-details​​

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

运行状况指示器通过从发布/订阅中提取消息来验证与发布/订阅的连接。

如果未通过 a 指定订阅，它将从预期不存在的随机订阅中提取消息。 如果它能够连接到 GCP 发布/订阅 API，它将发出“up”信号，即拉取结果为响应 ofor。​​spring.cloud.gcp.pubsub.health.subscription​​​​NOT_FOUND​​​​PERMISSION_DENIED​​

如果指定了自定义订阅，则如果成功拉取并（可选）确认消息，或者当成功拉取但未从 Pub/Sub 返回任何消息时，此运行状况指示器将发出“up”信号。 请注意，除非您将选项设置为 ，否则不会确认从订阅中提取的消息。 因此，请注意不要配置对业务有影响的订阅，而是完全忽略自定义订阅。​​spring.cloud.gcp.pubsub.health.acknowledge-messages​​​​true​​

6.2.2. 云发布/订阅运行状况指示器

如果您使用的是 Spring 启动执行器，则可以利用调用的云发布/订阅运行状况指示器。 订阅运行状况指示器将验证发布/订阅是否正在主动处理来自订阅积压工作的消息。 要启用它，您需要将Spring 引导执行器添加到您的项目中和GCP 监控中。 您还需要设置以下属性。​​pubsub-subscriber​​​​spring.cloud.gcp.pubsub.health.lagThreshold​​​​spring.cloud.gcp.pubsub.health.backlogThreshold​​

然后，指示器将汇总到​​在 localhost：8080/actuator/health​​ （使用该属性查看每个指示器的详细信息）可见的整体应用程序状态。​​pubsub-subscriber​​​​management.endpoint.health.show-details​​

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
<dependency>
    <groupId>com.google.cloud</groupId>
    <artifactId>google-cloud-monitoring</artifactId>
</dependency>

运行状况指示器通过检查订阅的消息积压和上次处理的消息来验证订阅者的运行状况。 订阅的积压工作是使用 Google Cloud 的监控指标检索的。使用的指标是订阅。​​num_undelivered_messages​​

如果最近在合理的时间阈值内处理了消息，则订阅者运行正常。 如果订阅的消息积压很大，但订阅者使用消息，则订阅者仍然正常。 如果没有对最近的消息进行任何处理，但积压工作增加，则订阅者不正常。

6.3. 发布/订阅操作和模板

​​PubSubOperations​​是一个抽象概念，允许Spring用户使用Google Cloud Pub/Sub，而无需依赖任何Google Cloud Pub/Sub API语义。 它提供了与Google Cloud Pub/Sub.交互所需的一组通用操作，是默认实现，它使用Google Cloud Java Client for Pub/Sub与Google Cloud Pub/Sub进行交互。​​PubSubTemplate​​​​PubSubOperations​​

6.3.1. 发布到主题

​​PubSubTemplate​​提供将消息发布到 Google Cloud 发布/订阅主题的异步方法。 该方法采用要将消息发布到的主题名称、泛型类型的有效负载以及带有消息标头的映射（可选）。 主题名称可以是当前项目中的短主题名称，也可以是使用 theformat 引用不同项目中的主题的完全限定名称。​​publish()​​​​projects/[project_name]/topics/[topic_name]​​

以下是有关如何向 Google Cloud 发布/订阅主题发布消息的示例：

Map<String, String> headers = Collections.singletonMap("key1", "val1");
pubSubTemplate.publish(topicName, "message", headers).get();

默认情况下，用于转换类型的有效负载,,,和发布/订阅消息。​​SimplePubSubMessageConverter​​​​byte[]​​​​ByteString​​​​ByteBuffer​​​​String​​

对消息进行排序

如果您依赖于消息转换器并希望提供排序键，请使用标头。 您还需要确保通过属性在发布者上启用消息排序。 此外，如果使用多个发布者，则需要将其设置为区域终结点，例如将消息发送到同一区域并按顺序接收。​​GcpPubSubHeaders.ORDERING_KEY​​​​spring.cloud.gcp.pubsub.publisher.enable-message-ordering​​​​spring.cloud.gcp.pubsub.publisher.endpoint​​​​"us-east1-pubsub.googleapis.com:443"​​

Map<String, String> headers =
    Collections.singletonMap(GcpPubSubHeaders.ORDERING_KEY, "key1");
pubSubTemplate.publish(topicName, "message1", headers).get();
pubSubTemplate.publish(topicName, "message2", headers).get();

6.3.2. 订阅订阅

Google Cloud Pub/Sub 允许将许多订阅关联到同一主题。允许您通过该方法收听订阅。 收听订阅时，系统会从 Google Cloud Pub/Sub 异步提取消息，并将其传递给用户提供的消息处理程序。 订阅名称可以是当前项目中的短订阅名称，也可以是使用 theformat 引用不同项目中的订阅的完全限定名称。​​PubSubTemplate​​​​subscribe()​​​​projects/[project_name]/subscriptions/[subscription_name]​​

例

使用消息处理程序订阅订阅：

Subscriber subscriber =
    pubSubTemplate.subscribe(
        subscriptionName,
        message -> {
          logger.info(
              "Message received from "
                  + subscriptionName
                  + " subscription: "
                  + message.getPubsubMessage().getData().toStringUtf8());
          message.ack();
        });

订阅方式

​​PubSubTemplate​​提供以下订阅方式：

6.3.3. 从订阅中提取消息

Google Cloud Pub/Sub 支持从订阅中同步拉取消息。 这与订阅不同，因为订阅是一项异步任务。

例

最多提取 10 条消息：

int maxMessages = 10;
boolean returnImmediately = false;
List<AcknowledgeablePubsubMessage> messages =
    pubSubTemplate.pull(subscriptionName, maxMessages, returnImmediately);

// acknowledge the messages
pubSubTemplate.ack(messages);

messages.forEach(
    message ->
        logger.info(message.getPubsubMessage().getData().toStringUtf8()));

拉取方法

​​PubsubTemplate​​提供以下拉取方式：

确认消息

有两种方法可以确认消息。

1. 要一次确认多条消息，您可以使用该方法。 您还可以使用 for 否定确认消息。 使用这些方法批量确认消息比单独确认消息更有效，但它们要求消息集合来自同一项目。PubSubTemplate.ack()PubSubTemplate.nack()
2. 要单独确认消息，您可以对每个消息使用理论方法（相应地确认或否定确认）。ack()nack()

死信主题

您的应用程序可能偶尔会收到无法处理的消息。 如果创建传递参数的订阅，则可以指定 在可配置的重新传递尝试次数后转发所有已编辑和非已编辑的消息。 有关更多信息，请参阅此处。​​Subscription.Builder​​​​DeadLetterPolicy​​​​nack()​​​​ack()​​

public Subscription newSubscription() {
    // Must use the fully-qualified topic name.
    String fullDeadLetterTopic = PubSubTopicUtils
                        .toTopicName(DEAD_LETTER_TOPIC, gcpProjectIdProvider.getProjectId())
                        .toString();
    return pubSubAdmin.createSubscription(Subscription.newBuilder()
            .setName(SUBSCRIPTION_NAME)
            .setTopic(TOPIC_NAME)
            .setDeadLetterPolicy(DeadLetterPolicy.newBuilder()
                    .setDeadLetterTopic(fullDeadLetterTopic)
                    .setMaxDeliveryAttempts(6)
                    .build()));
}

死信主题与任何其他主题没有什么不同，尽管需要一些额外的权限来确保 Cloud Pub/Sub 服务可以成功处理原始消息并在死信主题上重新发送。​​ack​​​​publish​​

6.3.4. JSON 支持

对于使用 Jackson JSON 的 POJO 的序列化和反序列化，请配置 abean，GCP Pub/Sub 的 Spring Boot 启动器将自动将其连接到 中。​​PubSubMessageConverter​​​​PubSubTemplate​​

// Note: The ObjectMapper is used to convert Java POJOs to and from JSON.
// You will have to configure your own instance if you are unable to depend
// on the ObjectMapper provided by Spring Boot starters.
@Bean
public PubSubMessageConverter pubSubMessageConverter() {
  return new JacksonPubSubMessageConverter(new ObjectMapper());
}

假设您定义了以下类：

static class TestUser {

  String username;

  String password;

  public String getUsername() {
    return this.username;
  }

  void setUsername(String username) {
    this.username = username;
  }

  public String getPassword() {
    return this.password;
  }

  void setPassword(String password) {
    this.password = password;
  }
}

您可以在发布时自动将对象序列化为 JSON：

TestUser user = new TestUser();
user.setUsername("John");
user.setPassword("password");
pubSubTemplate.publish(topicName, user);

这就是您在拉取时将消息转换为对象的方式：

int maxMessages = 1;
boolean returnImmediately = false;
List<ConvertedAcknowledgeablePubsubMessage<TestUser>> messages =
    pubSubTemplate.pullAndConvert(
        subscriptionName, maxMessages, returnImmediately, TestUser.class);

ConvertedAcknowledgeablePubsubMessage<TestUser> message = messages.get(0);

// acknowledge the message
message.ack();

TestUser receivedTestUser = message.getPayload();

请参阅我们的发布/订阅 JSON 有效负载示例应用，作为使用此功能的参考。