本教程介绍了如何创建一个翻译工作流,以等待您的输入(人机协同),并将 Firestore 数据库、两个 Cloud Run 函数、Cloud Translation API 以及使用要实时更新的 Firebase SDK 的网页关联起来。
借助 Workflows,您可以支持回调端点(或 webhook),用于等待 HTTP 请求到达该端点,并在稍后继续执行该工作流。在这种情况下,工作流会等待您的输入拒绝或验证某些文本的翻译,但也可以等待外部进程。如需了解详情,请参阅等待使用回调。
架构
本教程会创建一个 Web 应用,以便允许您执行以下操作:
- 在翻译网页上,输入您希望从英语翻译成法语的文本。点击翻译。
- 在网页中调用一个 Cloud Run 函数来启动工作流的执行。要翻译的文本将作为参数传递给函数和工作流。
- 该文本保存在 Cloud Firestore 数据库中。调用 Cloud Translation API。返回的译文存储在数据库中。使用 Firebase 托管部署 Web 应用,并实时更新以显示翻译后的文本。
- 工作流的
create_callback
步骤会创建一个回调端点网址,此网址也保存在 Firestore 数据库中。此时,网页会同时显示验证和拒绝按钮。 - 工作流现已暂停,并等待对回调端点网址的显式 HTTP POST 请求。
- 您可以决定是验证还是拒绝翻译。点击一个按钮会调用第二个 Cloud Run 函数,而该 Cloud Run 函数又会调用由工作流创建的回调端点,并传递审批状态。工作流恢复执行,并将审批状态
true
或false
保存在 Firestore 数据库中。
下图简要展示了此过程:
目标
- 部署 Web 应用。
- 创建 Firestore 数据库以存储翻译请求。
- 部署 Cloud Run functions 函数以运行工作流。
- 部署并运行工作流以编排整个过程。
费用
在本文档中,您将使用 Google Cloud 的以下收费组件:
准备工作
您的组织定义的安全限制条件可能会导致您无法完成以下步骤。如需了解相关问题排查信息,请参阅在受限的 Google Cloud 环境中开发应用。
- Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
Create or select a Google Cloud project.
-
Create a Google Cloud project:
gcloud projects create PROJECT_ID
Replace
PROJECT_ID
with a name for the Google Cloud project you are creating. -
Select the Google Cloud project that you created:
gcloud config set project PROJECT_ID
Replace
PROJECT_ID
with your Google Cloud project name.
-
-
Make sure that billing is enabled for your Google Cloud project.
-
Enable the App Engine, Cloud Build, Cloud Run functions, Firestore, Translation, and Workflows APIs:
gcloud services enable appengine.googleapis.com
cloudbuild.googleapis.com cloudfunctions.googleapis.com firestore.googleapis.com translate.googleapis.com workflows.googleapis.com - Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
Create or select a Google Cloud project.
-
Create a Google Cloud project:
gcloud projects create PROJECT_ID
Replace
PROJECT_ID
with a name for the Google Cloud project you are creating. -
Select the Google Cloud project that you created:
gcloud config set project PROJECT_ID
Replace
PROJECT_ID
with your Google Cloud project name.
-
-
Make sure that billing is enabled for your Google Cloud project.
-
Enable the App Engine, Cloud Build, Cloud Run functions, Firestore, Translation, and Workflows APIs:
gcloud services enable appengine.googleapis.com
cloudbuild.googleapis.com cloudfunctions.googleapis.com firestore.googleapis.com translate.googleapis.com workflows.googleapis.com - 更新 Google Cloud CLI 组件:
gcloud components update
- 使用您的账号登录:
gcloud auth login
- 设置本教程中使用的项目 ID 和默认位置:
export GOOGLE_CLOUD_PROJECT=PROJECT_ID export REGION=REGION gcloud config set workflows/location ${REGION}
替换以下内容:
部署第一个 Cloud Run 函数
此 Cloud Run 函数启动工作流的执行。要翻译的文本将作为参数传递给函数和工作流。
创建一个名为
callback-translation
的目录,其中包含名为invokeTranslationWorkflow
、translationCallbackCall
和public
的子目录:mkdir -p ~/callback-translation/{invokeTranslationWorkflow,translationCallbackCall,public}
切换到
invokeTranslationWorkflow
目录:cd ~/callback-translation/invokeTranslationWorkflow
创建一个文件名为
index.js
且包含以下 Node.js 代码的文本文件:创建一个文件名为
package.json
且包含以下npm
元数据的文本文件:使用 HTTP 触发器部署函数,并允许未经身份验证的访问:
gcloud functions deploy invokeTranslationWorkflow \ --region=${REGION} \ --runtime nodejs14 \ --entry-point=invokeTranslationWorkflow \ --set-env-vars PROJECT_ID=${GOOGLE_CLOUD_PROJECT},CLOUD_REGION=${REGION},WORKFLOW_NAME=translation_validation \ --trigger-http \ --allow-unauthenticated
部署该函数可能需要几分钟的时间。或者,您也可以使用 Google Cloud 控制台中的 Cloud Run 函数界面来部署函数。
部署该函数后,您可以确认
httpsTrigger.url
属性:gcloud functions describe invokeTranslationWorkflow
记下返回的网址,以便在后续步骤中使用。
部署第二个 Cloud Run 函数
此 Cloud Run 函数会向工作流创建的回调端点发出 HTTP POST 请求,并传递审批状态以反映翻译已验证还是被拒绝。
切换到
translationCallbackCall
目录:cd ../translationCallbackCall
创建一个文件名为
index.js
且包含以下 Node.js 代码的文本文件:创建一个文件名为
package.json
且包含以下npm
元数据的文本文件:使用 HTTP 触发器部署函数,并允许未经身份验证的访问:
gcloud functions deploy translationCallbackCall \ --region=${REGION} \ --runtime nodejs14 \ --entry-point=translationCallbackCall \ --trigger-http \ --allow-unauthenticated
部署该函数可能需要几分钟的时间。或者,您也可以使用 Google Cloud 控制台中的 Cloud Run 函数界面来部署函数。
部署该函数后,您可以确认
httpsTrigger.url
属性:gcloud functions describe translationCallbackCall
记下返回的网址,以便在后续步骤中使用。
部署工作流
工作流由一系列使用 Workflows 语法描述的步骤组成,该语法可以采用 YAML 或 JSON 格式编写。这是工作流的定义。创建工作流后,可以进行部署,使其可以执行。
切换到
callback-translation
目录:cd ..
创建一个文件名为
translation-validation.yaml
且包含以下内容的文本文件:创建工作流后,您可以对其进行部署,但不要执行工作流:
gcloud workflows deploy translation_validation --source=translation-validation.yaml
创建您的 Web 应用
创建一个调用 Cloud Functions 函数的 Web 应用,以启动工作流的执行。网页会实时更新,提供翻译请求的结果。
切换到
public
目录:cd public
创建一个文件名为
index.html
且包含以下 HTML 标记的文本文件。(在稍后的步骤中,您将修改index.html
文件并添加 Firebase SDK 脚本。)创建一个文件名为
script.js
且包含以下 JavaScript 代码的文本文件:修改
script.js
文件,将UPDATE_ME
占位符替换为您之前记下的 Cloud Run 函数网址。在
translateBtn.addEventListener
方法中,将const fnUrl = UPDATE_ME;
替换为:const fnUrl = "https://REGION-PROJECT_ID.cloudfunctions.net/invokeTranslationWorkflow";
在
callCallbackUrl
函数中,将const fnUrl = UPDATE_ME;
替换为:const fnUrl = "https://REGION-PROJECT_ID.cloudfunctions.net/translationCallbackCall";
创建一个文件名为
style.css
且包含以下级联样式的文本文件:
将 Firebase 添加到您的网页应用
在本教程中,HTML 页面、JavaScript 脚本和 CSS 样式表使用 Firebase Hosting 部署为静态资源,但它们可以托管在任何位置,并在您自己的机器上本地提供以进行测试。
创建 Firebase 项目
您需要先创建一个要关联到您的应用的 Firebase 项目,然后才能将 Firebase 添加到您的应用。
-
在 Firebase 控制台中,点击创建项目,然后从下拉菜单中选择现有的 Google Cloud 项目,以将 Firebase 资源添加到该项目中。
-
点击继续,直到您看到添加 Firebase 的选项。
-
跳过为您的项目设置 Google Analytics 的步骤。
-
点击添加 Firebase。
Firebase 会自动为您的 Firebase 项目预配资源。完成此过程后,您将进入 Firebase 控制台中您的项目的概览页面。
在 Firebase 中注册您的应用
有了 Firebase 项目后,您就可以将自己的 Web 应用添加到其中了。
在项目概览页面的中心,点击 Web 图标 (</>) 以启动设置工作流。
输入您的应用的别名。
只有您能在 Firebase 控制台中看到。
暂时跳过设置 Firebase Hosting 的步骤。
点击注册应用并转到该控制台。
启用 Cloud Firestore
Web 应用使用 Cloud Firestore 接收和保存数据。您需要启用 Cloud Firestore。
在 Firebase 控制台的构建部分中,点击 Firestore 数据库。
(您可能需要先展开左侧导航窗格以查看构建部分。)
在 Cloud Firestore 窗格中,点击创建数据库。
选择以测试模式开始,并使用如下所示的安全规则:
rules_version = '2'; service cloud.firestore { match /databases/{database}/documents { match /{document=**} { allow read, write; } } }
在阅读有关安全规则的免责声明后,点击下一步。
设置 Cloud Firestore 数据的存储位置。您可以接受默认值,也可以选择您附近的区域。
点击启用以预配 Firestore。
添加 Firebase SDK 并初始化 Firebase
Firebase 为大多数 Firebase 产品提供 JavaScript 库。在使用 Firebase Hosting 之前,您必须将 Firebase SDK 添加到您的 Web 应用。
- 要在您的应用中初始化 Firebase,您需要提供应用的 Firebase 项目配置。
- 在 Firebase 控制台中,转到您的项目设置 。
- 在您的应用窗格中,选择您的应用。
- 在 SDK 设置和配置窗格中,如需从 CDN 加载 Firebase SDK 库,请选择 CDN。
- 将代码段复制到
<body>
标记底部的index.html
文件中,替换XXXX
占位符值。
安装 Firebase JavaScript SDK。
如果您还没有
package.json
文件,请从callback-translation
目录中运行以下命令来创建一个:npm init
运行以下命令,安装
firebase
npm 软件包并将其保存到package.json
文件:npm install --save firebase
初始化和部署您的项目
如需将本地项目文件关联到 Firebase 项目,您必须初始化您的项目。然后,您可以部署您的 Web 应用。
从
callback-translation
目录运行以下命令:firebase init
选择
Configure files for Firebase Hosting and (optionally) set up GitHub Action deploys
选项。选择使用现有项目并输入您的项目 ID。
接受
public
作为默认公共根目录。选择配置单页应用。
跳过使用 GitHub 设置自动构建和部署的步骤。
在
File public/index.html already exists. Overwrite?
提示符处输入否。切换到
public
目录:cd public
在
public
目录中,运行以下命令以将您的项目部署到网站:firebase deploy --only hosting
在本地测试 Web 应用
借助 Firebase Hosting,您可以在本地查看和测试更改并与模拟后端项目资源交互。使用 firebase serve
时,您的应用会与托管内容和配置的模拟后端进行交互,但与所有其他项目资源的实际后端交互。在本教程中,您可以使用 firebase serve
,但在进行范围更广的测试时不建议使用。
从
public
目录运行以下命令:firebase serve
使用返回的本地网址(通常为
http://localhost:5000
)打开您的 Web 应用。输入一些英文文本,然后点击翻译。
此时应显示法语文本的翻译。
您现在可以点击验证或拒绝。
在 Firestore 数据库中,您可以验证内容。它应该类似于以下内容:
approved: true callback: "https://workflowexecutions.googleapis.com/v1/projects/26811016474/locations/us-central1/workflows/translation_validation/executions/68bfce75-5f62-445f-9cd5-eda23e6fa693/callbacks/72851c97-6bb2-45e3-9816-1e3dcc610662_1a16697f-6d90-478d-9736-33190bbe222b" text: "The quick brown fox jumps over the lazy dog." translation: "Le renard brun rapide saute par-dessus le chien paresseux."
approved
状态为true
或false
,具体取决于您是验证还是拒绝翻译。
恭喜!您已创建了一个使用 Workflows 回调的人机协同翻译工作流。
清理
如果您为本教程创建了一个新项目,请删除项目。 如果您使用的是现有项目,希望保留此项目且不保留本教程中添加的任何更改,请删除为教程创建的资源。
删除项目
为了避免产生费用,最简单的方法是删除您为本教程创建的项目。
要删除项目,请执行以下操作:
- In the Google Cloud console, go to the Manage resources page.
- In the project list, select the project that you want to delete, and then click Delete.
- In the dialog, type the project ID, and then click Shut down to delete the project.
删除教程资源
移除您在教程设置过程中添加的 gcloud CLI 默认配置:
gcloud config unset workflows/location
删除在本教程中创建的工作流:
gcloud workflows delete WORKFLOW_NAME
删除您在本教程中创建的 Cloud Run 函数:
gcloud functions delete FUNCTION_NAME
您也可以通过 Google Cloud 控制台删除 Cloud Run functions。