將資料匯入 Google Chat

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

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

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

必要條件

規劃匯入作業

請據此規劃要匯入的資料量，瞭解用量限制和配額如何影響匯入程序，並留意匯入新空間時支援的 Chat 空間類型。如果您是管理員，請參閱「將訊息資料從其他服務匯入 Google Chat」一文，並仔細按照步驟操作。

查看 API 用量限制

將資料匯入 Chat 所需的時間差異很大，視要匯入的 Chat 資源數量而定。請查看 Chat 應用程式的使用限制，以及預計從來源即時通訊平台匯入的資料量，以估算時間表。

將訊息匯入空間時，建議您將對 messages.create() 方法的呼叫分散到不同的訊息討論串。

找出要匯入的支援空間

匯入模式支援 SpaceType 為 SPACE 和 GROUP_CHAT 的聊天室，但不支援 DIRECT_MESSAGE。

如要匯入兩位使用者之間的對話，或是使用者與 Chat 應用程式之間的對話，請將對話匯入只有兩位成員的聊天室，並使用 SpaceType SPACE 或 GROUP_CHAT。

在匯入模式中建立聊天室

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

以匯入模式建立空間時，請注意下列事項。

• 日期和時間 - 請注意，匯入模式必須在 90 天內完成。如果聊天室在呼叫 spaces.create() 方法後的 90 天內仍處於匯入模式，系統會自動將其刪除，且無法存取或復原。
  • 使用 importModeExpireTime 欄位的值，追蹤 90 天期限的到期日。
  • 請勿使用 createTime 欄位的值追蹤 90 天期限的到期日。這不一定與呼叫 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：在匯入模式中建立的空間名稱。這是顯示給 Google Chat 使用者的空間專屬名稱，建議使用與匯入資料的空間相同的顯示名稱。

匯入資源

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

訊息

Chat 應用程式可使用自己的授權匯入訊息，或透過模擬使用者身分代表使用者匯入訊息。訊息作者會設為遭冒用的使用者帳戶。詳情請參閱「授權 Chat 應用程式」。如要在匯入模式空間中匯入訊息，請在 Message 資源上呼叫 create 方法。如要保留來源訊息平台中原始訊息的建立時間，可以設定訊息的 createTime。這個 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，且必須在空間建立時間之後。這項資訊不會用於判斷資料保留時間，也不會顯示在 Google 管理控制台和 Google 保管箱等管理工具中。createTime

使用者在來源訊息平台中加入及離開聊天室的方式可能有很多種 (透過邀請、自行加入、由其他使用者新增)，但在 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 方法 ，讀取並驗證匯入模式聊天室的內容。您可以從任何傳回訊息的 Reaction 和 Attachment 欄位讀取 emojiReactionSummaries 和 attachment 資源。Chat 應用程式只能透過模擬身分，代表使用者呼叫這個方法。詳情請參閱「授權 Chat 應用程式」。

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

即時通訊應用程式也可以呼叫 Membership 資源上的 list 方法，列出過往的成員。聊天室退出匯入模式後，list 方法就不會再公開成員的歷史記錄。Chat 擴充應用程式只能透過模擬，代表使用者呼叫這個方法。詳情請參閱「授權 Chat 應用程式」。

如要讀取匯入模式空間的屬性，請在 Space 資源上呼叫 get 方法。回應也會填入 importModeExpireTime，方便您追蹤完成匯入程序的時間範圍。即時通訊應用程式只能使用自己的授權呼叫這個方法。 詳情請參閱「授權 Chat 應用程式」。

根據來源資料，比對匯入資源的差異

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

訊息

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

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

回應

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

附件

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

過往會員資格

如要刪除匯入模式空間中的過往成員，請在 Membership 資源上使用 delete 方法。如果空間退出匯入模式，delete 方法就不再允許您刪除歷來成員資格。

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

Spaces

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

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

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

完整匯入模式

呼叫 completeImport 方法前，請務必完成驗證和資源差異的對帳。退出匯入模式聊天室後，該聊天室會轉換為一般聊天室，且無法復原。Chat 中不會顯示任何指標，指出這些聊天室是資料匯入所致。

請記下您呼叫 completeImport 的日期和時間、發出呼叫的使用者資源名稱，以及傳回的回應。如果遇到任何問題並需要調查，這項功能會很有幫助。

如要完成匯入模式，並讓使用者存取聊天室，Chat 應用程式可以呼叫 Space 資源的 completeImport 方法。 Chat 擴充應用程式只能透過模擬，代表使用者呼叫這個方法。詳情請參閱「授權 Chat 應用程式」。這個方法完成後，系統會將模擬使用者新增至聊天室，並指派聊天室管理員身分。您必須在首次呼叫 create.space 方法後的 90 天內呼叫這個方法。如果嘗試在 90 天期限過後呼叫這個方法，呼叫會失敗，因為匯入模式的聊天室已遭刪除，Chat 應用程式無法再存取。

completeImport 方法中模擬的使用者不一定要是空間建立者。

請勿在 importModeExpireTime 附近呼叫 completeImport，因為我們無法保證要求會在 importModeExpireTime 前送達，且系統在到期時間觸發的資料處理作業可能會發生衝突。建議您在importModeExpireTime前至少 30 分鐘撥打 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 使用者存取最近匯入的聊天室，Chat 應用程式可以在首次呼叫 create.space() 方法後的 90 天內，繼續使用 chat.import 範圍和使用者模擬功能，執行下列操作：

• 在聊天室中新增成員：在 Membership 資源上呼叫 create() 方法。建議 Chat 應用程式在聊天室匯入完成後立即建立 Membership 資源，這樣 Chat 應用程式就能繼續使用 chat.import 範圍，並確保所有匯入的成員都能存取聊天室。您應優先新增可能受保管箱訴訟保留政策約束的成員，這樣即使匯入的訊息超出保留期限，系統仍會保留。
• 設定目標對象：在 Space 資源上呼叫 update() 方法。如要瞭解如何建立及新增目標對象，請參閱「讓 Google Workspace 機構中的特定使用者能搜尋到 Google Chat 聊天室」。

如要搭配 chat.import 範圍使用這些方法，遭模擬的使用者必須是工作區管理員。

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

疑難排解

如果匯入即時通空間時發生問題，請參閱下列問題說明。如果收到錯誤回應，請記下錯誤訊息 (將文字複製/貼到文件中，或儲存螢幕截圖)，以供日後參考和排解問題。

成功匯入空間後，CompleteImportSpace 會完成，並顯示 OK 狀態。

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

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

很抱歉，刪除的空間無法再存取或復原，您必須重新啟動匯入程序。

如果空間資料量過大，無法在 90 天內匯入，請將空間分成兩個或多個較小的空間，然後再次啟動匯入程序。如需更多資訊，請參閱使用限制。

尋找遺失的空間

如果找不到新的 Chat 聊天室，請查看下表，瞭解您從 CompleteImportSpace 收到的回覆，以及相關說明和解決方法。