將資料匯入 Google Chat

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

以下概略說明完整的匯入程序：

1. 規劃匯入作業
2. 設定 Chat 應用程式的授權
3. 在匯入模式中建立聊天室
4. 匯入資源
5. 驗證匯入的資源
6. 根據來源資料比對匯入的資源差異
7. 完整匯入模式
8. 在匯入模式後授予聊天室存取權
9. 疑難排解

必要條件

規劃匯入作業

請根據要匯入的資料量進行規劃，瞭解使用限制和配額如何影響匯入程序，並瞭解匯入新聊天室時支援的聊天室類型。

查看 API 用量限制

匯入資料至 Chat 所需的時間會因要匯入的 Chat 資源數量而有很大差異。查看 Chat 應用程式的用量限制，以及從來源訊息傳遞平台匯入的資料量，據此擬定預估時間軸。

將訊息匯入聊天室時，建議您將呼叫分散到不同訊息串的 messages.create() 方法。

找出要匯入的受支援聊天室

匯入模式僅支援 SPACE 和 GROUP_CHAT 的 SpaceType。不支援 DIRECT_MESSAGE。詳情請參閱 SpaceType 說明文件。

在匯入模式中建立聊天室

如要在匯入模式中建立空格，請在 Space 資源上呼叫 create 方法，並將 importMode 設為 true。

在匯入模式中建立聊天室時，請注意下列事項。

• 日期和時間：請記得，匯入模式必須在 30 天內完成。如果聊天室在 spaces.create() 方法呼叫後的 30 天後仍處於匯入模式，系統會自動將其刪除，且無法存取或復原。
  • 請勿使用 createTime 欄位的值，追蹤 30 天的期限。這與您的呼叫 spaces.create() 方法不一定相同。使用匯入模式時，createTime 欄位可設為來源中建立空間的歷史時間戳記，以便保留原始建立時間。
• 聊天室資源名稱 (name)：用於擷取特定聊天室相關資訊的專屬 ID，在將內容匯入聊天室時，會在後續步驟中參照此 ID。

如要保留來源訊息平台中相同聊天室實體的建立時間，您可以設定聊天室的 createTime。這個 createTime 必須設為介於 2000 年 1 月 1 日至目前時間之間的值。

如要在匯入模式中建立外部空間，請將 externalUserAllowed 設為 true。匯入完成後，您就可以新增外部使用者。

以下範例說明如何在匯入模式中建立空間：

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

"""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': 'DISPLAY_NAME',
            'importMode': True,
            'createTime': f'{datetime.datetime(2000, 1, 1).isoformat()}Z',
        }
    )
    .execute()
)

print(result)

更改下列內容：

• EMAIL：您要以網域層級權限冒用身分的使用者帳戶電子郵件地址。
• DISPLAY_NAME：在匯入模式中建立的聊天室名稱。此名稱必須是顯示給 Chat 使用者的專屬名稱。建議您使用與匯入資料時相同的顯示名稱。

匯入資源

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

訊息

Chat 應用程式可以使用自身權限匯入訊息，也可以透過冒用身分代表使用者匯入訊息。郵件作者會設為冒用者使用者帳戶。詳情請參閱「授權 Chat 擴充應用程式」。如要在匯入模式空間中匯入訊息，請在 Message 資源上呼叫 create 方法。如要保留來源訊息平台的原始訊息建立時間，可以設定訊息的 createTime。這個 createTime 必須設為先前設定的空間建立時間和目前時間之間的值。

同一個聊天室中的訊息不得包含相同的 createTime，即使先前已刪除含有該時間的先前訊息也一樣。

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

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

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

"""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)

更改下列內容：

• EMAIL：您透過全網域授權模擬的使用者帳戶電子郵件地址。
• SPACE_NAME：在匯入模式中建立的聊天室名稱。

回應

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

附件

Chat 應用程式可以使用 Chat API 上傳附件。如要瞭解匯入模式聊天室支援的資源方法和驗證類型，請參閱「授權 Chat 應用程式」。不過，我們強烈建議您使用 Google 雲端硬碟 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 欄位表示為新增或移除。

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

"""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)

更改下列內容：

• EMAIL：您要使用全網域權限冒用身分的使用者帳戶電子郵件地址。
• SPACE_NAME：在匯入模式中建立的空間名稱。
• USER_ID：使用者的專屬 ID。

匯入外部聊天室中的資源

您只能使用 Workspace 機構內使用者的憑證，透過匯入模式建立外部聊天室。這項功能僅適用於聊天室處於匯入模式時。聊天室完成匯入模式後，即可邀請外部使用者加入匯入的聊天室 (請參閱存取權部分)，並使用他們的憑證呼叫 Chat API。

驗證匯入的資源

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

您的 Chat 應用程式也可以在 Message 資源上呼叫 get 方法，讀取個別訊息以進行驗證。聊天應用程式只能使用自己的權限呼叫這個方法，讀取自己的訊息。詳情請參閱「授權 Chat 擴充應用程式」。

即時通訊應用程式也可以在 Membership 資源上呼叫 list 方法，列出過去的會籍。聊天室退出匯入模式後，list 方法就不會再公開歷來會員資格。Chat 應用程式只能透過冒用身分，代表使用者呼叫這個方法。詳情請參閱「授權即時通訊應用程式」。

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

根據來源資料協調匯入的資源差異

如果匯入的資源因原始實體在匯入期間發生變更，而不再符合來源訊息平台的原始實體，聊天應用程式可以呼叫 Chat API 來修改匯入的聊天資源。舉例來說，如果使用者在 Chat 中建立訊息後，在來源訊息平台中編輯該訊息，Chat 應用程式就能更新匯入的訊息，以反映原始訊息的目前內容。

訊息

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

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

回應

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

附件

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

過去的會員資格

如要在匯入模式空間中刪除歷史會員資格，請在 Membership 資源上使用 delete 方法。當空間離開匯入模式後，delete 方法就無法再讓您刪除歷來會員資格。

您無法在匯入模式空間中更新歷史會員資格。如要修正匯入錯誤的歷史會員資料，請先刪除該資料，然後在聊天室仍處於匯入模式時重新建立。

Spaces

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

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

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

完整匯入模式

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

請記下呼叫 completeImport 的日期和時間、發出呼叫的使用者資源名稱，以及傳回的回應。如果您遇到任何問題，且必須調查問題，這項功能就很實用。

如要完成匯入模式，並讓使用者存取聊天室，Chat 應用程式可以在 Space 資源上呼叫 completeImport 方法。即時通訊應用程式只能透過冒用身分，代表使用者呼叫這個方法。詳情請參閱「授權 Chat 擴充應用程式」。這個方法完成後，系統會將冒用身分的使用者新增至聊天室，並將其設為聊天室管理員。這個方法必須在初始 create.space 方法呼叫後的 30 天內呼叫。如果在 30 天期限過後嘗試呼叫這個方法，由於匯入模式空間已遭刪除，Chat 應用程式無法再存取該空間，因此呼叫會失敗。

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

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

"""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)

更改下列內容：

• EMAIL：您要使用全網域權限冒用身分的使用者帳戶電子郵件地址。
• SPACE_NAME：在匯入模式中建立的空間名稱。

在匯入模式後授予聊天室存取權

如要讓 Chat 使用者存取最近匯入的聊天室，在初始 create.space() 方法呼叫後的 30 天內，Chat 應用程式可以繼續使用 chat.import 範圍和使用者模擬功能執行下列操作：

• 在聊天室中新增成員：請在 Membership 資源上呼叫 create() 方法。建議 Chat 應用程式在聊天室匯入作業完成後立即建立 Membership 資源，讓 Chat 應用程式可以繼續使用 chat.import 範圍，並確保所有匯入的會員都能存取聊天室。
• 設定目標對象：在 Space 資源上呼叫 update() 方法。如要瞭解如何建立及新增目標對象，請參閱「讓 Google Chat 聊天室可供 Google Workspace 機構中的特定使用者探索」。

如要使用這些方法搭配 chat.import 範圍，被冒用身分的使用者必須是聊天室管理員。

如果是外部聊天室，也可以透過成員 create() 方法邀請 Workspace 機構以外的使用者。請務必瞭解外部使用者的所有已知限制。

疑難排解

如果在匯入 Chat 聊天室時遇到問題，請參閱以下問題尋求協助。如果您收到錯誤回應，請記下該回應 (將文字複製/貼到文件中或儲存螢幕截圖)，以便日後參考和疑難排解。

當空間成功匯入時，CompleteImportSpace 會以 OK 的狀態完成。

未在 30 天期限內完成匯入作業

如先前在「在匯入模式中建立聊天室」一文所述，如果聊天室在呼叫建立方法後 30 天仍處於匯入模式，系統會自動將其刪除，且無法存取或復原。

很抱歉，刪除的空間已無法再使用或無法復原，您必須再次啟動匯入程序。

尋找遺漏的聊天室

如果找不到新的 Chat 聊天室，請查看下表中 CompleteImportSpace 回覆的內容，瞭解原因和解決方法。