將資料匯入 Google Chat

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

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

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

必要條件

規劃匯入作業

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

查看 API 用量限制

匯入資料至 Chat 所需的時間會因要匯入的 Chat 資源量而有很大差異。查看 Chat 應用程式的使用限制，以及從來源訊息平台匯入的資料量，以便決定預估時間表。

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

找出要匯入的支援空間

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

在匯入模式中建立聊天室

如要在匯入模式中建立空格，請在 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 資源 (例如訊息、回應、附件)。在聊天室中建立資源時，您會指定來自遷移來源訊息平台的相關資源資料。

訊息

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 應用程式只能使用自己的權限呼叫這個方法，讀取自己的訊息。詳情請參閱「授權 Chat 應用程式」。

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

您可以呼叫 Space 資源的 get 方法，讀取匯入模式空間的屬性。回應也會填入 importModeExpireTime，方便您正確追蹤完成匯入程序的時間範圍。即時通訊應用程式只能使用自己的權限呼叫這個方法。詳情請參閱「授權 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 Chat 聊天室可供 Google Workspace 機構中的特定使用者探索」。

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

對於外部聊天室，create() 方法也允許邀請 Workspace 機構外的使用者。請務必瞭解外部使用者的所有已知限制。

疑難排解

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

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

未在 90 天回溯期過期前完成匯入作業

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

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

尋找遺漏的空格

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