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() 메서드 호출을 분산하는 것이 좋습니다.

가져올 지원되는 스페이스 식별

가져오기 모드는 SPACE 및 GROUP_CHAT의 SpaceType만 지원합니다. DIRECT_MESSAGE는 지원하지 않습니다. 자세한 내용은 SpaceType 문서를 참고하세요.

가져오기 모드에서 스페이스 만들기

가져오기 모드에서 스페이스를 만들려면 Space 리소스에서 create 메서드를 호출하고 importMode를 true로 설정합니다.

가져오기 모드에서 스페이스를 만들 때는 다음 사항에 유의하세요.

• 날짜 및 시간 - 가져오기 모드는 90일 이내에 완료해야 합니다. spaces.create() 메서드가 호출된 후 90일이 지나도 스페이스가 여전히 가져오기 모드인 경우 자동으로 삭제되어 액세스할 수 없고 복구할 수 없게 됩니다.
  • importModeExpireTime 필드의 값을 사용하여 90일 기간의 만료를 추적합니다.
  • 90일 기간의 만료를 추적하는 데 createTime 필드의 값을 사용하지 마세요. 이는 spaces.create() 메서드를 호출할 때와 항상 동일하지는 않습니다. 가져오기 모드를 사용할 때는 원래 생성 시간을 보존하기 위해 createTime 필드를 소스에서 스페이스가 생성된 이전 타임스탬프로 설정할 수 있습니다.
• 스페이스 리소스 이름 (name): 특정 스페이스에 관한 정보를 가져오는 데 사용되며 스페이스로 콘텐츠를 가져올 때 이후 단계에서 참조되는 고유 식별자입니다.

소스 메시지 플랫폼의 상응하는 스페이스 항목의 생성 시간을 보존하려면 스페이스의 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가 포함될 수 없습니다. 이전에 해당 시간이 포함된 메시지가 삭제되더라도 마찬가지입니다.

가져오기 모드 스페이스에서 서드 파티 URL이 포함된 메시지는 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 Drive API를 사용하여 첨부파일을 Google Drive 파일로 업로드하고 파일 URI를 가져오기 모드 스페이스의 해당 메시지에 연결하여 다른 메시지 플랫폼에서 첨부파일을 가져와 Google Chat 첨부파일 업로드 내부 한도가 초과되지 않도록 하는 것이 좋습니다.

이전 멤버십

이전 멤버십은 소스 메시지 플랫폼에서 원래 스페이스 항목을 이미 탈퇴했지만 Chat에서 데이터를 보존하려는 사용자를 위해 생성된 멤버십입니다. 스페이스가 더 이상 가져오기 모드가 아닌 후에 새 회원을 추가하는 방법에 대한 자세한 내용은 멤버십 리소스 만들기를 참고하세요.

이러한 이전 회원이 Google의 데이터 보관 정책의 적용을 받는 경우, Chat으로 가져오기 전에 스페이스의 이전 멤버십으로 생성된 데이터 (예: 메시지 및 리액션)를 보존하는 것이 좋습니다. 스페이스가 가져오기 모드에 있는 동안 Membership 리소스에서 create 메서드를 사용하여 이전 멤버십을 스페이스로 가져올 수 있습니다. 이전 멤버십의 탈퇴 시간을 보존하려면 멤버십의 deleteTime를 설정해야 합니다. 이 탈퇴 시간은 해당 멤버십에 보관할 데이터에 영향을 미치므로 정확해야 합니다. 또한 이 deleteTime는 스페이스 생성 타임스탬프 이후여야 하며 향후 타임스탬프가 아니어야 합니다.

deleteTime 외에도 createTime를 설정하여 이전 멤버십의 원래 가입 시간을 보존할 수도 있습니다. deleteTime와 달리 createTime는 선택사항입니다. 설정하지 않으면 createTime는 deleteTime에서 1마이크로초를 빼서 자동으로 계산됩니다. 설정된 경우 createTime는 deleteTime 앞에 있어야 하며 스페이스 생성 시간 이후여야 합니다. 이 createTime 정보는 데이터 보관 기간을 결정하는 데 사용되지 않으며 Google 관리 콘솔 및 Google Vault와 같은 관리 도구에는 표시되지 않습니다.

사용자가 소스 메시지 플랫폼에서 스페이스에 참여하거나 스페이스에서 나가는 방법에는 여러 가지가 있을 수 있지만 (초대, 직접 참여, 다른 사용자에 의해 추가됨), 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 앱은 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에는 이러한 스페이스가 데이터 가져오기에 기여했다고 표시하는 표시기가 없습니다.

completeImport를 호출한 날짜 및 시간, 호출한 사용자의 리소스 이름, 반환된 응답을 기록합니다. 이는 문제가 발생하여 조사해야 하는 경우에 유용할 수 있습니다.

가져오기 모드를 완료하고 사용자가 스페이스에 액세스할 수 있도록 하려면 Chat 앱에서 Space 리소스에서 completeImport 메서드를 호출하면 됩니다. Chat 앱은 명의 도용을 통해 사용자를 대신하여만 이 메서드를 호출할 수 있습니다. 자세한 내용은 Chat 앱 승인하기를 참고하세요. 이 메서드가 완료되면 명의 도용된 사용자가 스페이스 관리자로 스페이스에 추가됩니다. 이 메서드는 최초 create.space 메서드 호출 후 90일 이내에 호출되어야 합니다. 90일이 지난 후에 이 메서드를 호출하려고 하면 가져오기 모드 스페이스가 삭제되어 Chat 앱에서 더 이상 액세스할 수 없으므로 호출이 실패합니다.

completeImport 메서드에서 명의 도용된 사용자는 스페이스 작성자가 아니어도 됩니다.

요청이 importModeExpireTime 전에 도착할 것이라고 보장할 수 없으며 만료 시간에 트리거된 시스템의 데이터 처리와 충돌이 발생할 수 있으므로 importModeExpireTime에 너무 가까워지기 전에 completeImport를 호출하지 마세요. 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 앱이 chat.import 범위를 계속 사용할 수 있고 가져온 모든 구성원이 스페이스에 액세스할 수 있도록 Chat 앱은 스페이스 가져오기가 완료된 직후에 Membership 리소스를 만드는 것이 좋습니다. 가져온 메일이 보관 기간을 초과하더라도 보존할 수 있는 Vault 보존 조치 정책이 적용될 수 있는 구성원을 추가하는 것을 우선순위에 두어야 합니다.
• 공유 대상 그룹 설정: Space 리소스에서 update() 메서드를 호출합니다. 공유 대상 그룹을 만들고 추가하는 방법을 알아보려면 Google Workspace 조직의 특정 사용자가 Google Chat 스페이스를 검색할 수 있도록 설정하기를 참고하세요.

chat.import 범위에서 이러한 메서드를 사용하려면 명의 도용된 사용자가 스페이스 관리자여야 합니다.

외부 스페이스의 경우 멤버십 create() 메서드를 사용하여 Workspace 조직 외부의 사용자를 초대할 수도 있습니다. 외부 사용자의 알려진 제한사항을 모두 숙지하세요.

문제 해결

Chat 스페이스를 가져올 때 문제가 발생하면 다음 문제를 검토하여 도움을 받으세요. 오류 응답이 발생하면 나중에 참고하고 문제를 해결할 수 있도록 메모해 두세요 (텍스트를 문서에 복사/붙여넣거나 스크린샷을 저장).

스페이스를 가져오면 CompleteImportSpace가 OK 상태로 완료됩니다.

90일 기간이 만료되기 전에 가져오기를 완료하지 않음

이전에 가져오기 모드로 스페이스 만들기에서 설명한 대로, 만들기 메서드가 호출된 후 90일이 지나도 스페이스가 여전히 가져오기 모드인 경우 자동으로 삭제되어 액세스할 수 없고 복구할 수 없게 됩니다.

삭제된 스페이스는 더 이상 사용할 수 없거나 복구할 수 없으며 가져오기 프로세스를 다시 시작해야 합니다.

누락된 스페이스 찾기

새 Chat 스페이스를 찾을 수 없는 경우 다음 표에서 CompleteImportSpace에서 받은 응답을 검토하여 설명과 해결 방법을 확인하세요.