將資料匯入 Google Chat

只要使用 Google Chat API，您就能將資料從其他訊息平台匯入 Google Chat。您可以從其他訊息平台，將現有訊息、附件、回應、成員資格和聊天室實體匯入至對應的 Chat API 資源。如要匯入這些資料，您可以在匯入模式中建立 Chat 聊天室，然後將資料匯入這些聊天室。程序順利完成後，這些聊天室就會成為標準的 Chat 聊天室。

  1. 查看 API 用量限制並預先規劃。
  2. 為 Chat 應用程式設定授權。
  3. 在匯入模式中建立聊天室。
  4. 匯入資源。
  5. 驗證匯入的資源。
  6. 協調匯入資源與來源資料的差異。
  7. 完成匯入模式。
  8. 建立成員資格資源。

先備知識

Apps Script

Python

  • Python 3.6 以上版本
  • pip 套件管理工具

  • 最新的 Python 專用 Google 用戶端程式庫。如要安裝或更新這些指令，請在指令列介面中執行下列指令：

    pip3 install --upgrade google-api-python-client google-auth

  • 已發布的 Chat 應用程式。如要建立及發布 Chat 應用程式，請參閱「建構 Google Chat 應用程式」。

  • 為 Chat 應用程式設定授權。Chat 應用程式必須在應用程式匯入內容的任何網域中委派全網域授權，請參閱「授權 Chat 應用程式」。

查看 API 用量限制並預先規劃

將資料匯入 Chat 所需的時間，取決於匯入的 Chat 資源數量。請查看 Chat 應用程式的用量限制，以及從來源訊息傳遞平台匯入的資料量，來確定預估時間軸。

在匯入模式中建立聊天室

如要在匯入模式下建立聊天室，請呼叫 Space 資源上的 create 方法，並將 importMode 設為 true。如要保留來源訊息平台中同等聊天室實體的建立時間，可以設定聊天室的 createTime。此 createTime 必須設為介於 2000 年 1 月 1 日到現在時間之間的值。

請記下您建立的聊天室的 name，以便在後續步驟中將內容匯入空間時參照。

呼叫 create 方法後，Chat 擴充應用程式必須在 30 天內將資源匯入聊天室、完成匯入模式，以及使用 chat.import 範圍建立成員資格資源。使用標準 Chat API 成員資格範圍的 30 天後，即時通訊應用程式仍可建立成員資格。30 天後，如果聊天室仍處於匯入模式，就會自動刪除，屆時將無法存取且無法復原。建議您預先規劃 Chat 應用程式的用量限制，確保可在上述時間範圍內將所有排程資源匯入 Chat。

以下範例說明如何在匯入模式中建立聊天室：

Apps Script

function createSpaceInImportMode() {
  const space = Chat.Spaces.create({
      spaceType: 'SPACE',
      displayName: 'Import Mode Space',
      importMode: true,
      createTime: (new Date('January 1, 2000')).toJSON()
  });
  console.log(space.name);
}

Python

"""Create a space in import mode."""

import datetime

from google.oauth2 import service_account
from googleapiclient.discovery import build

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

CREDENTIALS = (
    service_account.Credentials.from_service_account_file('credentials.json')
    .with_scopes(SCOPES)
    .with_subject('EMAIL')
)

# Build a service endpoint for Chat API.
service = build('chat', 'v1', credentials=CREDENTIALS)

result = (
    service.spaces()
    .create(
        body={
            'spaceType': 'SPACE',
            'displayName': 'Import Mode Space',
            'importMode': True,
            'createTime': f'{datetime.datetime(2000, 1, 1).isoformat()}Z',
        }
    )
    .execute()
)

print(result)

更改下列內容：

  • EMAIL：您向全網域授權模擬的使用者帳戶電子郵件地址。

匯入資源

如要從其他訊息平台匯入資源，請在匯入模式聊天室中建立 Google Chat 資源 (例如訊息、回應、附件)。在聊天室中建立資源時，您需要從遷移的來源訊息平台指定相關資源的資料。

訊息

您的即時通訊應用程式可以使用自己的授權，或透過模擬使用者代表使用者匯入訊息。(訊息作者設為模擬的使用者帳戶)。詳情請參閱「授權即時通訊應用程式」。如要在匯入模式空間中匯入訊息，請在 Message 資源上呼叫 create 方法。如要保留來源訊息平台的原始訊息建立時間，可以設定訊息的 createTime。這個 createTime 必須設為您之前設定與現在之間的空格建立時間之間的值。

即使已刪除包含該時間的舊訊息，同一聊天室中的訊息也無法包含相同的 createTime。

在匯入模式的聊天室中含有第三方網址的訊息，無法在 Google Chat 中顯示連結預覽畫面，

在匯入模式下建立訊息時，聊天室不會通知或傳送電子郵件給任何使用者，包括含有使用者提及的訊息。

以下範例說明如何在匯入模式聊天室中建立訊息：

Python

"""Create a message in import mode space."""

import datetime

from google.oauth2 import service_account
from googleapiclient.discovery import build

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

CREDENTIALS = (
    service_account.Credentials.from_service_account_file('credentials.json')
    .with_scopes(SCOPES)
    .with_subject('EMAIL')
)

# Build a service endpoint for Chat API.
service = build('chat', 'v1', credentials=CREDENTIALS)

NAME = 'spaces/SPACE_NAME'
result = (
    service.spaces()
    .messages()
    .create(
        parent=NAME,
        body={
            'text': 'Hello, world!',
            'createTime': f'{datetime.datetime(2000, 1, 2).isoformat()}Z',
        },
    )
    .execute()
)

print(result)

更改下列內容：

回應

Chat 應用程式可以使用 Chat API 匯入訊息回應。如要瞭解匯入模式聊天室中的資源方法和驗證支援類型，請參閱「授權 Chat 擴充應用程式」。

附件

您的 Chat 應用程式可以使用 Chat API 上傳附件。如要瞭解匯入模式聊天室中的資源方法和驗證支援類型，請參閱「授權 Chat 擴充應用程式」。不過，我們強烈建議您使用 Google Drive API 以 Google 雲端硬碟檔案上傳附件，並將檔案 URI 連結至匯入模式聊天室中相關訊息，以便從其他訊息平台匯入附件，以免達到 Google Chat 內部限制上傳的附件限制。

過往會籍

過往成員資格是為已在來源訊息傳遞平台中離開原始聊天室實體，但想在 Chat 中保留其資料的使用者，所建立會員身分。如要進一步瞭解如何在聊天室不再處於匯入模式後新增成員，請參閱「建立成員資源」。

在許多情況下，當這些過往成員須遵守 Google 的資料保留政策時，您可能會想先將過往成員建立的資料 (例如訊息和回應) 保留在聊天室中，再將其匯入 Chat。當聊天室處於匯入模式時，您可以使用 Membership 資源上的 create 方法，將這些歷來成員資格匯入聊天室。為了保留過往成員資格的離開時間，您必須設定成員資格的 deleteTime。這個離開時間必須準確，因為這會影響要為會員保留哪些資料。此外，這個 deleteTime 必須晚於聊天室建立時間戳記，而且不能是未來的時間戳記。

除了 deleteTime 以外，您也可以設定 createTime，以保留原有成員資格的原始彙整時間。與 deleteTime 不同，createTime 為選用項目。如未設定，createTime 會自動從 deleteTime 減去 1 微秒來計算。如要設定，createTime 必須早於 deleteTime，且不得晚於聊天室建立時間。這些 createTime 資訊不會用於決定資料保留情況，也不會在 Google 管理控制台和 Google 保管箱等管理工具中顯示。

雖然使用者可以在來源訊息傳遞平台中透過多種方式加入及離開聊天室 (透過邀請、自行加入，或由其他使用者加入)，但在 Chat 中，這些動作全都會以過去的成員資格 createTime 和 deleteTime 欄位表示為新增或移除。

以下範例說明如何在匯入模式空間中建立過往成員資格：

Python

"""Create a historical membership in import mode space."""

import datetime

from google.oauth2 import service_account
from googleapiclient.discovery import build

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

CREDENTIALS = (
    service_account.Credentials.from_service_account_file('credentials.json')
    .with_scopes(SCOPES)
    .with_subject('EMAIL')
)

# Build a service endpoint for Chat API.
service = build('chat', 'v1', credentials=CREDENTIALS)

NAME = 'spaces/SPACE_NAME'
USER = 'users/USER_ID'
result = (
    service.spaces()
    .members()
    .create(
        parent=NAME,
        body={
            'createTime': f'{datetime.datetime(2000, 1, 3).isoformat()}Z',
            'deleteTime': f'{datetime.datetime(2000, 1, 4).isoformat()}Z',
            'member': {'name': USER, 'type': 'HUMAN'},
        },
    )
    .execute()
)

print(result)

更改下列內容：

驗證匯入的資源

您的 Chat 應用程式可以呼叫 Message 資源上的 list 方法 ，以讀取並驗證匯入模式空間的內容。您可以從任何傳回訊息的 emojiReactionSummaries 和 attachment 欄位讀取 Reaction 和 Attachment 資源。即時通訊應用程式只能透過模擬功能代表使用者呼叫這個方法。詳情請參閱「授權即時通訊應用程式」。

您的 Chat 應用程式也可以呼叫 Message 資源上的 get 方法，讀取個別訊息以供驗證。即時通訊應用程式只能透過自己的授權呼叫此方法來讀取自己的訊息。詳情請參閱「授權即時通訊應用程式」。

即時通訊應用程式也可以呼叫 Membership 資源上的 list 方法，列出過往成員資格。聊天室結束匯入模式後，list 方法不會再顯示歷來成員資格。即時通訊應用程式只能透過模擬來代表使用者呼叫這個方法。詳情請參閱「授權即時通訊應用程式」。

對 Space 資源呼叫 get 方法，即可讀取匯入模式空間的屬性。即時通訊應用程式只能使用自己的授權呼叫此方法。詳情請參閱「授權即時通訊應用程式」。

核對匯入的資源與來源資料的差異

如果在匯入期間因原始實體變更而有任何匯入的資源與來源訊息平台中的原始實體不符，Chat 應用程式可以呼叫 Chat API 來修改匯入的即時通訊資源。例如，在 Chat 中建立訊息後，如果使用者在來源訊息平台中編輯訊息，Chat 應用程式可以更新匯入的訊息，使其反映原始訊息的目前內容。

訊息

如要在匯入模式空間中更新訊息的支援欄位，請在 Message 資源上呼叫 update 方法。即時通訊應用程式必須使用初始訊息建立期間所用的授權，才能呼叫這個方法。如果您在初始訊息建立期間使用了使用者模擬功能，則必須透過同一個模擬使用者更新該訊息。

如要在匯入模式空間中刪除訊息，請呼叫 Message 資源上的 delete 方法。匯入模式空間中的訊息不需要由原始訊息建立者刪除，且可模擬網域中任何使用者刪除。即時通訊應用程式只能根據自己的授權刪除自己的訊息。詳情請參閱「授權即時通訊應用程式」。

回應

如要在匯入模式空間中刪除訊息的回應，請使用 reactions 資源上的 delete 方法。如要瞭解匯入模式聊天室中的資源方法和驗證支援類型，請參閱「授權 Chat 擴充應用程式」。

附件

如要在匯入模式空間中更新訊息的附件，請在 media 資源上使用 upload 方法。如要瞭解匯入模式聊天室中的資源方法和驗證支援類型，請參閱「授權 Chat 擴充應用程式」。

過往會籍

如要在匯入模式空間中刪除過往成員資格，請使用 Membership 資源的 delete 方法。聊天室結束匯入模式後，delete 方法就不會再讓您刪除過往成員資格。

您無法在匯入模式聊天室中更新過往成員資格。如要修正未正確匯入的過往成員資格，您必須先刪除該成員，然後在空間仍處於匯入模式時重新建立。

聊天室

如要在匯入模式空間中更新支援的欄位，請使用 spaces 資源上的 patch 方法。

如要刪除匯入模式空間，請在 spaces 資源上使用 delete 方法。

如要瞭解匯入模式聊天室中的資源方法和驗證支援類型，請參閱「授權 Chat 擴充應用程式」。

完成匯入模式

呼叫 completeImport 方法之前，您應確保驗證和資源差異的協調作業已完成。從匯入模式退出聊天室是無法復原的程序，而且會將匯入模式空間轉換為一般空間。Chat 中沒有會將這些聊天室歸因於資料匯入的指標。

如要完成匯入模式，並讓使用者存取聊天室，Chat 應用程式可以在 Space 資源上呼叫 completeImport 方法。即時通訊應用程式只能透過模擬功能代表使用者呼叫這個方法。詳情請參閱「授權即時通訊應用程式」。此方法完成後，模擬的使用者就會以聊天室管理員的形式新增至聊天室。您必須在初始 create.space 方法呼叫後的 30 天內呼叫此方法。如果您在 30 天的期間過後嘗試呼叫此方法，由於匯入模式空間會遭到刪除，且無法再存取 Chat 應用程式，因此呼叫會導致失敗。

completeImport 方法中模擬的使用者不一定要是聊天室建立者。

以下範例說明如何完成匯入模式：

Python

"""Complete import."""

from google.oauth2 import service_account
from googleapiclient.discovery import build

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

CREDENTIALS = (
    service_account.Credentials.from_service_account_file('credentials.json')
    .with_scopes(SCOPES)
    .with_subject('EMAIL')
)

# Build a service endpoint for Chat API.
service = build('chat', 'v1', credentials=CREDENTIALS)

NAME = 'spaces/SPACE_NAME'
result = service.spaces().completeImport(name=NAME).execute()

print(result)

更改下列內容：

建立成員資源

如要為已完成匯入模式的聊天室新增使用者成員資格，請在 Membership 資源上呼叫 create 方法。在初始 create.space 方法呼叫後的 30 天內，即時通訊應用程式可繼續使用 chat.import 範圍和使用者模擬功能呼叫這個方法。模擬的使用者必須是聊天室管理員。

30 天過後，即時通訊應用程式需要額外的成員資格範圍才能呼叫這個方法。

我們建議即時通訊應用程式在匯入完成後立即建立成員資源，以便 Chat 擴充應用程式可繼續使用 chat.import 範圍建立成員資格，並為所有成員提供匯入的聊天室存取權。