Google Chat API を使用すると、他のメッセージング プラットフォームから Google Chat にデータをインポートできます。他のメッセージング プラットフォームから対応する Chat API リソースに、既存のメッセージ、添付ファイル、リアクション、メンバーシップ、スペース エンティティをインポートできます。このデータをインポートするには、Chat スペースをインポート モードで作成し、それらのスペースにデータをインポートします。
インポート モードのスペースを使用してデータをインポートする手順の概要は次のとおりです。
- API の使用制限を確認し、事前に計画を立てます。
- Chat アプリの認可を構成します。
- インポート モードでスペースを作成します。
- リソースをインポートする。
- インポートされたリソースを検証する。
- インポートされたリソースの差異をソースデータから調整する。
- 完全インポート モード。
- メンバーシップ リソースを作成する。
前提条件
Apps Script
- Google Chat へのアクセス権を持つ Google Workspace アカウント。
- 公開されている Chat アプリ。Chat アプリを作成するには、このquickstartの手順に沿ってください。
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
をメモしておきます。
Chat アプリは、create
メソッドが呼び出されてから 30 日間、スペースにリソースをインポートし、インポート モードを完了して、chat.import
スコープを使用してメンバーシップ リソースを作成する必要があります。Chat アプリでは、30 日後以降も、標準の Chat API メンバーシップ スコープを使用してメンバーシップを作成できます。30 日が経過してもインポート モードのままだと、スペースは自動的に削除され、アクセスできなくなり、Chat アプリからは復元できなくなります。あらかじめ計画して、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 リソース(メッセージ、リアクション、添付ファイルなど)を作成します。スペースでリソースを作成するときに、移行元のメッセージ プラットフォームからの関連リソースのデータを指定します。
メッセージ
Chat アプリは、独自の権限を使用して、またはユーザーの代わりに権限借用によってメッセージをインポートできます。(メッセージ作成者は権限借用されたユーザー アカウントに設定されます)。詳細については、Chat アプリを承認するをご覧ください。インポート モードのスペースにメッセージをインポートするには、Message
リソースで create
メソッドを呼び出します。ソース メッセージング プラットフォームからの元のメッセージの作成時刻を保持するには、メッセージの createTime
を設定します。この createTime
は、以前に設定したスペース作成時刻から現在の時刻までの間の値に設定する必要があります。
以前のメッセージが削除されていても、同じスペース内のメッセージに同じ createTime
を含めることはできません。
インポート モードのスペースにサードパーティの URL を含むメッセージでは、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)
次のように置き換えます。
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 Vault などの管理ツールには表示されません。
ユーザーがソース メッセージ プラットフォームでスペースに参加したり、スペースから退出したりする方法は複数あります(招待、ユーザー自身による参加、別のユーザーによる追加)。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)
次のように置き換えます。
EMAIL
: ドメイン全体の権限で権限を借用するユーザー アカウントのメールアドレス。SPACE_NAME
: インポート モードで作成されたスペースの名前。USER_ID
: ユーザーの一意の ID。
インポートされたリソースを検証する
Chat アプリは、Message
リソースに対して list
メソッド を呼び出すことで、インポート モードのスペースの内容を読み取り、検証できます。Reaction
リソースと Attachment
リソースは、返されたメッセージの emojiReactionSummaries
フィールドと attachment
フィールドから読み取ることができます。チャットアプリは、権限借用によってユーザーの代わりにのみこのメソッドを呼び出すことができます。詳細については、Chat アプリを承認するをご覧ください。
Chat アプリでは、Message
リソースの get
メソッドを呼び出すことで、検証のために個々のメッセージを読み取ることもできます。チャットアプリは、このメソッドを呼び出して、自身の権限を使用して自身のメッセージを読み取ることができます。詳細については、Chat アプリを承認するをご覧ください。
Chat アプリでは、Membership
リソースで list
メソッドを呼び出して、過去のメンバーシップを一覧表示することもできます。スペースがインポート モードを終了すると、list
メソッドは過去のメンバーシップを公開しなくなります。チャットアプリは、権限借用によってユーザーの代わりにのみ、このメソッドを呼び出すことができます。詳細については、Chat アプリを承認するをご覧ください。
インポート モードのスペースのプロパティを読み取るには、Space
リソースの get
メソッドを呼び出します。チャットアプリは、独自の権限を使用してのみ、このメソッドを呼び出すことができます。詳細については、Chat アプリを承認するをご覧ください。
インポートされたリソースの差異をソースデータと照合する
インポート中に元のエンティティが変更されたため、インポートされたリソースがソース メッセージ プラットフォームの元のエンティティと一致しなくなった場合、チャットアプリは Chat API を呼び出して、インポートされたチャット リソースを変更できます。たとえば、Chat でメッセージが作成された後に、ユーザーがソース メッセージング プラットフォームでメッセージを編集すると、Chat アプリはインポートされたメッセージを更新して、元のメッセージの現在のコンテンツを反映できます。
メッセージ
インポート モードのスペースでメッセージでサポートされているフィールドを更新するには、Message
リソースの update
メソッドを呼び出します。チャットアプリは、最初のメッセージ作成時に使用したのと同じ権限を使用してのみ、このメソッドを呼び出すことができます。最初のメッセージの作成時にユーザーの権限借用を使用した場合は、権限借用した同じユーザーを使用してメッセージを更新する必要があります。
インポート モードのスペース内のメッセージを削除するには、Message
リソースの delete
メソッドを呼び出します。インポート モードのスペース内のメッセージは、元のメッセージ作成者が削除する必要はなく、ドメイン内の任意のユーザーになりすますことで削除できます。Chat アプリは、自身の権限を使用してのみ、自身のメッセージを削除できます。詳細については、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
メソッドで権限を借用するユーザーがスペース作成者である必要はありません。
次の例は、インポート モードを完了する方法を示しています。
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)
次のように置き換えます。
EMAIL
: ドメイン全体の権限で権限を借用するユーザー アカウントのメールアドレス。SPACE_NAME
: インポート モードで作成されたスペースの名前。
メンバーシップ リソースを作成する
インポート モードが完了したスペースにユーザー メンバーシップを追加するには、Membership
リソースで create
メソッドを呼び出します。チャットアプリは、最初の create.space
メソッド呼び出しから 30 日以内であれば、引き続き chat.import
スコープとユーザーの権限借用を使用して、このメソッドを呼び出すことができます。権限を借用するユーザーはスペースの管理者である必要があります。
30 日が経過すると、Chat アプリでこのメソッドを呼び出すには、追加のメンバーシップ スコープが必要になります。
インポート完了後すぐに Chat アプリでメンバーシップ リソースを作成することをおすすめします。これにより、Chat アプリはメンバーの作成に引き続き chat.import
スコープを使用し、インポートされたスペースへのアクセス権をすべてのメンバーに提供できます。