本教學課程說明如何使用 Google Meet REST API 搭配 Google WorkspaceEvents API 與 Google Cloud Pub/Sub,觀察會議事件並做出回應。範例應用程式會記錄會議的開始和結束時間、參與者加入或離開的時間,以及產生任何會議成果的時間。
如要進一步瞭解如何使用事件,請參閱 Google Workspace Event API 說明文件中的「訂閱 Google Meet 事件」一文。
必要條件
如果您需要為貴機構啟用上述任何一項先決條件,請要求 Google Workspace 管理員開啟:
- 擁有可存取 Google Meet 的 Google Workspace 帳戶。
- 具備建立 Google Cloud 專案的權限。
- 已安裝 Python 3。
- 已安裝 gcloud CLI。
準備環境
本節說明如何為本教學課程建立及設定本機環境和 Google Cloud 專案,
建立工作目錄和 Python 虛擬環境
如要建立並啟用新的虛擬環境,請在終端機中執行下列指令。
Linux/macOS
mkdir meet-tutorial
cd meet-tutorial
python3 -mvenv env
source env/bin/activate
Windows (命令提示字元)
mkdir meet-tutorial
cd meet-tutorial
python3 -mvenv env
env/bin/activate.bat
Windows (PowerShell)
mkdir meet-tutorial
cd meet-tutorial
python3 -mvenv env
env/bin/activate.ps1
建立 Google Cloud 專案
Google Cloud 控制台
- 在 Google Cloud 控制台中,依序點選「選單」圖示 >「IAM 與管理」>「建立專案」。
-
在「Project Name」欄位中,輸入專案的描述性名稱。
選用:如要編輯專案 ID,請按一下「Edit」。專案建立後即無法變更專案 ID,因此請在專案生命週期內選擇符合您需求的 ID。
- 在「位置」欄位中,按一下「瀏覽」,查看專案的潛在位置。然後按一下「選取」。
- 按一下「建立」,Google Cloud 控制台會前往「資訊主頁」頁面,並在幾分鐘內建立專案。
gcloud CLI
在下列其中一種開發環境中,存取 Google Cloud CLI (「gcloud):
-
Cloud Shell:如要在已設定 gcloud CLI 中使用線上終端機,請啟用 Cloud Shell。
啟用 Cloud Shell -
本機殼層:如要使用本機開發環境,請安裝並initialize gcloud CLI。
如要建立 Cloud 專案,請使用「gcloud projects create」指令:gcloud projects create PROJECT_ID
啟用 Google Cloud 專案的計費功能
Google Cloud 控制台
- 前往 Google Cloud 控制台中的「帳單」。依序點選「選單」圖示 >「帳單」>「我的專案」。
- 在「請選取機構」中,選擇與 Google Cloud 專案相關聯的機構。
- 在專案列中開啟「動作」選單 ( ),按一下「變更帳單」,然後選擇所需的 Cloud Billing 帳戶。
- 按一下 [設定帳戶]。
gcloud CLI
- 如要列出可用的帳單帳戶,請執行:
gcloud billing accounts list
- 將帳單帳戶連結至 Google Cloud 專案:
gcloud billing projects link PROJECT_ID --billing-account=BILLING_ACCOUNT_ID
更改下列內容:
PROJECT_ID
是您要啟用計費功能的 Cloud 專案的專案 ID。BILLING_ACCOUNT_ID
是要與 Google Cloud 專案連結的帳單帳戶 ID。
設定驗證與授權
驗證及授權可讓應用程式存取 Meet REST API 資源。需要使用者授權才能呼叫 Meet REST API。本節說明如何設定使用者憑證和要求授權。
設定 OAuth 同意畫面並選擇範圍
下列步驟會提供預留位置資訊,供您為應用程式設定 OAuth 同意畫面。在外部發布應用程式之前,請更新這項資訊。
- 在 Google Cloud 控制台中,依序點選「選單」圖示 >「API 和服務」>「OAuth 同意畫面」。
- 在「使用者類型」下方,選取「內部」,然後按一下「建立」。
- 在「應用程式名稱」中輸入
Meet REST API Tutorial
。 - 填寫應用程式註冊表單,然後按一下「儲存並繼續」。
- 按一下「新增或移除範圍」。畫面上會出現一個面板,當中列出 Google Cloud 專案中已啟用的各個 API 範圍。
- 在「手動新增範圍」下方,貼上下列範圍:
https://www.googleapis.com/auth/meetings.space.created
- 按一下「Add to Table」。
- 按一下「更新」。
- 選取應用程式所需的範圍後,請按一下「儲存並繼續」。
- 針對使用者類型選取「外部」,請新增測試使用者:
- 在「測試使用者」下方,點選「新增使用者」。
- 輸入您的電子郵件地址和任何其他授權測試使用者,然後按一下「儲存並繼續」。
- 查看您的應用程式註冊摘要。如要變更,請按一下「編輯」。如果應用程式註冊正確無誤,請按一下「Back to Dashboard」(返回資訊主頁)。
建立用戶端 ID
在 OAuth 2.0 流程中,用戶端 ID 就是應用程式的憑證。由於應用程式會在本機執行,因此請建立桌面用戶端 ID。
- 在 Google Cloud 控制台中,依序點選「選單」圖示 >「API 和服務」>「憑證」。
- 依序按一下「建立憑證」>「OAuth 用戶端 ID」。
- 依序按一下「應用程式類型」>「電腦版應用程式」。
- 在「名稱」欄位中,輸入憑證名稱。這個名稱只會顯示在 Google Cloud 控制台中。
- 按一下「建立」,畫面上會顯示 OAuth 用戶端已建立的畫面,顯示您的新用戶端 ID 與用戶端密鑰。
- 按一下「OK」(確定)。新建立的憑證會顯示在「OAuth 2.0 用戶端 ID」下方。
安裝 Google 驗證資料庫
安裝 Google 驗證程式庫:
pip install google-auth google-auth-oauthlib
執行授權
Meet REST API 需要使用者憑證 (格式為 OAuth 2.0 存取憑證)。在本節中,您將實作 OAuth 2.0 流程,為使用者要求存取權杖和更新權杖。
在工作目錄中建立
main.py
檔案,並新增下列內容:import os import json from google.auth.transport import requests from google.oauth2.credentials import Credentials from google_auth_oauthlib.flow import InstalledAppFlow def authorize() -> Credentials: """Ensure valid credentials for calling the Meet REST API.""" CLIENT_SECRET_FILE = "./client_secret.json" credentials = None if os.path.exists('token.json'): credentials = Credentials.from_authorized_user_file('token.json') if credentials is None: flow = InstalledAppFlow.from_client_secrets_file( CLIENT_SECRET_FILE, scopes=[ 'https://www.googleapis.com/auth/meetings.space.created', ]) flow.run_local_server(port=0) credentials = flow.credentials if credentials and credentials.expired: credentials.refresh(requests.Request()) if credentials is not None: with open("token.json", "w") as f: f.write(credentials.to_json()) return credentials USER_CREDENTIALS = authorize()
如要執行程式碼,必須提供用戶端 ID 和先前建立的密鑰。將下載的用戶端密鑰檔案複製到專案工作目錄,並重新命名為
client_secret.json
。如要測試授權的運作方式,請執行下列指令。要求獲準後,應用程式會提示授權,並在專案工作目錄中建立
token.json
檔案。python3 main.py
新增 Meet REST API
現在授權碼已完成,接下來請啟用並呼叫 Meet REST API。
啟用 API
本節將重點放在 Meet REST API,本教學課程也會使用 Google Cloud Pub/Sub 和 Google WorkspaceEvents API。
Google Cloud 控制台
在 Google Cloud 控制台中,啟用 Google Meet REST API、Google WorkspaceEvents API 和 Google Cloud Pub/Sub。
確認您在正確的 Cloud 專案中啟用 API,然後點選「Next」。
確認您啟用的是正確的 API,然後按一下「啟用」。
gcloud CLI
如有需要,請將目前的 Cloud 專案設為您使用
gcloud config set project
指令建立的專案:gcloud config set project PROJECT_ID
將 PROJECT_ID 替換成您建立的 Cloud 專案的專案 ID。
使用
gcloud services enable
指令啟用 Google Meet REST API、Google WorkspaceEvents API 和 Google Cloud Pub/Sub:gcloud services enable meet.googleapis.com workspaceevents.googleapis.com pubsub.googleapis.com
安裝 Meet REST API 用戶端程式庫
如要安裝 Meet REST API 用戶端程式庫,請按照下列步驟操作:
執行下列指令:
pip install google-apps-meet
編輯
main.py
檔案以匯入用戶端:from google.apps import meet_v2 as meet
建立聊天室
現在 Meet REST API 已可使用,請定義函式來建立可訂閱的會議空間。
編輯 main.py
並新增:
def create_space() -> meet.Space:
"""Create a meeting space."""
client = meet.SpacesServiceClient(credentials=USER_CREDENTIALS)
request = meet.CreateSpaceRequest()
return client.create_space(request=request)
訂閱活動
如要接收會議空間的相關事件,請使用 Google Workspace Event API 建立訂閱。您還必須建立並訂閱 Google Cloud Pub/Sub 主題,這個主題會做為應用程式接收事件的通知端點。
設定 Google Cloud Pub/Sub
如何建立及訂閱 Pub/Sub 主題:
Google Cloud 控制台
- 在 Google Cloud 控制台中,依序點選「選單」圖示 >「Pub/Sub」。
確認已選取應用程式的 Cloud 專案。
- 按一下「建立主題」圖示
- 輸入
workspace-events
做為主題名稱。 - 保留選取「新增預設訂閱項目」的選項。
- 按一下「建立」,您的完整主題名稱格式為
projects/{project}/topics/{topic}
。請記下這個名稱,後續步驟會用到。
,然後執行下列操作:
- 輸入
- 授予將 Pub/Sub 訊息發布至主題的權限:
- 在側邊面板中,開啟「權限」分頁。
- 按一下「Add Principal」(新增主體)。
- 在「新增主體」中輸入
meet-api-event-push@system.gserviceaccount.com
。 - 在「指派角色」中,選取
Pub/Sub Publisher
。 - 點按「儲存」。
更新主題的權限可能需要幾分鐘。
gcloud CLI
- 在 Cloud 專案中執行以下指令以建立主題:
gcloud pubsub topics create workspace-events
輸出內容會顯示完整的主題名稱,格式為
projects/{project}/topics/{topic}
。請記下這個名稱,後續步驟會用到。 - 授予將訊息發布至主題的權限:
gcloud pubsub topics add-iam-policy-binding workspace-events --member='serviceAccount:meet-api-event-push@system.gserviceaccount.com' --role='roles/pubsub.publisher'
更新主題的權限可能需要幾分鐘。
- 為主題建立 Pub/Sub 訂閱項目:
gcloud pubsub subscriptions create workspace-events-sub --topic=TOPIC_NAME
更改下列內容:
TOPIC_NAME
:您在前一個步驟建立的主題名稱。
記下主題名稱,並確認 {project}
的值是應用程式的 Cloud 專案 ID。您稍後將使用主題名稱建立 Google Workspace 訂閱項目。
建立服務帳戶
Google Cloud 控制台
- 在 Google Cloud 控制台中,依序點選「選單」圖示 >「IAM 與管理」>「服務帳戶」。
- 按一下「建立服務帳戶」。
- 填寫服務帳戶詳細資料,然後按一下「建立並繼續」。
- 選用:將角色指派給服務帳戶,即可授予 Google Cloud 專案資源的存取權。詳情請參閱「授予、變更及撤銷資源的存取權」。
- 點選「繼續」。
- 選用:輸入可透過這個服務帳戶管理及執行動作的使用者或群組。詳情請參閱「管理服務帳戶模擬功能」。
- 按一下 [完成]。記下服務帳戶的電子郵件地址。
gcloud CLI
- 建立服務帳戶:
gcloud iam service-accounts create meet-event-listener \ --display-name="meet-event-listener"
- 選用:將角色指派給服務帳戶,即可授予 Google Cloud 專案資源的存取權。詳情請參閱「授予、變更及撤銷資源的存取權」。
使用服務帳戶
建立服務帳戶後,將存取權授予自己以模擬該服務帳戶。
Google Cloud 控制台
- 在新建服務帳戶的「動作」欄中,依序按一下 >「管理權限」。
- 依序點選「新增金鑰」>「授予存取權」。
- 在「新增主體」下方輸入電子郵件地址。
- 依序選取「服務帳戶」>「服務帳戶權杖建立者」角色。
- 點按「儲存」。
gcloud CLI
- 如要新增權限,請使用服務帳戶的電子郵件地址執行
gcloud iam service-accounts add-iam-policy-binding
。gcloud iam service-accounts add-iam-policy-binding \ SERVICE_ACCOUNT_EMAIL \ --member="user:YOUR_EMAIL \ --role="roles/iam.serviceAccountTokenCreator"
- 登入
gcloud
,將應用程式預設憑證設為服務帳戶。畫面出現授權提示時,請使用在先前步驟中使用的帳戶登入。gcloud auth application-default login --impersonate-service-account=SERVICE_ACCOUNT_EMAIL
安裝 Pub/Sub 用戶端程式庫
使用
pip
安裝 Pub/Sub 的用戶端程式庫:pip install google-cloud-pubsub
然後編輯
main.py
以匯入用戶端:from google.cloud import pubsub_v1
建立 Google Workspace 訂閱方案
將以下程式碼加入 main.py
,定義訂閱 Meet 事件的方法。這個程式碼會訂閱會議空間的所有活動。訂閱後,事件會發布至 Pub/Sub 主題。
def subscribe_to_space(space_name: str = None, topic_name: str = None):
"""Subscribe to events for a meeting space."""
session = requests.AuthorizedSession(USER_CREDENTIALS)
body = {
'targetResource': f"//meet.googleapis.com/{space_name}",
"eventTypes": [
"google.workspace.meet.conference.v2.started",
"google.workspace.meet.conference.v2.ended",
"google.workspace.meet.participant.v2.joined",
"google.workspace.meet.participant.v2.left",
"google.workspace.meet.recording.v2.fileGenerated",
"google.workspace.meet.transcript.v2.fileGenerated",
],
"payloadOptions": {
"includeResource": False,
},
"notificationEndpoint": {
"pubsubTopic": topic_name
},
"ttl": "86400s",
}
response = session.post("https://workspaceevents.googleapis.com/v1/subscriptions", json=body)
return response
接著,請新增對應的程式碼來提取及處理事件。
監聽及處理事件
繼續編輯 main.py
,並新增以下程式碼範例。這個程式碼會實作接收端,並使用 Google Cloud Pub/Sub API 提取可用的事件。各種處理常式方法都會輸出對應事件的相關資訊。
def format_participant(participant: meet.Participant) -> str:
"""Formats a participant for display on the console."""
if participant.anonymous_user:
return f"{participant.anonymous_user.display_name} (Anonymous)"
if participant.signedin_user:
return f"{participant.signedin_user.display_name} (ID: {participant.signedin_user.user})"
if participant.phone_user:
return f"{participant.phone_user.display_name} (Phone)"
return "Unknown participant"
def fetch_participant_from_session(session_name: str) -> meet.Participant:
"""Fetches the participant for a session."""
client = meet.ConferenceRecordsServiceClient(credentials=USER_CREDENTIALS)
# Use the parent path of the session to fetch the participant details
parsed_session_path = client.parse_participant_session_path(session_name)
participant_resource_name = client.participant_path(
parsed_session_path["conference_record"],
parsed_session_path["participant"])
return client.get_participant(name=participant_resource_name)
def on_conference_started(message: pubsub_v1.subscriber.message.Message):
"""Display information about a conference when started."""
payload = json.loads(message.data)
resource_name = payload.get("conferenceRecord").get("name")
client = meet.ConferenceRecordsServiceClient(credentials=USER_CREDENTIALS)
conference = client.get_conference_record(name=resource_name)
print(f"Conference (ID {conference.name}) started at {conference.start_time.rfc3339()}")
def on_conference_ended(message: pubsub_v1.subscriber.message.Message):
"""Display information about a conference when ended."""
payload = json.loads(message.data)
resource_name = payload.get("conferenceRecord").get("name")
client = meet.ConferenceRecordsServiceClient(credentials=USER_CREDENTIALS)
conference = client.get_conference_record(name=resource_name)
print(f"Conference (ID {conference.name}) ended at {conference.end_time.rfc3339()}")
def on_participant_joined(message: pubsub_v1.subscriber.message.Message):
"""Display information about a participant when they join a meeting."""
payload = json.loads(message.data)
resource_name = payload.get("participantSession").get("name")
client = meet.ConferenceRecordsServiceClient(credentials=USER_CREDENTIALS)
session = client.get_participant_session(name=resource_name)
participant = fetch_participant_from_session(resource_name)
display_name = format_participant(participant)
print(f"{display_name} joined at {session.start_time.rfc3339()}")
def on_participant_left(message: pubsub_v1.subscriber.message.Message):
"""Display information about a participant when they leave a meeting."""
payload = json.loads(message.data)
resource_name = payload.get("participantSession").get("name")
client = meet.ConferenceRecordsServiceClient(credentials=USER_CREDENTIALS)
session = client.get_participant_session(name=resource_name)
participant = fetch_participant_from_session(resource_name)
display_name = format_participant(participant)
print(f"{display_name} left at {session.end_time.rfc3339()}")
def on_recording_ready(message: pubsub_v1.subscriber.message.Message):
"""Display information about a recorded meeting when artifact is ready."""
payload = json.loads(message.data)
resource_name = payload.get("recording").get("name")
client = meet.ConferenceRecordsServiceClient(credentials=USER_CREDENTIALS)
recording = client.get_recording(name=resource_name)
print(f"Recording available at {recording.drive_destination.export_uri}")
def on_transcript_ready(message: pubsub_v1.subscriber.message.Message):
"""Display information about a meeting transcript when artifact is ready."""
payload = json.loads(message.data)
resource_name = payload.get("transcript").get("name")
client = meet.ConferenceRecordsServiceClient(credentials=USER_CREDENTIALS)
transcript = client.get_transcript(name=resource_name)
print(f"Transcript available at {transcript.docs_destination.export_uri}")
def on_message(message: pubsub_v1.subscriber.message.Message) -> None:
"""Handles an incoming event from the Google Cloud Pub/Sub API."""
event_type = message.attributes.get("ce-type")
handler = {
"google.workspace.meet.conference.v2.started": on_conference_started,
"google.workspace.meet.conference.v2.ended": on_conference_ended,
"google.workspace.meet.participant.v2.joined": on_participant_joined,
"google.workspace.meet.participant.v2.left": on_participant_left,
"google.workspace.meet.recording.v2.fileGenerated": on_recording_ready,
"google.workspace.meet.transcript.v2.fileGenerated": on_transcript_ready,
}.get(event_type)
try:
if handler is not None:
handler(message)
message.ack()
except Exception as error:
print("Unable to process event")
print(error)
def listen_for_events(subscription_name: str = None):
"""Subscribe to events on the subscription."""
subscriber = pubsub_v1.SubscriberClient()
with subscriber:
future = subscriber.subscribe(subscription_name, callback=on_message)
print("Listening for events")
try:
future.result()
except KeyboardInterrupt:
future.cancel()
print("Done")
完成程式碼
將下列程式碼新增至 main.py
,以呼叫這些方法,以建立空間、訂閱事件並監聽。使用您自己的主題和訂閱項目名稱更新 TOPIC_NAME
和 SUBSCRIPTION_NAME
常數。
將程式碼新增至
main.py
:space = create_space() print(f"Join the meeting at {space.meeting_uri}") TOPIC_NAME = "projects/PROJECT_ID/topics/TOPIC_ID" SUBSCRIPTION_NAME = "projects/PROJECT_ID/subscriptions/SUBSCRIPTION_ID" subscription = subscribe_to_space(topic_name=TOPIC_NAME, space_name=space.name) listen_for_events(subscription_name=SUBSCRIPTION_NAME)
更改下列內容:
PROJECT_ID
:應用程式的專屬 Cloud 專案 ID,例如my-sample-project-191923
。TOPIC_ID
:您在 Cloud 專案中建立的 Pub/Sub 主題名稱。SUBSCRIPTION_ID
:訂閱項目的名稱,例如workspace-events-sub
。
執行程式:
python3 main.py
如果您之前不曾執行程式,系統會在首次執行時提示授權。授予應用程式呼叫 Meet REST API 的權限。成功執行程式後,您應該會看到類似以下的輸出內容:
Join the meeting at https://meet.google.com/abc-mnop-xyz
加入會議
如要產生應用程式事件,請使用應用程式顯示的網址加入會議。加入後,您可以嘗試以下動作來觸發事件:
- 離開會議再重新加入。
- 你可以邀請其他人,或是使用電話撥入會議。
- 啟用錄音和轉錄稿功能。
每項活動都會產生一個事件,由應用程式接收並記錄至 Google Cloud 控制台。
完成後,請使用 ctrl-c
中斷程式。
選用:可嘗試的其他步驟
應用程式會記錄事件的基本詳細資料。如要繼續探索 Meet REST API,請嘗試修改應用程式來執行這些額外動作。
- 使用 People API 擷取已登入參與者的其他資訊。
- 使用 Google Drive API 下載錄製內容和轉錄稿。
- 與其從 Google 雲端硬碟下載轉錄稿,請使用 Meet REST API 中的結構化轉錄稿方法擷取轉錄稿。
選用:清除
如要避免系統向您的 Google Cloud 控制台帳戶收取本教學課程中所用資源的費用,建議您清除已建立的所有資源和專案。
如要刪除訂閱項目:
控制台
在 Google Cloud 控制台中,依序前往「選單」>「Pub/Sub」>「訂閱項目」
選取訂閱項目,然後按一下
「More actions」(更多動作)。按一下 [Delete] (刪除),畫面上會顯示「刪除訂閱項目」視窗。
按一下「刪除」。
gcloud CLI
刪除訂閱項目:
gcloud pubsub subscriptions delete SUBSCRIPTION_NAME
如要刪除主題:
控制台
在 Google Cloud 控制台中,依序點選「選單」>「Pub/Sub」>「主題」
選取主題,然後按一下
「More actions」(更多動作)。按一下 [Delete] (刪除),畫面上會顯示「Delete topic」(刪除主題) 視窗。
輸入
delete
,然後按一下「Delete」(刪除)。
gcloud CLI
刪除主題:
gcloud pubsub topics delete TOPIC_NAME
如要刪除專案:
控制台
- 在 Google Cloud 控制台中,前往「Manage resources」(管理資源) 頁面。依序點選「Menu」圖示 >「IAM & Admin」>「管理資源」。
- 在專案清單中選取要刪除的專案,然後按一下「Delete」(刪除) 。
- 在對話方塊中輸入專案 ID,然後按一下「Shut down」(關閉) 來刪除專案。
gcloud CLI
如要刪除專案,請使用 gcloud projects delete 指令:
gcloud projects delete PROJECT_ID
相關主題
- 進一步瞭解 Google Meet REST API 的功能,並查看參考說明文件。
- 瞭解如何使用 Google Workspace Event API 訂閱事件。
- 如要進一步瞭解驗證機制,請參閱「設定 OAuth 同意畫面並選擇範圍」。