將資料匯入 Google Chat

有了 Google Chat API，您就能將資料從其他訊息平台匯入 Google Chat。您可以從其他訊息平台，匯入現有的訊息、附件、回應、成員資格和聊天室實體，以對應的 Chat API 資源。如要匯入這些資料，您可以在匯入模式中建立 Chat 聊天室，然後將資料匯入這些聊天室。

以下概略說明如何使用匯入模式空間，匯入資料：

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

必要條件

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

視匯入的 Chat 資源數量而定，將資料匯入 Chat 所需的時間可能大不相同。請預先規劃，方法是查看 Chat 應用程式的用量限制，以及從來源訊息平台匯入排定匯入的資料量，以決定預估時間表。

在匯入模式中建立聊天室

如要在匯入模式中建立空間，請呼叫 Space 資源上的 create 方法，並將 importMode 設為 true。為了保留來源訊息傳遞平台中對等空間實體的建立時間，可以設定空間的 createTime。這個 createTime 必須設為介於 2000 年 1 月 1 日到目前時間之間的值。

記下所建立空間的 name，以便在稍後將內容匯入聊天室時參照。

呼叫 create 方法之後，Chat 應用程式有 30 天的時間可以將資源匯入聊天室、完成匯入模式，以及使用 chat.import 範圍建立成員資源。30 天後，即時通訊應用程式仍可透過標準 Chat API 成員範圍建立成員資格。30 天後，如果聊天室仍處於匯入模式，系統會自動將其刪除，且 Chat 應用程式將無法存取及復原。請預先規劃 Chat 應用程式的用量限制，確保能在這段時間內將所有預定資源匯入 Chat。

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

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);
}

"""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 資源 (例如訊息、回應和附件)。在聊天室中建立資源時，您需要從遷移來源的訊息平台指定相關資源的資料。

訊息

您的 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 應用程式」。

歷來會員

歷來成員資格是指使用者已從來源訊息傳遞平台離開原始聊天室實體，但您想在 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。

驗證匯入的資源

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

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

即時通訊應用程式也可以列出 Membership 資源上的 list 方法，列出歷來成員資格。空間結束匯入模式後，list 方法不會再公開歷史成員資格。即時通訊應用程式只能藉由模擬，代表使用者呼叫這個方法。詳情請參閱「授權 Chat 應用程式」。

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

協調匯入的資源與來源資料的差異

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

訊息

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

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

回應

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

附件

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

歷來會員

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

您無法在匯入模式空間中更新過往成員。如果要修正匯入的歷來成員資料有誤，必須先刪除該成員，然後在該空間仍處於匯入模式時重新建立。

聊天室

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

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

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

完成匯入模式

呼叫 completeImport 方法之前，請務必確保已完成驗證和資源差異的對帳程序。退出匯入模式後，空間即無法回復，並將匯入模式空間轉換為一般空間。Chat 中不會有任何指標會將這些聊天室歸因於資料匯入。

如要完成匯入模式，並讓使用者存取聊天室，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：在匯入模式中建立的聊天室名稱。

建立成員資源

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

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

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