Spring Cloud GCP（五）

15.4. Firestore 操作和模板

​​FirestoreOperations​​及其实现提供了 Spring 开发人员熟悉的模板模式。​​FirestoreTemplate​​

使用 Spring Data Cloud Firestore 提供的自动配置，Spring 应用程序上下文将包含一个完全配置的对象，您可以在应用程序中自动连线该对象：​​FirestoreTemplate​​

@SpringBootApplication
public class FirestoreTemplateExample {

    @Autowired
    FirestoreOperations firestoreOperations;

    public Mono<User> createUsers() {
        return this.firestoreOperatons.save(new User("Alice", 29))
            .then(this.firestoreOperatons.save(new User("Bob", 60)));
    }

    public Flux<User> findUsers() {
        return this.firestoreOperatons.findAll(User.class);
    }

    public Mono<Long> removeAllUsers() {
        return this.firestoreOperatons.deleteAll(User.class);
    }
}

模板 API 支持：

• 读取和写入操作
• 交易
• 子集合操作

15.5. 按约定查询方法

public class MyApplication {
  void partTreeRepositoryMethodTest() {
    User u1 = new User("Cloud", 22, null, null, new Address("1 First st., NYC", "USA"));
    u1.favoriteDrink = "tea";
    User u2 =
        new User(
            "Squall",
            17,
            Arrays.asList("cat", "dog"),
            null,
            new Address("2 Second st., London", "UK"));
    u2.favoriteDrink = "wine";
    Flux<User> users = Flux.fromArray(new User[] {u1, u2});

    this.userRepository.saveAll(users).blockLast();

    assertThat(this.userRepository.count().block()).isEqualTo(2);
    assertThat(this.userRepository.findBy(PageRequest.of(0, 10)).collectList().block())
        .containsExactly(u1, u2);
    assertThat(this.userRepository.findByAge(22).collectList().block()).containsExactly(u1);
    assertThat(this.userRepository.findByAgeNot(22).collectList().block()).containsExactly(u2);
    assertThat(this.userRepository.findByHomeAddressCountry("USA").collectList().block())
        .containsExactly(u1);
    assertThat(this.userRepository.findByFavoriteDrink("wine").collectList().block())
        .containsExactly(u2);
    assertThat(this.userRepository.findByAgeGreaterThanAndAgeLessThan(20, 30).collectList().block())
        .containsExactly(u1);
    assertThat(this.userRepository.findByAgeGreaterThan(10).collectList().block())
        .containsExactlyInAnyOrder(u1, u2);
    assertThat(this.userRepository.findByNameAndAge("Cloud", 22).collectList().block())
        .containsExactly(u1);
    assertThat(
            this.userRepository
                .findByNameAndPetsContains("Squall", Collections.singletonList("cat"))
                .collectList()
                .block())
        .containsExactly(u2);
  }
}

在上面的示例中，查询方法实现是使用Spring 数据查询创建命名约定基于方法名称生成的。​​UserRepository​​

云修复仅支持通过 AND 加入的筛选器组件，以及以下操作：

• ​​equals​​
• ​​is not equal​​
• ​​greater than or equals​​
• ​​greater than​​
• ​​less than or equals​​
• ​​less than​​
• ​​is null​​
• ​​contains​​（接受最多 10 个元素或奇异值）List
• ​​in​​（最多接受 10 个元素）List
• ​​not in​​（最多接受 10 个元素）List

编写仅指定这些方法的签名的自定义存储库接口后，将为您生成实现，并可与存储库的自动连线实例一起使用。

15.6. 交易

只读和读写事务由提供（有关详细信息，请参阅这篇关于反应式事务的博客文章）。 为了使用它，您需要像这样自动接线：​​TransactionalOperator​​​​ReactiveFirestoreTransactionManager​​

public class MyApplication {
  @Autowired ReactiveFirestoreTransactionManager txManager;
}

之后，您将能够使用它来创建实例。 请注意，您可以使用对象在只读事务和读写事务之间切换：​​TransactionalOperator​​​​TransactionDefinition​​

DefaultTransactionDefinition transactionDefinition = new DefaultTransactionDefinition();
transactionDefinition.setReadOnly(false);
TransactionalOperator operator =
    TransactionalOperator.create(this.txManager, transactionDefinition);

当您有实例时，可以使用以下命令在事务中调用一系列 Firestore 操作：​​TransactionalOperator​​​​operator::transactional​​

User alice = new User("Alice", 29);
User bob = new User("Bob", 60);

this.userRepository
    .save(alice)
    .then(this.userRepository.save(bob))
    .as(operator::transactional)
    .block();

this.userRepository
    .findAll()
    .flatMap(
        a -> {
          a.setAge(a.getAge() - 1);
          return this.userRepository.save(a);
        })
    .as(operator::transactional)
    .collectList()
    .block();

assertThat(this.userRepository.findAll().map(User::getAge).collectList().block())
    .containsExactlyInAnyOrder(28, 59);

15.6.1. 带有@Transactional注释的声明性事务

此功能需要 bean，这是在使用时提供的。​​SpannerTransactionManager​​​​spring-cloud-gcp-starter-data-firestore​​

​​FirestoreTemplate​​并支持将注释作为事务运行方法。 如果一个带注释的方法调用另一个也带注释的方法，则这两个方法将在同一事务中工作。​​FirestoreReactiveRepository​​​​@Transactional​​​​@Transactional​​

此处说明了使用此功能的一种方法。您需要执行以下操作：

1. 使用注释注释配置类。@EnableTransactionManagement
2. 创建一个服务类，其方法注释如下：@Transactional

class UserService {
  @Autowired private UserRepository userRepository;

  @Transactional
  public Mono<Void> updateUsers() {
    return this.userRepository
        .findAll()
        .flatMap(
            a -> {
              a.setAge(a.getAge() - 1);
              return this.userRepository.save(a);
            })
        .then();
  }
}

3. 创建一个 Spring Bean 提供程序，用于创建该类的实例：

@Bean
public UserService userService() {
  return new UserService();
}

之后，您可以像这样自动连接您的服务：

public class MyApplication {
  @Autowired UserService userService;
}

现在，当您调用服务对象上注释的方法时，事务将自动启动。 如果在执行带有注释的方法期间发生错误，事务将被回滚。 如果未发生错误，则将提交事务。​​@Transactional​​​​@Transactional​​

15.7. 子集合

子集合是与特定实体关联的集合。 子集合中的文档也可以包含子集合，从而允许您进一步嵌套数据。您最多可以嵌套 100 层的数据。

要使用子集合，您需要使用 call 创建一个带有父实体的对象。 您可以使用此对象来保存、查询和删除与此父对象关联的实体。 父级不必存在于 Firestore 中，但应具有非空 id 字段。​​FirestoreReactiveOperations​​​​FirestoreReactiveOperations.withParent​​

自动线：​​FirestoreReactiveOperations​​

@Autowired
FirestoreReactiveOperations firestoreTemplate;

然后，您可以使用此对象创建具有自定义父级的对象：​​FirestoreReactiveOperations​​

FirestoreReactiveOperations bobTemplate =
    this.firestoreTemplate.withParent(new User("Bob", 60));

PhoneNumber phoneNumber = new PhoneNumber("111-222-333");
bobTemplate.save(phoneNumber).block();
assertThat(bobTemplate.findAll(PhoneNumber.class).collectList().block())
    .containsExactly(phoneNumber);
bobTemplate.deleteAll(PhoneNumber.class).block();
assertThat(bobTemplate.findAll(PhoneNumber.class).collectList().block()).isEmpty();

15.8. 更新时间和乐观锁定

Firestore 存储每个文档的更新时间。 如果要检索它，可以向实体添加一个类型字段，并使用注释对其进行批注。​​com.google.cloud.Timestamp​​​​@UpdateTime​​

@UpdateTime
Timestamp updateTime;

使用更新时间进行乐观锁定

带批注的字段可用于乐观锁定。 要启用此功能，您需要将参数设置为：​​@UpdateTime​​​​version​​​​true​​

@UpdateTime(version = true)
Timestamp updateTime;

启用乐观锁定后，写入请求中将自动添加一个前提条件，以确保要更新的文档自上次读取以来未发生更改。 它使用此字段的值作为文档版本，并检查您编写的文档版本是否与您阅读的文档版本相同。

如果该字段为空，则前提条件将检查具有相同 id 的文档是否存在，以确保您不会无意中覆盖现有文档。

15.9. 云 Firestore 弹簧启动启动器

如果您更喜欢仅使用Firestore客户端，Spring Cloud GCP提供了一个方便的入门器，可以自动配置在纯模式下开始使用Google Cloud Firestore所需的身份验证设置和客户端对象。

请参阅文档以了解有关 Cloud Firestore 的更多信息。

要开始使用此库，请将 theartifact 添加到您的项目中。spring-cloud-gcp-starter-firestore

Maven 坐标，使用Spring Cloud GCP BOM：

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

格拉德尔坐标：

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

15.9.1. 使用云还原

启动器会自动在 Spring 应用程序上下文中配置和注册 abean。要开始使用它，只需使用注释即可。​​Firestore​​​​@Autowired​​

@Autowired
Firestore firestore;

 void writeDocumentFromObject() throws ExecutionException, InterruptedException {
   // Add document data with id "joe" using a custom User class
   User data =
       new User(
           "Joe",
           Arrays.asList(new Phone(12345, PhoneType.CELL), new Phone(54321, PhoneType.WORK)));

   // .get() blocks on response
   WriteResult writeResult = this.firestore.document("users/joe").set(data).get();

   LOGGER.info("Update time: " + writeResult.getUpdateTime());
 }

 User readDocumentToObject() throws ExecutionException, InterruptedException {
   ApiFuture<DocumentSnapshot> documentFuture = this.firestore.document("users/joe").get();

   User user = documentFuture.get().toObject(User.class);

   LOGGER.info("read: " + user);

   return user;
 }

15.10. 模拟器的使用

Google Cloud Firebase SDK 为 Cloud Firestore 提供了一个本地内存模拟器，您可以使用该模拟器来开发和测试您的应用。

首先按照 Firebase 模拟器安装步骤安装、配置和运行模拟器。

Firestore 模拟器运行后，请确保在 Spring 应用程序中设置了以下属性：​​application.properties​​

spring.cloud.gcp.firestore.emulator.enabled=true
spring.cloud.gcp.firestore.host-port=${EMULATOR_HOSTPORT}

从现在开始，您的应用程序将连接到本地运行的模拟器实例，而不是真正的 Firestore 服务。

15.11. 示例

Spring Cloud GCP提供了Firestore示例应用程序来演示API的使用：

• 反应式 Firestore 存储库示例应用程序：
• Firestore 客户端库示例应用程序

15.12. 测试

​​Testcontainers​​提供模块。在文档中查看更多信息​​gcloud​​​​FirestoreEmulatorContainer​​

16. Redis 云内存存储

16.1. 弹簧缓存

Cloud Memorystore for Redis提供完全托管的内存数据存储服务。 Cloud Memorystore 与 Redis 协议兼容，可轻松与Spring Caching 集成。

您所要做的就是创建一个云内存存储实例，并将其 IP 地址用作属性值。 其他一切都与设置 redis 支持的 Spring 缓存完全相同。​​application.properties​​​​spring.redis.host​​

简而言之，需要以下依赖项：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-cache</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-redis</artifactId>
</dependency>

然后，您可以对要缓存的方法使用注释。​​org.springframework.cache.annotation.Cacheable​​

@Cacheable("cache1")
public String hello(@PathVariable String name) {
    ....
}

如果您对详细的操作指南感兴趣，请查看使用 Cloud Memorystore Codelab 的 Spring 引导缓存。

可在此处找到云内存存储文档。

17. 大查询

Google Cloud BigQuery是一个完全托管的 PB 级低成本分析数据仓库。

Spring Cloud GCP 提供：

• 一个方便的启动器，它为 BigQuery 客户端对象提供自动配置，以及与BigQuery交互所需的凭据。
• 一个 Spring 集成消息处理程序，用于将数据加载到 Spring 集成管道中的 BigQuery 表中。

Maven 坐标，使用Spring Cloud GCP BOM：

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

格拉德尔坐标：

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

17.1. 配置

以下应用程序属性可以使用 Spring Cloud GCP BigQuery 库进行配置。

17.1.1. 大查询客户端对象

该类通过从计算机环境中推断您的凭据和项目 ID 来为您配置BigQuery实例。​​GcpBigQueryAutoConfiguration​​

用法示例：

// BigQuery client object provided by our autoconfiguration.
@Autowired
BigQuery bigquery;

public void runQuery() throws InterruptedException {
  String query = "SELECT column FROM table;";
  QueryJobConfiguration queryConfig =
      QueryJobConfiguration.newBuilder(query).build();

  // Run the query using the BigQuery object
  for (FieldValueList row : bigquery.query(queryConfig).iterateAll()) {
    for (FieldValue val : row) {
      System.out.println(val);
    }
  }
}

此对象用于与所有 BigQuery 服务进行交互。 有关更多信息，请参阅BigQuery 客户端库使用示例。

17.1.2. 大查询模板

类是客户端对象的包装器，可以更轻松地将数据加载到 BigQuery 表中。 Ais 的范围限定为单个数据集。 自动配置实例将使用通过属性提供的数据集。​​BigQueryTemplate​​​​BigQuery​​​​BigQueryTemplate​​​​BigQueryTemplate​​​​spring.cloud.gcp.bigquery.datasetName​​

下面是如何将 CSV 数据加载到 BigQuery 表的代码片段。​​InputStream​​

// BigQuery client object provided by our autoconfiguration.
@Autowired
BigQueryTemplate bigQueryTemplate;

public void loadData(InputStream dataInputStream, String tableName) {
  ListenableFuture<Job> bigQueryJobFuture =
      bigQueryTemplate.writeDataToTable(
          tableName,
          dataFile.getInputStream(),
          FormatOptions.csv());

  // After the future is complete, the data is successfully loaded.
  Job job = bigQueryJobFuture.get();
}

下面是如何将换行符分隔的 JSON数据加载到 BigQuery 表的代码片段。此实现使用BigQuery Storage Write API。下面是一个示例换行符分隔的 JSON 文件，可用于测试此功能。​​InputStream​​

// BigQuery client object provided by our autoconfiguration.
@Autowired
BigQueryTemplate bigQueryTemplate;

  /**
   * This method loads the InputStream of the newline-delimited JSON records to be written in the given table.
   * @param tableName name of the table where the data is expected to be written
   * @param jsonInputStream InputStream of the newline-delimited JSON records to be written in the given table
   */
  public void loadJsonStream(String tableName, InputStream jsonInputStream)
      throws ExecutionException, InterruptedException {
    ListenableFuture<WriteApiResponse> writeApFuture =
        bigQueryTemplate.writeJsonStream(tableName, jsonInputStream);
    WriteApiResponse apiRes = writeApFuture.get();//get the WriteApiResponse
    if (!apiRes.isSuccessful()){
      List<StorageError> errors = apiRes.getErrors();
      //TODO(developer): process the List of StorageError
    }
    //else the write process has been successful
  }

下面是如何创建表，然后将换行符分隔的 JSON数据加载到 BigQuery 表的代码片段。此实现使用BigQuery Storage Write API。下面是一个示例换行符分隔的 JSON 文件，可用于测试此功能。​​InputStream​​

// BigQuery client object provided by our autoconfiguration.
@Autowired
BigQueryTemplate bigQueryTemplate;

  /**
   * This method created a table with the given name and schema and then loads the InputStream of the newline-delimited JSON records in it.
   * @param tableName name of the table where the data is expected to be written
   * @param jsonInputStream InputStream of the newline-delimited JSON records to be written in the given table
   * @param tableSchema Schema of the table which is required to be created
   */
  public void createTableAndloadJsonStream(String tableName, InputStream jsonInputStream, Schema tableSchema)
      throws ExecutionException, InterruptedException {
    ListenableFuture<WriteApiResponse> writeApFuture =
        bigQueryTemplate.writeJsonStream(tableName, jsonInputStream, tableSchema);//using the overloaded method which created the table when tableSchema is passed
    WriteApiResponse apiRes = writeApFuture.get();//get the WriteApiResponse
    if (!apiRes.isSuccessful()){
      List<StorageError> errors = apiRes.getErrors();
      //TODO(developer): process the List of StorageError
    }
    //else the write process has been successful
  }

17.2. 弹簧集成

Spring Cloud GCP BigQuery 还提供了 Spring Integration 消息处理程序。 这对于将 BigQuery 数据加载操作合并到 Spring 集成管道中非常有用。​​BigQueryFileMessageHandler​​

下面是一个使用 abean 配置 abean 的示例。​​ServiceActivator​​​​BigQueryFileMessageHandler​​

@Bean
public DirectChannel bigQueryWriteDataChannel() {
  return new DirectChannel();
}

@Bean
public DirectChannel bigQueryJobReplyChannel() {
  return new DirectChannel();
}

@Bean
@ServiceActivator(inputChannel = "bigQueryWriteDataChannel")
public MessageHandler messageSender(BigQueryTemplate bigQueryTemplate) {
  BigQueryFileMessageHandler messageHandler = new BigQueryFileMessageHandler(bigQueryTemplate);
  messageHandler.setFormatOptions(FormatOptions.csv());
  messageHandler.setOutputChannel(bigQueryJobReplyChannel());
  return messageHandler;
}

17.2.1. 大查询消息处理

接受以下消息负载类型以加载到 BigQuery 中：,,, 和。 消息负载将被流式传输并写入您指定的 BigQuery 表。​​BigQueryFileMessageHandler​​​​java.io.File​​​​byte[]​​​​org.springframework.core.io.Resource​​​​java.io.InputStream​​

默认情况下，配置为读取它收到的消息的标头以确定如何加载数据。 标头由类指定，总结如下。​​BigQueryFileMessageHandler​​​​BigQuerySpringMessageHeaders​​

或者，您可以省略这些标头，并通过调用 and 显式设置表名或格式选项。​​setTableName(…)​​​​setFormatOptions(…)​​

17.2.2. 大查询消息回复

处理消息以将数据加载到 BigQuery 表后，它将使用 aon 回复通道进行响应。 Job 对象提供有关加载文件操作的元数据和信息。​​BigQueryFileMessageHandler​​​​Job​​

默认情况下，该 is 以异步模式运行，并且它将使用 aon 回复通道进行回复。 未来与数据加载作业的状态相关联，并将在作业完成时完成。​​BigQueryFileMessageHandler​​​​setSync(false)​​​​ListenableFuture<Job>​​

如果处理程序在同步模式下运行，则处理程序将在加载作业完成时阻止并阻止直到完成。​​setSync(true)​​

18. 云 IAP

Cloud Identity-Aware Proxy （IAP） 为部署到 Google Cloud 的应用提供安全层。

IAP 启动器使用Spring Security OAuth 2.0 资源服务器功能自动从代理注入的 HTTP 标头中提取用户身份。​​x-goog-iap-jwt-assertion​​

将自动验证以下声明：

• 发行时间
• 过期时间
• 发行
• 观众

当应用在 App Engine 标准版或 App Engine 灵活版上运行时，系统会自动确定受众群体（声明）验证字符串。 此功能依赖于云资源管理器 API 来检索项目详细信息，因此需要进行以下设置：​​"aud"​​

• 在GCP 控制台中启用云资源管理器 API。
• 确保您的应用程序具有权限。resourcemanager.projects.get

App Engine 自动确定受众群体可以通过 using属性进行覆盖。它通过提供逗号分隔的列表来支持多个允许的受众。​​spring.cloud.gcp.security.iap.audience​​

对于计算引擎或 Kubernetes 引擎，必须提供属性，因为受众字符串取决于特定的后端服务设置，无法自动推断。 要确定受众群体价值，请按照 IAP验证 JWT 有效负载指南中的说明进行操作。 如果未提供 ifis，应用程序将无法启动以下消息：​​spring.cloud.gcp.security.iap.audience​​​​spring.cloud.gcp.security.iap.audience​​

No qualifying bean of type 'com.google.cloud.spring.security.iap.AudienceProvider' available.

Starter Maven 坐标，使用Spring Cloud GCP BOM：

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

入门格拉德尔坐标：

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

18.1. 配置

以下属性可用。

18.2. 示例

提供了一个示例应用程序。

19. 云视觉

Google Cloud Vision API允许用户利用机器学习算法来处理图像和文档，包括：图像分类、人脸检测、文本提取、光学字符识别等。

Spring Cloud GCP 提供：

• 一个方便的启动器，可自动配置开始使用Google Cloud Vision API 所需的身份验证设置和客户端对象。
• ​CloudVisionTemplate​​这简化了与云视觉 API 的交互。

• 允许您轻松地将图像，PDF，TIFF和GIF文档作为Spring Resources发送到API。
• 为常见操作提供方便的方法，例如对图像的内容进行分类。

• ​​DocumentOcrTemplate​​它提供了在 PDF 和 TIFF 文档上运行光学字符识别 （OCR） 的便捷方法。

19.1. 依赖设置

要开始使用此库，请将 theartifact 添加到您的项目中。​​spring-cloud-gcp-starter-vision​​

Maven 坐标，使用Spring Cloud GCP BOM：

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

格拉德尔坐标：

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

19.2. 配置

可以使用 Spring Cloud GCP 视觉库配置以下选项。

19.2.1. 云视觉 OCR 依赖项

如果有兴趣对项目的文档应用光学字符识别 （OCR），则需要将两者添加到依赖项中。 存储启动器是必需的，因为Cloud Vision API将在Google Cloud Storage 存储桶中处理您的文档并写入OCR输出文件。​​spring-cloud-gcp-starter-vision​​​​spring-cloud-gcp-starter-storage​​

Maven 使用Spring Cloud GCP BOM 进行坐标：

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

格拉德尔坐标：

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

19.3. 图像分析

允许您轻松分析图像;它提供了以下与云视觉接口的方法：​​CloudVisionTemplate​​

​​public AnnotateImageResponse analyzeImage(Resource imageResource, Feature.Type… featureTypes)​​

参数：

• ​​Resource imageResource​​指要分析的图像对象的 Spring 资源。 Google Cloud Vision 文档提供了它们支持的图像类型的列表。
• ​​Feature.Type… featureTypes​​指要从映像中提取的云视觉功能的 var-arg 数组。 特征是指希望对图像执行的一种图像分析，例如标签检测、OCR 识别、面部检测等。 可以在一个请求中指定要分析的多个特征。 云视觉功能文档中提供了云视觉功能的完整列表。

返回：

• AnnotateImageResponse包含请求中指定的所有特征分析的结果。 对于您在请求中提供的每种特征类型，提供一个 getter 方法来获取该特征分析的结果。 例如，如果您使用该功能分析图像，则可以使用以下命令从响应中检索结果。AnnotateImageResponseLABEL_DETECTIONannotateImageResponse.getLabelAnnotationsList()
  
  ​​AnnotateImageResponse​​由谷歌云视觉图书馆提供;有关更多详细信息，请参阅RPC 参考或Javadoc。 此外，还可以查阅云视觉文档，熟悉 API 的概念和功能。

19.3.1. 检测图像标签示例

图像标签是指生成描述图像内容的标签。 下面是如何使用云视觉 Spring 模板完成此操作的代码示例。

@Autowired
private ResourceLoader resourceLoader;

@Autowired
private CloudVisionTemplate cloudVisionTemplate;

public void processImage() {
  Resource imageResource = this.resourceLoader.getResource("my_image.jpg");
  AnnotateImageResponse response = this.cloudVisionTemplate.analyzeImage(
      imageResource, Type.LABEL_DETECTION);
  System.out.println("Image Classification results: " + response.getLabelAnnotationsList());
}

19.4. 文件分析

这允许您轻松分析 PDF、TIFF 和 GIF 文档;它提供了以下与云视觉接口的方法：​​CloudVisionTemplate​​

​​public AnnotateFileResponse analyzeFile(Resource fileResource, String mimeType, Feature.Type… featureTypes)​​

参数：

• ​​Resource fileResource​​指您要分析的PDF，TIFF或GIF对象的Spring 资源。 不支持超过 5 页的文档。
• ​​String mimeType​​是文件资源的 MIME 类型。 目前，仅支持。application/pdfimage/tiffimage/gif
• ​​Feature.Type… featureTypes​​指要从文档中提取的云视觉功能的 var-arg 数组。 功能是指希望对文档执行的一种图像分析，例如标签检测、OCR 识别、面部检测等。 可以在一个请求中指定要分析的多个特征。 云视觉功能文档中提供了云视觉功能的完整列表。

返回：

• 注释文件响应包含在请求中指定的所有特征分析的结果。 对于分析文档的每一页，响应将包含一个对象，您可以使用该对象进行检索。 对于您在请求中提供的每种特征类型，提供一个 getter 方法来获取该特征分析的结果。 例如，如果您使用该功能分析 PDF，则可以使用以下命令从响应中检索结果。AnnotateImageResponseannotateFileResponse.getResponsesList()AnnotateImageResponseDOCUMENT_TEXT_DETECTIONannotateImageResponse.getFullTextAnnotation().getText()
  
  ​​AnnotateFileResponse​​由谷歌云视觉图书馆提供;有关更多详细信息，请参阅RPC 参考或Javadoc。 此外，还可以查阅云视觉文档，熟悉 API 的概念和功能。

19.4.1. 运行文本检测示例

检测文件中的文本是指从小文档（如 PDF 或 TIFF）中提取文本。 下面是如何使用云视觉 Spring 模板完成此操作的代码示例。

@Autowired
private ResourceLoader resourceLoader;

@Autowired
private CloudVisionTemplate cloudVisionTemplate;

public void processPdf() {
  Resource imageResource = this.resourceLoader.getResource("my_file.pdf");
  AnnotateFileResponse response =
    this.cloudVisionTemplate.analyzeFile(
        imageResource, "application/pdf", Type.DOCUMENT_TEXT_DETECTION);

  response
    .getResponsesList()
    .forEach(
        annotateImageResponse ->
            System.out.println(annotateImageResponse.getFullTextAnnotation().getText()));
}

19.5. 文档 OCR 模板

它允许您轻松地对存储在Google存储桶中的PDF和TIFF文档运行光学字符识别（OCR）。DocumentOcrTemplate

首先，您需要在Google Cloud Storage中创建一个存储桶，并将要处理的文档上传到存储桶中。

19.5.1. 在文档上运行 OCR

在文档上运行 OCR 时，云视觉 API 将以 JSON 格式输出 OCR 输出文件的集合，这些文件描述文本内容、单词和字母的边框以及有关文档的其他信息。

提供了以下方法，用于对保存在 Google Cloud Storage 中的文档运行 OCR：​​DocumentOcrTemplate​​

​​ListenableFuture<DocumentOcrResultSet> runOcrForDocument(GoogleStorageLocation document, GoogleStorageLocation outputFilePathPrefix)​​

该方法允许您指定文档的位置以及所有 JSON 输出文件将保存在 Google Cloud Storage 中的输出位置。 它返回包含包含文档的 OCR 内容。​​ListenableFuture​​​​DocumentOcrResultSet​​

19.5.2. 运行 OCR 示例

下面是如何在存储在 Google 存储桶中的文档上运行 OCR 并读取文档第一页中的文本的代码片段。

@Autowired
private DocumentOcrTemplate documentOcrTemplate;

public void runOcrOnDocument() {
    GoogleStorageLocation document = GoogleStorageLocation.forFile(
            "your-bucket", "test.pdf");
    GoogleStorageLocation outputLocationPrefix = GoogleStorageLocation.forFolder(
            "your-bucket", "output_folder/test.pdf/");

    ListenableFuture<DocumentOcrResultSet> result =
        this.documentOcrTemplate.runOcrForDocument(
            document, outputLocationPrefix);

    DocumentOcrResultSet ocrPages = result.get(5, TimeUnit.MINUTES);

    String page1Text = ocrPages.getPage(1).getText();
    System.out.println(page1Text);
}

19.5.3. 读取 OCR 输出文件

在某些用例中，您可能需要直接读取存储在 Google Cloud Storage 中的 OCR 输出文件。

​​DocumentOcrTemplate​​提供以下读取和处理 OCR 输出文件的方法：

• ​​readOcrOutputFileSet(GoogleStorageLocation jsonOutputFilePathPrefix)​​: 读取文件路径前缀下的 OCR 输出文件的集合，并返回分析的内容。 路径下的所有文件都应对应于同一文档。
• ​​readOcrOutputFile(GoogleStorageLocation jsonFile)​​: 读取单个 OCR 输出文件并返回分析的内容。

19.5.4. 读取 OCR 输出文件示例

下面的代码片段描述了如何读取单个文档的 OCR 输出文件。

@Autowired
private DocumentOcrTemplate documentOcrTemplate;

// Parses the OCR output files corresponding to a single document in a directory
public void parseOutputFileSet() {
  GoogleStorageLocation ocrOutputPrefix = GoogleStorageLocation.forFolder(
      "your-bucket", "json_output_set/");

  DocumentOcrResultSet result = this.documentOcrTemplate.readOcrOutputFileSet(ocrOutputPrefix);
  System.out.println("Page 2 text: " + result.getPage(2).getText());
}

// Parses a single OCR output file
public void parseSingleOutputFile() {
  GoogleStorageLocation ocrOutputFile = GoogleStorageLocation.forFile(
      "your-bucket", "json_output_set/test_output-2-to-2.json");

  DocumentOcrResultSet result = this.documentOcrTemplate.readOcrOutputFile(ocrOutputFile);
  System.out.println("Page 2 text: " + result.getPage(2).getText());
}

19.6. 示例

提供示例以显示Spring Cloud GCP与Google Cloud Vision的示例用法。

• 图像标记示例向您展示如何在 Spring 应用程序中使用图像标记。 应用程序生成标签，描述您在应用程序中指定的图像中的内容。
• 文档 OCR 演示展示了如何在 PDF/TIFF 文档上应用 OCR 处理以提取其文本内容。

20. 机密管理器

Google Cloud Secret Manager是一种安全便捷的存储 API 密钥、密码、证书和其他敏感数据的方法。 有关其功能的详细摘要，请参阅机密管理器文档。

Spring Cloud GCP 提供：

• 一个属性源，允许您指定 GCP 项目的机密并将其作为引导属性源加载到应用程序上下文中。
• 允许你在机密管理器中读取、写入和更新机密。SecretManagerTemplate

20.1. 依赖设置

要开始使用此库，请将 theartifact 添加到您的项目中。​​spring-cloud-gcp-starter-secretmanager​​

Maven 坐标，使用Spring Cloud GCP BOM：

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

格拉德尔坐标：

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

20.1.1. 配置

默认情况下，Spring Cloud GCP 机密管理器将使用应用程序默认凭据进行身份验证。 这可以使用身份验证属性覆盖。

20.2. 机密管理器属性源

Spring Cloud GCP 集成的 Google Cloud Secret Manager 使您能够将 Secret Manager 用作引导属性源。

这允许您在​​引导阶段​​（指加载 Spring 应用程序的初始阶段）期间将 Google Cloud Secret Manager 中的机密指定并作为属性加载到应用程序上下文中。

机密管理器属性源使用以下语法指定机密：

# 1. Long form - specify the project ID, secret ID, and version
sm://projects/<project-id>/secrets/<secret-id>/versions/<version-id>}

# 2.  Long form - specify project ID, secret ID, and use latest version
sm://projects/<project-id>/secrets/<secret-id>

# 3. Short form - specify project ID, secret ID, and version
sm://<project-id>/<secret-id>/<version-id>

# 4. Short form - default project; specify secret + version
#
# The project is inferred from the spring.cloud.gcp.secretmanager.project-id setting
# in your bootstrap.properties (see Configuration) or from application-default credentials if
# this is not set.
sm://<secret-id>/<version>

# 5. Shortest form - specify secret ID, use default project and latest version.
sm://<secret-id>

可以在以下位置使用此语法：

1. 在您的文件中：application.propertiesbootstrap.properties
   

# Example of the project-secret long-form syntax.
spring.datasource.password=${sm://projects/my-gcp-project/secrets/my-secret}

1. 使用注释访问值。@Value
   

// Example of using shortest form syntax.
@Value("${sm://my-secret}")

20.3. 密钥管理器模板

该类简化了创建、更新和读取机密的操作。​​SecretManagerTemplate​​

要开始使用此类，您可以在将初学者依赖项添加到项目中后注入该类的实例。​​@Autowired​​

@Autowired
private SecretManagerTemplate secretManagerTemplate;

有关机密管理器模板可用的操作的信息，请参阅机密管理器操作。

20.4. 在不重新启动应用程序的情况下刷新密钥

1. 在运行应用程序之前，请更改项目的配置文件，如下所示：
   
   将执行器启动器依赖项导入到您的项目中，
   
   

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

将以下属性添加到项目中。后者用于启用Spring Boot的Config Data API。application.properties

management.endpoints.web.exposure.include=refresh
spring.config.import=sm://

最后，将以下属性添加到项目的禁用 秘密管理器增强说唱短语。bootstrap.properties

spring.cloud.gcp.secretmanager.legacy=false

1. 运行应用程序后，更新存储在密钥管理器中的密钥。
2. 若要刷新机密，请将以下命令发送到应用程序服务器：
   

curl -X POST http://[host]:[port]/actuator/refresh

请注意，仅注释支持在不重新启动应用程序的情况下更新机密。@ConfigurationProperties@RefreshScope

20.5. 允许默认密钥

默认情况下，访问不存在的机密时，机密管理器将引发异常。

但是，如果要在这种情况下使用默认值，则可以将以下属性添加到项目的属性中。

`spring.cloud.gcp.secretmanager.allow-default-secret=true`

因此，当没有机密管理器并且不是有效的应用程序属性时，将解析带有批注的变量。​​@Value("${${sm://application-fake}:DEFAULT}")​​​​DEFAULT​​​​application-fake​​​​application-fake​​

20.6. 示例

提供了一个机密管理器示例应用程序，演示了模板类的基本属性源加载和用法。

21. 谷歌云密钥管理服务

借助 Google 云密钥管理服务 （KMS），您可以在单个集中式云服务中创建、导入和管理加密密钥并执行加密操作。

Spring Cloud GCP 提供了一个实用程序模板类，它使您可以方便地加密和解密二进制或文本数据。​​KmsTemplate​​

21.1. 依赖设置

要开始使用此库，请将 theartifact 添加到您的项目中。​​spring-cloud-gcp-starter-kms​​

Maven 坐标，使用Spring Cloud GCP BOM：

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

格拉德尔坐标：

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

21.2. 配置

可以使用春季云 GCP KMS 库配置以下选项。

21.3. 基本用法

将项目添加到项目后，将为项目激活自动配置类。​​spring-cloud-gcp-starter-kms​​​​com.google.cloud.spring.autoconfigure.kms.GcpKmsAutoConfiguration​​

自动配置提供的 Thebean 是使用 Spring Cloud GCP 支持 Google KMS 的入口点。此类允许您通过 URI 字符串（格式如下所述）在项目中指定云 KMS 密钥，并使用它执行加密/解密。​​com.google.cloud.spring.kms.KmsTemplate​​

模板类会自动验证从云 KMS API 收到的 CRC32 校验和响应，以验证响应的正确性。

21.3.1. 云 KMS 密钥 ID 格式

Spring Cloud GCP 提供以下密钥语法来指定项目中的云 KMS 密钥：

1. Shortest form - specify the key by key ring ID, and key ID.
 The project is inferred from the spring.cloud.gcp.kms.project-id if set, otherwise
 the default GCP project (such as using application-default-credentials) is used.
 The location is assumed to be `global`.

 {key-ring-id}/{key-id}

 2. Short form - specify the key by location ID, key ring ID, and key ID.
 The project is inferred from the spring.cloud.gcp.kms.project-id if set, otherwise
 the default GCP project (such as using application-default-credentials) is used.

 {location-id}/{key-ring-id}/{key-id}

 3. Full form - specify project ID, location ID, key ring ID, and key ID

 {project-id}/{location-id}/{key-ring-id}/{key-id}

 4. Long form - specify project ID, location ID, key ring ID, and key ID.
 This format is equivalent to the fully-qualified resource name of a Cloud KMS key.

 projects/{project-id}/locations/{location-id}/keyRings/{key-ring-id}/cryptoKeys/{key-id}

21.4. 示例

提供了云 KMS 示例应用程序，演示了基本的加密和解密操作。

22. 云运行时配置 API

Spring Cloud GCP可以将Google运行时配置API​用作Spring Cloud Config服务器来远程存储应用程序配置数据。

Spring Cloud GCP Config 支持是通过其自己的 Spring Boot 启动器提供的。 它允许使用 Google 运行时配置 API 作为 Spring Boot 配置属性的来源。

梅文坐标：

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

格拉德尔坐标：

dependencies {
    compile group: 'org.springframework.cloud',
    name: 'spring-cloud-gcp-starter-config',
    version: '3.4.0'
}

22.1. 配置

以下参数可在 Spring Cloud GCP 配置中配置：

22.2. 快速入门

1. 在调用的 Google 运行时配置 API 中创建配置。 换句话说，ifisandis，应该调用配置。${spring.application.name}_${spring.profiles.active}spring.application.namemyappspring.profiles.activeprodmyapp_prod
   
   为此，您应该安装Google Cloud SDK，拥有GoogleCloud Project并运行以下命令：
   
   

gcloud init # if this is your first Google Cloud SDK run.
gcloud beta runtime-config configs create myapp_prod
gcloud beta runtime-config configs variables set myapp.queue-size 25 --config-name myapp_prod

1. 使用应用程序的配置数据配置文件：bootstrap.properties
   

spring.application.name=myapp
spring.profiles.active=prod

1. 将注释添加到 Spring 管理的 bean：@ConfigurationProperties
   

@Component
@ConfigurationProperties("myapp")
public class SampleConfig {

  private int queueSize;

  public int getQueueSize() {
    return this.queueSize;
  }

  public void setQueueSize(int queueSize) {
    this.queueSize = queueSize;
  }
}

当您的 Spring 应用程序启动时，上述 bean 的字段值将设置为 25。​​queueSize​​​​SampleConfig​​

22.3. 在运行时刷新配置

Spring Cloud支持使用向端点的 POST 请求重新加载配置参数。​​/actuator/refresh​​

1. 添加弹簧引导执行器依赖项：
   
   梅文坐标：
   
   

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

格拉德尔坐标：

dependencies {
    implementation("org.springframework.boot:spring-boot-starter-actuator")
}

1. 添加到 Spring 配置类中，以使参数在运行时可重新加载。@RefreshScope
2. 添加到您的允许无限制访问。management.endpoints.web.exposure.include=refreshapplication.properties/actuator/refresh
3. 使用以下命令更新属性：gcloud
   

$ gcloud beta runtime-config configs variables set \
  myapp.queue_size 200 \
  --config-name myapp_prod

1. 向刷新终结点发送 POST 请求：
   

$ curl -XPOST https://myapp.host.com/actuator/refresh

22.4. 示例

提供示例应用程序和代码实验室。

23. 云铸造厂

Spring Cloud GCP 为 Cloud Foundry 的GCP Service Broker 提供支持。 我们的 Pub/Sub、Cloud Spanner、Storage、Cloud Trace 和 Cloud SQL MySQL 和 PostgreSQL 入门器具有 Cloud Foundry 感知和检索属性，如项目 ID、凭据等，这些属性用于从 Cloud Foundry 环境进行自动配置。

为了利用Cloud Foundry支持，请确保添加了以下依赖项：

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

在 Pub/Sub 的主题和订阅或存储的存储桶名称等情况下，这些参数未在自动配置中使用，您可以使用 Spring Boot 提供的 VCAP 映射来获取它们。 例如，要检索已置备的发布/订阅主题，可以使用应用程序环境中的属性。​​vcap.services.mypubsub.credentials.topic_name​​

23.1. 用户提供的服务

用户提供的服务使开发人员能够在Cloud Foundry上运行其应用程序时使用市场上不可用的服务。 例如，您可能希望使用用户提供的服务，该服务指向整个单位使用的共享 Google 服务（如 Cloud Spanner）。

为了让 Spring Cloud GCP 将您用户提供的服务检测为 Google 云服务，您必须添加一个实例标签，指示它使用的 Google 云服务。 该标签应该只是Google服务的Cloud Foundry名称。

例如，如果您使用 Cloud Spanner 创建用户提供的服务，则可以运行：

$ cf create-user-provided-service user-spanner-service -t "google-spanner" ...

这允许Spring Cloud GCP从Cloud Foundry检索正确的服务属性，并在应用程序的自动配置中使用它们。

下面提供了Google服务名称到Cloud Foundry名称的映射：

24. Kotlin 支持

最新版本的 Spring 框架为 Kotlin 提供了一流的支持。 对于 Spring 的 Kotlin 用户，Spring Cloud GCP 库开箱即用，并且可以与 Kotlin 应用程序完全互操作。

有关在 Kotlin 中构建 Spring 应用程序的更多信息，请参阅Spring Kotlin 文档。

24.1. 先决条件

确保您的 Kotlin 应用程序已正确设置。 根据您的构建系统，您需要在项目中包含正确的 Kotlin 构建插件：

• Kotlin Maven 插件
• Kotlin Gradle 插件

根据应用程序的需求，您可能需要使用编译器插件来增强构建配置：

• Kotlin Spring 插件：为了方便起见，使您的 Spring 配置类/成员成为非最终的。
• Kotlin JPA 插件：允许在 Kotlin 应用程序中使用 JPA。

正确配置 Kotlin 项目后，Spring Cloud GCP 库将在您的应用程序中工作，无需任何其他设置。

24.2. 示例

提供了一个Kotlin 示例应用程序来演示 Kotlin 中的工作 Maven 设置和各种 Spring Cloud GCP 集成。

25. 配置属性

要查看所有与 GCP 相关的配置属性的列表，请查看附录页面。

26. 从春季云 GCP 1.x 到 2.x 的迁移指南

26.1. Maven 组 ID 更改

Spring Cloud 将 Spring Cloud GCP 和其他云提供商从他们的发布列车中解脱出来。 要使用新取消捆绑的库，请添加物料清单 （BOM） 并更改文件中的组 ID：​​spring-cloud-gcp-dependencies​​​​spring-cloud-gcp​​​​pom.xml​​

之前（pom.xml）

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.springframework.cloud</groupId>
      <artifactId>spring-cloud-dependencies</artifactId>
      <version>${spring-cloud.version}</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependencies>
  <dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-gcp-starter</artifactId>
  </dependency>
</dependencies>

After (pom.xml)

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

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

26.2. Java 软件包名称更改

Spring Cloud GCP 中的所有代码都已从 over 移动到包中。​​org.springframework.cloud.gcp​​​​com.google.cloud.spring​​

26.3. 删除已弃用的项目

财产​​spring.cloud.gcp.datastore.emulatorHost​​

使用代替​​spring.cloud.gcp.datastore.host​​

​​GcpPubSubHeaders.ACKNOWLEDGEMENT​​

使用，类型为​​GcpPubSubHeaders.ORIGINAL_MESSAGE​​​​BasicAcknowledgeablePubsubMessage​​

​​SpannerQueryOptions.getQueryOptions()​​

用​​getOptions()​​

​​PubSubTemplate.subscribe(String, MessageReceiver)​​

用​​subscribe(String, Consumer<BasicAcknowledgeablePubsubMessage>)​​

​​SpannerReadOptions.getReadOptions()​​

用​​getOptions()​​

云日志记录

​​org.springframework.cloud.gcp.autoconfigure.logging​​包

从模块使用。​​com.google.cloud.spring.logging​​​​spring-cloud-gcp-logging​​

云日志记录日志追加程序

从模块替换。​​org/springframework/cloud/gcp/autoconfigure/logging/logback[-json]-appender.xml​​​​com/google/cloud/spring/logging/logback[-json]-appender.xml​​​​spring-cloud-gcp-logging​​

倒数弹簧.xml

<configuration>
  <include resource="com/google/cloud/spring/logging/logback-appender.xml" />
  ...
</configuration>