本教學課程示範如何使用 Cloud Run 函式實作 Slack Slash 指令,藉此搜尋 Google Knowledge Graph API。
目標
- 在 Slack 中建立 Slash Command。
- 編寫及部署 HTTP Cloud Run 函式。
- 使用 Slash Command 搜尋 Google 知識圖譜 API。
費用
在本文件中,您會使用 Google Cloud的下列計費元件:
- Cloud Run functions
如要根據預測用量估算費用,請使用 Pricing Calculator。
事前準備
- 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.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator
(
roles/resourcemanager.projectCreator
), which contains theresourcemanager.projects.create
permission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
-
Enable the Cloud Functions, Cloud Build, and Google Knowledge Graph Search APIs.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (
roles/serviceusage.serviceUsageAdmin
), which contains theserviceusage.services.enable
permission. Learn how to grant roles. -
Install the Google Cloud CLI.
-
如果您使用外部識別資訊提供者 (IdP),請先 使用聯合身分登入 gcloud CLI。
-
如要初始化 gcloud CLI,請執行下列指令:
gcloud init
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator
(
roles/resourcemanager.projectCreator
), which contains theresourcemanager.projects.create
permission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
-
Enable the Cloud Functions, Cloud Build, and Google Knowledge Graph Search APIs.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (
roles/serviceusage.serviceUsageAdmin
), which contains theserviceusage.services.enable
permission. Learn how to grant roles. -
Install the Google Cloud CLI.
-
如果您使用外部識別資訊提供者 (IdP),請先 使用聯合身分登入 gcloud CLI。
-
如要初始化 gcloud CLI,請執行下列指令:
gcloud init
- 準備開發環境。 <0x
- 使用者在 Slack 頻道中執行
/kg <search_query>
Slash 指令。 - Slack 會將指令的有效負載傳送至函式的觸發端點。
- 該函式會將使用者的搜尋查詢傳送至 Knowledge Graph API。
- 知識圖譜 API 以任何相符的結果回應。
- 函式會將回應格式化為 Slack 訊息。
- 函式會將訊息傳回 Slack。
- 使用者在 Slack 頻道中看見設定好格式的回應。
將應用程式存放區範例複製到本機電腦中:
Node.js
git clone https://github.com/GoogleCloudPlatform/nodejs-docs-samples.git
您也可以 下載 zip 格式的範例,然後解壓縮該檔案。
Python
git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git
您也可以 下載 zip 格式的範例,然後解壓縮該檔案。
Go
git clone https://github.com/GoogleCloudPlatform/golang-samples.git
您也可以 下載 zip 格式的範例,然後解壓縮該檔案。
Java
git clone https://github.com/GoogleCloudPlatform/java-docs-samples.git
您也可以 下載 zip 格式的範例,然後解壓縮該檔案。
Ruby
git clone https://github.com/GoogleCloudPlatform/ruby-docs-samples.git
您也可以 下載 zip 格式的範例,然後解壓縮該檔案。
變更為包含 Cloud Run 函式程式碼範例的目錄:
Node.js
cd nodejs-docs-samples/functions/slack/
Python
cd python-docs-samples/functions/slack/
Go
cd golang-samples/functions/slack/
Java
cd java-docs-samples/functions/slack/
Ruby
cd ruby-docs-samples/functions/slack/
建立 Slack 應用程式,以託管 Slack Slash 指令。將其與您有權安裝整合功能的 Slack 團隊建立關聯。
前往「Slash commands」 並按一下 [Create new command] 按鈕。
輸入
/kg
做為指令名稱。輸入指令的網址:
Node.js
https://YOUR_REGION-YOUR_PROJECT_ID.cloudfunctions.net/kgSearch
Python
https://YOUR_REGION-YOUR_PROJECT_ID.cloudfunctions.net/kg_search
Go
https://YOUR_REGION-YOUR_PROJECT_ID.cloudfunctions.net/KGSearch
Java
https://YOUR_REGION-YOUR_PROJECT_ID.cloudfunctions.net/java-slack-function
Ruby
https://YOUR_REGION-YOUR_PROJECT_ID.cloudfunctions.net/kg_search
其中
YOUR_REGION
是函式部署的區域,YOUR_PROJECT_ID
則是 Cloud 專案 ID。當您的函式部署完成時,這兩個值都可以在您的終端機中看見。
按一下 [Save]。
前往「Basic Information」。
按一下「將應用程式安裝到工作區」,然後按照畫面上的指示,為工作區啟用應用程式。
您的 Slack Slash Command 應該很快就會上線。
將指令輸入到您的 Slack 頻道中:
/kg giraffe
觀察記錄以確定執行已經完成:
gcloud functions logs read --limit 100
- 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 components update
視覺化資料流動過程
Slack Slash Command 教學課程應用程式中的資料流動過程涉及數個步驟:
以下可能有助於透過視覺化的方式瞭解步驟:
建立 Knowledge Graph API 金鑰
在Google Cloud 控制台的「憑證」頁面中,按一下「建立憑證」按鈕,然後選取「API 金鑰」。請記下這組金鑰,因為您會在下一節使用這組金鑰存取 Knowledge Graph API。
準備函式
部署函式
如要部署函式,在您 (或 Slack) 對函式端點發出 HTTP POST 要求時執行,請在包含範例程式碼 (或 Java 的 pom.xml
檔案) 的目錄中執行下列指令:
將 YOUR_SLACK_SIGNING_SECRET
替換為 Slack 在應用程式設定的「基本資訊」頁面中提供的簽署密鑰,並將 YOUR_KG_API_KEY
替換為您先前建立的 Knowledge Graph API 金鑰。
Node.js
gcloud functions deploy kgSearch \ --runtime nodejs20 \
--trigger-http \
--set-env-vars "SLACK_SECRET=YOUR_SLACK_SIGNING_SECRET
,KG_API_KEY=YOUR_KG_API_KEY
" \
--allow-unauthenticated
使用 --runtime
標記指定支援的 Node.js 版本執行階段 ID,以執行函式。
Python
gcloud functions deploy kg_search \ --runtime python312 \
--trigger-http \
--set-env-vars "SLACK_SECRET=YOUR_SLACK_SIGNING_SECRET
,KG_API_KEY=YOUR_KG_API_KEY
" \
--allow-unauthenticated
使用 --runtime
標記指定支援的 Python 版本執行階段 ID,以執行函式。
Go
gcloud functions deploy KGSearch \ --runtime go121 \
--trigger-http \
--set-env-vars "SLACK_SECRET=YOUR_SLACK_SIGNING_SECRET
,KG_API_KEY=YOUR_KG_API_KEY
" \
--allow-unauthenticated
Java
gcloud functions deploy java-slack-function \ --entry-point functions.SlackSlashCommand \ --runtime java17 \ --memory 512MB \
--trigger-http \
--set-env-vars "SLACK_SECRET=YOUR_SLACK_SIGNING_SECRET
,KG_API_KEY=YOUR_KG_API_KEY
" \
--allow-unauthenticated
使用 --runtime
標記指定支援的 Java 版本執行函式的執行階段 ID。
Ruby
gcloud functions deploy kg_search --runtime ruby33 \
--trigger-http \
--set-env-vars "SLACK_SECRET=YOUR_SLACK_SIGNING_SECRET
,KG_API_KEY=YOUR_KG_API_KEY
" \
--allow-unauthenticated
使用 --runtime
標記指定支援的 Ruby 版本執行階段 ID,以執行函式。
設定應用程式
部署函式後,您需要建立 Slack 斜線指令,在每次觸發指令時將查詢傳送至函式:
瞭解程式碼
匯入依附元件
應用程式必須匯入數個依附元件,才能與 Google Cloud Platform 服務通訊:
Node.js
Python
Go
Java
Ruby
接收 webhook
下列函式會在您 (或 Slack) 對函式端點提出 HTTP POST 要求時執行:
Node.js
Python
Go
Java
Ruby
下列函式會驗證 Slack 提供的 X-Slack-Signature
標頭,藉此驗證傳入的要求:
Node.js
Python
Go
Java
Ruby
查詢知識圖譜 API
下列函式將含有使用者搜尋查詢的要求傳送至知識圖譜 API:
Node.js
Python
Go
Java
Ruby
設定 Slack 訊息格式
最後,下列函式將知識圖譜結果的格式設定為豐富格式的 Slack 訊息,並顯示給使用者:
Node.js
Python
Go
Java
Ruby
Slack API 逾時
Slack API 預期函式會在收到 Webhook 要求後3 秒內回覆。
本教學課程中的指令通常會在 3 秒內回應。如果是執行時間較長的指令,建議您設定函式,將要求 (包括其 response_url
) 推送至做為工作佇列的 Pub/Sub 主題。
接著,您可以建立由 Pub/Sub 觸發的第二個函式,處理這些工作並將結果傳回 Slack 的 response_url
。
使用 Slash 指令
清除所用資源
如要避免系統向您的 Google Cloud 帳戶收取本教學課程中所用資源的相關費用,請刪除含有該項資源的專案,或者保留專案但刪除個別資源。
刪除專案
如要避免付費,最簡單的方法就是刪除您為了本教學課程所建立的專案。
如要刪除專案:
刪除函式
如要刪除您在本教學課程中部署的函式,請執行下列指令:
Node.js
gcloud functions delete kgSearch
Python
gcloud functions delete kg_search
Go
gcloud functions delete KGSearch
Java
gcloud functions delete java-slack-function
Ruby
gcloud functions delete kg_search
您也可以從Google Cloud 控制台刪除 Cloud Run 函式。