gactions 使用手冊

本指南將說明如何在常見的使用情境下，使用 gactions 指令列介面 (CLI) 工具。如要瞭解如何建構端對端動作，請參閱 Conversational Actions Build 說明文件。

提示：如要查看執行指令的更多資訊，請使用 --verbose 旗標。

專案同步處理

使用 Actions SDK 時，gaction 是工具，用於在 Actions 主控台和本機檔案系統之間同步處理動作專案。

gactions pull 作業會將專案從 Actions 主控台匯出至本機檔案系統，而 gactions push 作業會將專案從本機檔案系統推送至 Actions 主控台。

透過 Actions 主控台下載動作

執行 gactions pull，將 Actions 專案的設定複製到本機檔案系統。

要複製的專案 project-id 可以在指令列中傳遞，或是在 settings/settings.yaml 檔案中寫入。如果同時存在，則 CLI 的優先順序高於以選項的形式傳送的值。

mkdir -p myAction/sdk
cd myAction/sdk
gactions pull --project-id my-project-id
Pulling your project files from Draft for a project id: "my-project-id"
✔ Done. You should see the files written in path/to/myAction/sdk
ls -l
total 8
drwxr-x---  3 user  primarygroup   96 May  7 10:00 actions
drwxr-x---  4 user  primarygroup  128 May  7 10:00 custom
-rw-r-----  1 user  primarygroup   15 May  7 10:00 manifest.yaml
drwxr-x---  3 user  primarygroup   96 May  7 10:00 settings
vi settings/settings.yaml
// change projectId to "my-other-project-id"
gactions pull
Pulling your project files from Draft for a project id: "my-other-project-id"
path/to/myAction/sdk/manifest.yaml already exists. Would you like to overwrite it?. [y/n]
...
✔ Done. You should see the files written in path/to/myAction/sdk

以上程式碼片段說明如何從專案草稿提取動作。你也可以從特定版本的動作中擷取。版本代表了 Action 專案提交的複本，可部署至發布版本。

--version-id 旗標會指定要提取的版本。

mkdir -p myAction/sdk
cd myAction/sdk
gactions pull --project-id my-project-id --version-id my-version-id
Pulling version "my-version-id" of the project "my-project-id" from Actions Console...
✔ Done. You should see the files written in path/to/myAction/sdk
ls -l
total 8
drwxr-x---  3 user  primarygroup   96 May  7 10:00 actions
drwxr-x---  4 user  primarygroup  128 May  7 10:00 custom
-rw-r-----  1 user  primarygroup   15 May  7 10:00 manifest.yaml
drwxr-x---  3 user  primarygroup   96 May  7 10:00 settings

如要在不要求確認的情況下覆寫檔案的本機副本，請使用 --force 旗標。使用 --clean 標記移除遠端草稿或版本中沒有的任何本機檔案。搭配使用這些動作，即可取得 Actions 主控台專案的確切副本。

touch local_file.txt
gactions pull --force
Pulling your project files from Draft for a project id: "my-project-id"
[WARNING] 2020/05/07 17:34:32 path/to/myAction/sdk/local_file.txt is not present in the draft of your Action. To remove, run pull with --clean flag.
✔ Done. You should see the files written in path/to/myAction/sdk
gactions pull --force --clean
Pulling your project files from Draft for a project id: "my-project-id"
[WARNING] 2020/05/07 17:43:44 path/to/myAction/sdk/local_file.txt is not present in the draft of your Action. Removing path/to/myAction/sdk/local_file.txt.
✔ Done. You should see the files written in path/to/myAction/sdk

將動作推送至動作主控台專案草稿

執行 gactions push，將變更從本機檔案系統推送至控制台的「動作草稿」。在開發期間，這個流程相當實用，而且您可以查看在 Actions 主控台查看的變更，而不會影響提供測試用的版本。

gactions push
Pushing your project files to your Actions console draft for a project id: "my-project-id". This may take a few minutes.
Sending configuration files
Waiting for server to respond.
✔ Done. You can now navigate to the Actions Console: https://console.actions.google.com/project/my-project-id/overview to view your project. If you want to test your changes in the simulator, run "gactions deploy preview"

從原始碼管理系統匯入現有專案

如果您想透過版本管控系統中修訂版本編輯現有專案：

查看目標修訂版本 (視系統而定)。
替換專案 settings.yaml 中的 projectId 值。
您也可以執行 gactions push 將本機設定檔複製到操作專案。

git clone https://github.com/my/repo.git
Cloning into 'repo'...
remote: Enumerating objects: 10, done.
remote: Counting objects: 100% (10/10), done.
remote: Compressing objects: 100% (9/9), done.
remote: Total 51 (delta 3), reused 3 (delta 1), pack-reused 41
Receiving objects: 100% (51/51), 36.86 KiB | 3.69 MiB/s, done.
Resolving deltas: 100% (11/11), done.
cd repo/sdk/
vi settings/settings.yaml
// change the value of `projectId`
gactions push

列出版本

執行 gactions versions list 以查看動作版本的詳細資料。如要進一步瞭解版本狀態，請參閱「狀態」參考資料。

gactions versions list
Version         Status          Last Modified By        Modified On     
1           Created     your-email@your-domain.com  2020-09-28 20:22:04

如果部署作業的狀態顯示「建立失敗」，您可以在主控台的「發布」部分下方取得詳細資料。

部署專案

gactions deploy 指令可讓您在 Actions 模擬器中部署專案，或部署至 Alpha 版/Beta 版/正式版頻道。

在模擬器中預覽

執行 gactions deploy preview 將您的動作部署至「預覽」，如此一來，即可在主控台中測試您的動作，而不必更新動作專案版本或影響其他開發人員。換句話說，您在本機檔案系統中所做的任何變更都不會套用至已部署的 Actions 專案版本，但可以透過預覽版本進行測試。

gactions deploy preview
Deploying your project files to your Actions console preview for a project id: "my-project". This may take a few minutes.
Sending configuration files
Waiting for server to respond.
✔ Done. You can now navigate to the Actions Console simulator to test your changes: http://console.actions.google.com/project/my-project/simulator?disableAutoPreview

建立版本

執行 gactions deploy 即可為 Alpha/Beta/prod 版本建立版本，您可以透過「動作」控制台的部署區段進行管理。使用 Alpha 版測試和/或 Beta 版測試頻道

gactions deploy alpha
Deploying your project files to a actions.channels.Alpha channel for a project id: "my-project-id"
Sending configuration files
Waiting for server to respond.
✔ Done. Your Action was deployed to actions.channels.Alpha channel. You can check status of deployment in the Actions Console.

發布版本

執行 gactions release-channels list 以查看動作的發布版本詳細資訊。您可以使用這個指令來識別每個管道的部署版本或待處理版本。

gactions release-channels list
Release Channel             Current Version             Pending Version
alpha                   1                     N/A

帳戶連結

gactions encrypt 和 gactions decrypt 指令可讓您管理 OAuth2 用戶端密鑰。這些指令僅適用於帳戶連結。

加密 OAuth2 帳戶連結用戶端密鑰

執行 gactions encrypt，以安全地新增用於驗證 OAuth2 帳戶連結的用戶端密鑰，或是使用新的加密金鑰來加密現有的密鑰。

gactions encrypt
Write your secret: *********************
Encrypting your client secret
path/to/myAction/sdk/settings/accountLinkingSecret.yaml already exists. Would you like to overwrite it?. [y/n]
y
✔ Done. Encrypted secret was written to path/to/myAction/sdk/settings/accountLinkingSecret.yaml

存取加密帳戶連結密鑰的純文字值。

如果您需要暫時存取專案密鑰的純文字值，請執行 gactions decrypt。指令會將所選值列印成您選擇的文字檔。建議您將目的地檔案放在專案的根目錄資料夾，以免純文字值發生意外外洩。

gactions decrypt ../../burn_after_read.txt
Decrypting your client secret
✔ Done. Check path/above/myActions/burn_after_read.txt to find decrypted client secret.
vi ../../burn_after_read.txt
rm ../../burn_after_read.txt