本頁面由 Cloud Translation API 翻譯而成。

建立、讀取、更新及刪除訊息

您可以透過 Google Chat API 呼叫對應的方法，以非同步方式建立、讀取、更新或刪除訊息。本指南說明如何呼叫下列方法：

使用 spaces.messages.create 建立訊息。
使用 spaces.messages.get 讀取訊息。
使用 spaces.messages.update 更新訊息。
使用 spaces.messages.delete 刪除郵件。

Chat 應用程式可以直接回應 Chat 事件 (例如訊息和加入聊天室)，無需非同步呼叫 Chat API。如要建立可同步回應 Chat 事件的 Chat 應用程式，請參閱建構即時通訊應用程式。Chat 應用程式能夠以非同步且非同步的方式使用 Chat API。

如要在不使用 Chat 應用程式的 Chat 聊天室中以非同步方式建立訊息，請設定 Webhook。

必要條件

如要執行本指南中的範例，您必須符合下列條件：

Python

Python 3.6 以上版本
pip 套件管理工具
適用於 Python 的 Google 用戶端程式庫。如要安裝，請在指令列介面中執行下列指令：
```
pip3 install --upgrade google-api-python-client google-auth-httplib2 google-auth-oauthlib oauth2client
```
已發布的 Chat 應用程式，且成員的 Chat 聊天室中有成員：
- 如要建立及發布即時通訊應用程式，請參閱使用 Cloud Functions 建構 Google Chat 應用程式。
- 如要在 Chat 聊天室中新增 Chat 應用程式，請參閱將應用程式加入 Google Chat 的聊天室或對話。
為 Chat 應用程式設定授權：
- 完整支援服務帳戶。如要設定服務帳戶，請參閱以服務帳戶的身分進行驗證及授權。
- 開發人員預覽版：Google Workspace 開發人員預覽計劃可支援使用者驗證功能，讓使用者搶先體驗特定功能。如要設定使用者驗證，請參閱驗證及授權使用者 (開發人員預覽版)。spaces.messages.update 方法尚不支援使用者驗證。

建立訊息

如要在 Google Chat 中非同步建立訊息，請呼叫 Message 資源上的 create 方法。您可以建立文字或資訊卡訊息。如要開始或回覆討論串，請指定 threadKey 或 thread.name。

請記下您所建立訊息的 name，方便日後閱讀、更新或刪除。或者，您也可以為訊息命名。

建立簡訊

建立 text 訊息的方法如下：

Python

在工作目錄中建立名為 chat_create_text_message.py 的檔案。

在 chat_create_text_message.py 中加入下列程式碼：

from httplib2 import Http
from oauth2client.service_account import ServiceAccountCredentials
from apiclient.discovery import build

# Specify required scopes.
SCOPES = ['https://www.googleapis.com/auth/chat.bot']

# Specify service account details.
CREDENTIALS = ServiceAccountCredentials.from_json_keyfile_name(
    'service_account.json', SCOPES)

# Build the URI and authenticate with the service account.
chat = build('chat', 'v1', http=CREDENTIALS.authorize(Http()))

# Create a Chat message.
result = chat.spaces().messages().create(

    # The space to create the message in.
    #
    # Replace SPACE with a space name.
    # Obtain the space name from the spaces resource of Chat API,
    # or from a space's URL.
    parent='spaces/SPACE',

    # The message to create.
    body={'text': 'Hello, world!'}

).execute()

print(result)

在程式碼中，將 SPACE 替換成聊天室名稱。您可以透過 Chat API 的 spaces.list() 方法或聊天室網址取得該名稱。
在工作目錄中建構並執行範例：
```
python3 chat_create_text_message.py
```

建立卡片訊息

建立 card 訊息的方法如下：

透過 Chat REST API 建立的資訊卡訊息。 — **圖 1**：使用 Chat API 建立的資訊卡訊息。

Python

在工作目錄中建立名為 chat_create_card_message.py 的檔案。

在 chat_create_card_message.py 中加入下列程式碼：

from httplib2 import Http
from oauth2client.service_account import ServiceAccountCredentials
from apiclient.discovery import build

# Specify required scopes.
SCOPES = ['https://www.googleapis.com/auth/chat.bot']

# Specify service account details.
CREDENTIALS = ServiceAccountCredentials.from_json_keyfile_name(
    'service_account.json', SCOPES)

# Build the URI and authenticate with the service account.
chat = build('chat', 'v1', http=CREDENTIALS.authorize(Http()))

# Create a Chat message.
result = chat.spaces().messages().create(

    # The space to create the message in.
    #
    # Replace SPACE with a space name.
    # Obtain the space name from the spaces resource of Chat API,
    # or from a space's URL.
    parent='spaces/SPACE',

    # The message to create.
    body=
    {
      'cardsV2': [{
        'cardId': 'createCardMessage',
        'card': {
          'header': {
            'title': 'A Card Message!',
            'subtitle': 'Created with Chat REST API',
            'imageUrl': 'https://developers.google.com/chat/images/chat-product-icon.png',
            'imageType': 'CIRCLE'
          },
          'sections': [
            {
              'widgets': [
                {
                  'buttonList': {
                    'buttons': [
                      {
                        'text': 'Read the docs!',
                        'onClick': {
                          'openLink': {
                            'url': 'https://developers.google.com/chat'
                          }
                        }
                      }
                    ]
                  }
                }
              ]
            }
          ]
        }
      }]
    }

).execute()

print(result)

在程式碼中，將 SPACE 替換成聊天室名稱。您可以透過 Chat API 的 spaces.list() 方法或聊天室網址取得該名稱。
在工作目錄中建構並執行範例：
```
python3 chat_create_card_message.py
```

發起或回覆郵件串

如要發起對話串，請建立訊息並將 thread.name 留空；Google Chat 會在建立討論串時填入訊息。(選用) 如要自訂執行緒名稱，請指定 thread.threadKey 做為執行緒名稱。

如要回覆郵件串，請將討論串名稱指定為 thread.threadKey 或 thread.name。後續 thread.threadKey 或 thread.name 訊息的回覆會在同一個回覆中張貼至回覆中。

每個 thread.threadKey 都是專屬的 Chat 應用程式或 Webhook，可供設定。如果兩個不同的應用程式或 Webhook 設定了相同的 thread.threadKey，則訊息不會以會話串表示。而是會啟動兩個不同的執行緒。只要指定 thread.name，即可讓同一個應用程式或 Webhook 在相同執行緒中張貼回覆。

以下說明如何使用 thread.threadKey 的「nameOfThread」啟動或回覆討論串：

Python

在工作目錄中建立名為 chat_create_message_thread.py 的檔案。

在 chat_create_message_thread.py 中加入下列程式碼：

from httplib2 import Http
from oauth2client.service_account import ServiceAccountCredentials
from apiclient.discovery import build

# Specify required scopes.
SCOPES = ['https://www.googleapis.com/auth/chat.bot']

# Specify service account details.
CREDENTIALS = ServiceAccountCredentials.from_json_keyfile_name(
    'service_account.json', SCOPES)

# Build the URI and authenticate with the service account.
chat = build('chat', 'v1', http=CREDENTIALS.authorize(Http()))

# Create a Chat message.
result = chat.spaces().messages().create(

    # The space to create the message in.
    #
    # REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD replies to an existing thread
    # if one exists, otherwise it starts a new one.
    #
    # Replace SPACE with a space name.
    # Obtain the space name from the spaces resource of Chat API,
    # or from a space's URL.
    parent='spaces/SPACE',

    # Whether to start a thread or reply to an existing one.
    #
    # Required when threading is enabled in a space unless starting a
    # thread.  Ignored in other space types. Threading is enabled when
    # space.spaceThreadingState is THREADED_MESSAGES.
    messageReplyOption='REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD',

    # The message body.
    body={

        # The message to create.
        'text': 'Start or reply to another message in a thread!',

        # The thread to start or reply to.
        'thread': {
            'threadKey': 'nameOfThread'
        }
    }

).execute()

print(result)

在程式碼中，將 SPACE 替換成聊天室名稱。您可以透過 Chat API 的 spaces.list() 方法或聊天室網址取得該名稱。
在工作目錄中建構並執行範例：
```
python3 chat_create_message_thread.py
```

建立訊息並為其命名

為方便對已建立的訊息執行作業，請為這個訊息指派自訂 name。指派自訂名稱後，Chat 應用程式就能快速記住訊息，無需儲存建立訊息時傳回的回應主體訊息 name。

指派自訂名稱後，Chat 應用程式可記住訊息內容，不會儲存訊息建立時傳回的回應主體訊息 name。

指派自訂名稱不會取代產生的 name 欄位，也就是訊息的資源名稱。而會將自訂名稱設為 clientAssignedMessageId 欄位，如此一來，系統處理後續作業 (例如更新或刪除郵件) 時就能參照該欄位。

在建立訊息時指定使用的自訂名稱會傳回錯誤，但 update 和 delete 等其他方法可正常運作。

自訂名稱規定：

開頭是 client-。例如，client-custom-name 是有效的自訂名稱，但 custom-name 不是。
只能使用小寫英文字母、數字和連字號，
長度不得超過 63 個字元。

建立及命名訊息的方法如下：

Python

在工作目錄中建立名為 chat_create_named_message.py 的檔案。

在 chat_create_named_message.py 中加入下列程式碼：

from httplib2 import Http
from oauth2client.service_account import ServiceAccountCredentials
from apiclient.discovery import build

# Specify required scopes.
SCOPES = ['https://www.googleapis.com/auth/chat.bot']

# Specify service account details.
CREDENTIALS = ServiceAccountCredentials.from_json_keyfile_name(
    'service_account.json', SCOPES)

# Build the URI and authenticate with the service account.
chat = build('chat', 'v1', http=CREDENTIALS.authorize(Http()))

# Create a Chat message with a custom name.
result = chat.spaces().messages().create(

    # The space to create the message in.
    #
    # Replace SPACE with a space name.
    # Obtain the space name from the spaces resource of Chat API,
    # or from a space's URL.
    parent='spaces/SPACE',

    # Custom name for the message used to facilitate later operations.
    messageId='client-custom-name',

    # The message to create.
    body={'text': 'Hello, world!'}

).execute()

print(result)

在程式碼中，將 SPACE 替換成聊天室名稱。您可以透過 Chat API 的 spaces.list() 方法或聊天室網址取得該名稱。
在工作目錄中建構並執行範例：
```
python3 chat_create_named_message.py
```

讀取訊息

如要在 Google Chat 中非同步讀取訊息，請針對 Message 資源呼叫 get 方法，並傳遞要讀取的訊息 name。

如要讀取訊息，請按照下列步驟操作：

Python

在工作目錄中建立名為 chat_read_message.py 的檔案。

在 chat_read_message.py 中加入下列程式碼：

from httplib2 import Http
from oauth2client.service_account import ServiceAccountCredentials
from apiclient.discovery import build

# Specify required scopes.
SCOPES = ['https://www.googleapis.com/auth/chat.bot']

# Specify service account details.
CREDENTIALS = ServiceAccountCredentials.from_json_keyfile_name(
    'service_account.json', SCOPES)

# Build the URI and authenticate with the service account.
chat = build('chat', 'v1', http=CREDENTIALS.authorize(Http()))

# Get a Chat message.
result = chat.spaces().messages().get(

    # The message to read.
    #
    # Replace SPACE with a space name.
    # Obtain the space name from the spaces resource of Chat API,
    # or from a space's URL.
    #
    # Replace MESSAGE with a message name.
    # Obtain the message name from the response body returned
    # after creating a message asynchronously with Chat REST API.
    name='spaces/SPACE/messages/MESSAGE'

  ).execute()

# Print Chat API's response in your command line interface.
print(result)

在程式碼中，將 SPACE 替換成聊天室名稱。您可以透過 Chat API 的 spaces.list() 方法或聊天室網址取得該名稱。
在程式碼中，將 MESSAGE 替換為訊息名稱。您可以透過 Chat API 以非同步方式建立訊息之後，傳回這個回應訊息。此外，您也可以在建立訊息時，為其指派自訂名稱。
在工作目錄中建構並執行範例：
```
python3 chat_read_message.py
```

更新訊息

如要在 Google Chat 中非同步更新現有訊息，請呼叫 Message 資源上的 update 方法，並傳遞要更新訊息的 name，以及指定更新訊息的 updateMask 和 body。

更新簡訊，或在簡訊訊息前加上簡訊

如要更新 text 訊息，請傳遞：

要更新訊息的 name。
updateMask='text'
指定更新訊息的 body。

如果更新後的訊息是「卡片」訊息，文字訊息就會接在資訊卡訊息後方 (持續顯示)。

以下說明如何在簡訊中更新 text 訊息，或是在 card 訊息前面加上簡訊：

Python

在工作目錄中建立名為 chat_update_text_message.py 的檔案。

在 chat_update_text_message.py 中加入下列程式碼：

from httplib2 import Http
from oauth2client.service_account import ServiceAccountCredentials
from apiclient.discovery import build

# Specify required scopes.
SCOPES = ['https://www.googleapis.com/auth/chat.bot']

# Specify service account details.
CREDENTIALS = ServiceAccountCredentials.from_json_keyfile_name(
  'service_account.json', SCOPES)

# Build the URI and authenticate with the service account.
chat = build('chat', 'v1', http=CREDENTIALS.authorize(Http()))

# Update a Chat message.
result = chat.spaces().messages().update(

  # The message to update, and the updated message.
  #
  # Replace SPACE with a space name.
  # Obtain the space name from the spaces resource of Chat API,
  # or from a space's URL.
  #
  # Replace MESSAGE with a message name.
  # Obtain the message name from the response body returned
  # after creating a message asynchronously with Chat REST API.
  name='spaces/SPACE/messages/MESSAGE',
  updateMask='text',
  body={'text': 'Updated message!'}

).execute()

# Print Chat API's response in your command line interface.
print(result)

在程式碼中，將 SPACE 替換成聊天室名稱。您可以透過 Chat API 的 spaces.list() 方法或聊天室網址取得該名稱。
在程式碼中，將 MESSAGE 替換為訊息名稱。您可以透過 Chat API 以非同步方式建立訊息之後，傳回這個回應訊息。此外，您也可以在建立訊息時，為其指派自訂名稱。
在工作目錄中建構並執行範例：
```
python3 chat_update_text_message.py
```

更新卡片訊息，或將卡片訊息附加到簡訊中

如要更新 card 訊息，請傳遞：

要更新訊息的 name
updateMask='cardsV2'
指定更新訊息的 body。

如果更新後的訊息是 text 訊息，則資訊卡會附加在簡訊中 (持續顯示)。如果更新後的訊息本身是「卡片」，顯示的資訊卡就會更新。

以下說明如何將訊息更新至 card 訊息：

Python

在工作目錄中建立名為 chat_update_card_message.py 的檔案。

在 chat_update_card_message.py 中加入下列程式碼：

from httplib2 import Http
from oauth2client.service_account import ServiceAccountCredentials
from apiclient.discovery import build

# Specify required scopes.
SCOPES = ['https://www.googleapis.com/auth/chat.bot']

# Specify service account details.
CREDENTIALS = ServiceAccountCredentials.from_json_keyfile_name(
  'service_account.json', SCOPES)

# Build the URI and authenticate with the service account.
chat = build('chat', 'v1', http=CREDENTIALS.authorize(Http()))

# Update a Chat message.
result = chat.spaces().messages().update(

  # The message to update, and the updated message.
  #
  # Replace SPACE with a space name.
  # Obtain the space name from the spaces resource of Chat API,
  # or from a space's URL.
  #
  # Replace MESSAGE with a message name.
  # Obtain the message name from the response body returned
  # after creating a message asynchronously with Chat REST API.
  name='spaces/SPACE/messages/MESSAGE',
  updateMask='cardsV2',
  body=
  {
    'cardsV2': [{
      'cardId': 'updateCardMessage',
      'card': {
        'header': {
          'title': 'An Updated Card Message!',
          'subtitle': 'Updated with Chat REST API',
          'imageUrl': 'https://developers.google.com/chat/images/chat-product-icon.png',
          'imageType': 'CIRCLE'
        },
        'sections': [
          {
            'widgets': [
              {
                'buttonList': {
                  'buttons': [
                    {
                      'text': 'Read the docs!',
                      'onClick': {
                        'openLink': {
                          'url': 'https://developers.google.com/chat'
                        }
                      }
                    }
                  ]
                }
              }
            ]
          }
        ]
      }
    }]
  }

).execute()

# Print Chat API's response in your command line interface.
print(result)

在程式碼中，將 SPACE 替換成聊天室名稱。您可以透過 Chat API 的 spaces.list() 方法或聊天室網址取得該名稱。
在程式碼中，將 MESSAGE 替換為訊息名稱。您可以透過 Chat API 以非同步方式建立訊息之後，傳回這個回應訊息。此外，您也可以在建立訊息時，為其指派自訂名稱。
在工作目錄中建構並執行範例：
```
python3 chat_update_card_message.py
```

刪除留言

如要以非同步方式刪除 Google Chat 中現有的訊息，請對 Message 資源呼叫 delete 方法，並傳遞訊息的 name。

刪除訊息的方法如下：

Python

在工作目錄中建立名為 chat_delete_message.py 的檔案。

在 chat_delete_message.py 中加入下列程式碼：

from httplib2 import Http
from oauth2client.service_account import ServiceAccountCredentials
from apiclient.discovery import build

# Specify required scopes.
SCOPES = ['https://www.googleapis.com/auth/chat.bot']

# Specify service account details.
CREDENTIALS = ServiceAccountCredentials.from_json_keyfile_name(
  'service_account.json', SCOPES)

# Build the URI and authenticate with the service account.
chat = build('chat', 'v1', http=CREDENTIALS.authorize(Http()))

# Delete a Chat message.
result = chat.spaces().messages().delete(

  # The message to delete.
  #
  # Replace SPACE with a space name.
  # Obtain the space name from the spaces resource of Chat API,
  # or from a space's URL.
  #
  # Replace MESSAGE with a message name.
  # Obtain the message name from the response body returned
  # after creating a message asynchronously with Chat REST API.
  name='spaces/SPACE/messages/MESSAGE'

).execute()

# Print Chat API's response in your command line interface.
# When deleting a message, the response body is empty.
print(result)

在程式碼中，將 SPACE 替換成聊天室名稱。您可以透過 Chat API 的 spaces.list() 方法或聊天室網址取得該名稱。
在程式碼中，將 MESSAGE 替換為訊息名稱。您可以透過 Chat API 以非同步方式建立訊息之後，傳回這個回應訊息。此外，您也可以在建立訊息時，為其指派自訂名稱。
在工作目錄中建構並執行範例：
```
python3 chat_delete_message.py
```

限制和注意事項

如要在 Google Chat 中取得訊息的 name，唯一的方法是從建立訊息時傳回的回應主體。請務必記下您建立的訊息的name，以便日後需要讀取、更新或刪除。或者，您也可以為訊息命名。
使用服務帳戶以應用程式身分進行驗證時，Chat 應用程式只能讀取、更新及刪除自己的訊息。
開發人員預覽版：應用程式透過使用者驗證執行動作時，Google Chat 可能會顯示歸因訊息，告知使用者授權代表執行動作的應用程式名稱。