Nhập dữ liệu vào Google Chat

Với Google Chat API, bạn có thể nhập dữ liệu từ các nền tảng nhắn tin khác vào Google Chat. Bạn có thể nhập các tin nhắn, tệp đính kèm, lượt thể hiện cảm xúc, gói thành viên và thực thể không gian hiện có từ các nền tảng nhắn tin khác vào tài nguyên API Chat tương ứng. Bạn có thể nhập dữ liệu này bằng cách tạo không gian Chat ở chế độ nhập và nhập dữ liệu vào các không gian đó. Sau khi quá trình này hoàn tất, các không gian này sẽ trở thành phòng Chat tiêu chuẩn.

Sau đây là quy trình nhập đầy đủ:

1. Lập kế hoạch nhập
2. Định cấu hình quyền uỷ quyền cho ứng dụng Chat
3. Tạo không gian ở chế độ nhập
4. Nhập tài nguyên
5. Xác thực tài nguyên đã nhập
6. Điều chỉnh sự khác biệt về tài nguyên đã nhập từ dữ liệu nguồn
7. Chế độ nhập hoàn chỉnh
8. Cấp quyền truy cập vào không gian sau khi sử dụng chế độ nhập
9. Khắc phục sự cố

Điều kiện tiên quyết

Lập kế hoạch nhập

Hãy lên kế hoạch cho lượng dữ liệu cần nhập, tìm hiểu cách giới hạn và hạn mức sử dụng có thể ảnh hưởng đến quy trình nhập, đồng thời lưu ý các loại không gian Chat được hỗ trợ khi nhập vào một không gian mới.

Xem lại giới hạn sử dụng API

Thời gian cần thiết để nhập dữ liệu vào Chat có thể khác nhau đáng kể tuỳ thuộc vào số lượng tài nguyên trong Chat cần nhập. Xem lại giới hạn sử dụng của ứng dụng Chat và lượng dữ liệu được lên lịch để nhập từ nền tảng nhắn tin nguồn để xác định tiến trình ước tính.

Khi nhập tin nhắn vào không gian, bạn nên phân phối các lệnh gọi đến phương thức messages.create() trên nhiều chuỗi tin nhắn.

Xác định những không gian được hỗ trợ để nhập

Chế độ nhập chỉ hỗ trợ SpaceType của SPACE và GROUP_CHAT. Phương thức này không hỗ trợ DIRECT_MESSAGE. Hãy xem tài liệu về SpaceType để biết thêm thông tin.

Tạo không gian ở chế độ nhập

Để tạo một không gian ở chế độ nhập, hãy gọi phương thức create trên tài nguyên Space và đặt importMode thành true.

Khi bạn tạo không gian ở chế độ nhập, hãy lưu ý những điều sau.

• Ngày và giờ – Hãy nhớ hoàn tất chế độ nhập trong vòng 30 ngày. Nếu không gian vẫn ở chế độ nhập sau 30 ngày kể từ khi phương thức spaces.create() được gọi, thì không gian đó sẽ tự động bị xoá và không thể truy cập cũng như khôi phục được.
  • Không sử dụng giá trị của trường createTime để theo dõi thời hạn của khung thời gian 30 ngày. Điều này không phải lúc nào cũng giống như khi bạn gọi phương thức spaces.create(). Khi sử dụng chế độ nhập, trường createTime có thể được đặt thành dấu thời gian trước đây mà tại đó không gian được tạo trong nguồn để duy trì thời gian tạo ban đầu.
• Tên tài nguyên không gian (name) – Giá trị nhận dạng duy nhất dùng để truy xuất thông tin về không gian cụ thể và được tham chiếu trong các bước sau khi nhập nội dung vào không gian.

Để giữ nguyên thời gian tạo của thực thể không gian tương đương từ nền tảng nhắn tin nguồn, bạn có thể đặt createTime của không gian. Bạn phải đặt createTime này thành một giá trị trong khoảng từ ngày 1 tháng 1 năm 2000 đến thời điểm hiện tại.

Để tạo không gian bên ngoài ở chế độ nhập, hãy đặt externalUserAllowed thành true. Sau khi nhập xong, bạn có thể thêm người dùng bên ngoài.

Ví dụ sau đây cho thấy cách tạo không gian ở chế độ nhập:

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)

Thay thế nội dung sau:

• EMAIL: địa chỉ email của tài khoản người dùng mà bạn đang mạo danh có quyền trên toàn miền.
• DISPLAY_NAME: tên của không gian được tạo ở chế độ nhập. Đây phải là tên duy nhất cho không gian mà người dùng Chat nhìn thấy. Bạn nên sử dụng tên hiển thị giống với tên của không gian mà bạn đang nhập dữ liệu.

Nhập tài nguyên

Để nhập tài nguyên từ các nền tảng nhắn tin khác, bạn tạo tài nguyên Google Chat (chẳng hạn như tin nhắn, lượt thể hiện cảm xúc, tệp đính kèm) trong không gian ở chế độ nhập. Khi tạo tài nguyên trong không gian, bạn sẽ chỉ định dữ liệu từ tài nguyên liên quan trên nền tảng nhắn tin mà bạn đang di chuyển.

Tin nhắn

Các ứng dụng trong Chat có thể nhập tin nhắn bằng cách sử dụng thẩm quyền của riêng ứng dụng đó hoặc thay mặt cho người dùng bằng cách mạo danh. Tác giả thư được đặt thành tài khoản người dùng được mạo danh. Để biết thêm thông tin, hãy xem phần Uỷ quyền cho ứng dụng Chat. Để nhập thông báo vào không gian chế độ nhập, hãy gọi phương thức create trên tài nguyên Message. Để lưu giữ thời gian tạo tin nhắn gốc từ nền tảng nhắn tin nguồn, bạn có thể đặt createTime của thông báo. Bạn phải đặt createTime này thành một giá trị nằm trong khoảng thời gian tạo không gian mà bạn đã đặt trước đó và thời gian hiện tại.

Các tin nhắn trong cùng một không gian không được chứa cùng một createTime, ngay cả khi các tin nhắn trước đó có cùng thời gian đó đã bị xoá.

Những tin nhắn chứa URL của bên thứ ba trong các phòng ở chế độ nhập không thể hiển thị bản xem trước đường liên kết trong Google Chat.

Khi bạn tạo tin nhắn ở chế độ nhập, các không gian sẽ không thông báo hoặc gửi email cho bất kỳ người dùng nào, bao gồm cả những tin nhắn chứa tính năng nhắc đến người dùng.

Ví dụ sau đây cho thấy cách tạo thông báo trong không gian ở chế độ nhập:

"""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)

Thay thế đoạn mã sau:

• EMAIL: địa chỉ email của tài khoản người dùng mà bạn đang mạo danh với thẩm quyền trên toàn miền.
• SPACE_NAME: tên của không gian được tạo ở chế độ nhập.

Lượt thể hiện cảm xúc

Ứng dụng Chat của bạn có thể nhập phản ứng cho tin nhắn bằng cách sử dụng API Chat. Để biết thông tin về các phương thức tài nguyên và loại hỗ trợ xác thực trong không gian ở chế độ nhập, hãy xem phần Uỷ quyền cho ứng dụng Chat.

Phần đính kèm:

Ứng dụng Chat có thể tải tệp đính kèm lên bằng API Chat. Để biết thông tin về các phương thức tài nguyên và loại hỗ trợ xác thực trong không gian ở chế độ nhập, hãy xem phần Uỷ quyền cho ứng dụng Chat. Tuy nhiên, bạn nên sử dụng API Google Drive để tải tệp đính kèm lên dưới dạng tệp Google Drive và liên kết URI tệp với thư tương ứng trong không gian ở chế độ nhập để nhập tệp đính kèm từ các nền tảng nhắn tin khác nhằm tránh đạt đến giới hạn nội bộ của Google Chat đối với việc tải tệp đính kèm lên.

Gói thành viên trước đây

Gói thành viên trước đây là các gói thành viên được tạo cho những người dùng đã rời khỏi thực thể không gian ban đầu trên nền tảng nhắn tin nguồn, nhưng bạn muốn giữ lại dữ liệu của họ trong Chat. Để biết thông tin về cách thêm thành viên mới sau khi không gian không còn ở chế độ nhập, hãy xem bài viết Tạo tài nguyên gói thành viên.

Trong nhiều trường hợp, khi các thành viên trước đây phải tuân thủ chính sách giữ lại dữ liệu trong Google, bạn sẽ muốn giữ lại dữ liệu (chẳng hạn như Tin nhắn và lượt thể hiện cảm xúc) do các thành viên trước đây tạo ra trong một không gian trước khi nhập vào Chat. Khi không gian đang ở chế độ nhập, bạn có thể nhập các gói thành viên trước đây đó vào không gian bằng cách sử dụng phương thức create trên tài nguyên Membership. Để giữ nguyên thời gian rời khỏi gói thành viên trước đây, bạn phải đặt deleteTime của gói thành viên đó. Thời gian nghỉ phép này phải chính xác vì thời gian này sẽ ảnh hưởng đến dữ liệu cần giữ lại cho các gói hội viên đó. Hơn nữa, deleteTime này phải sau dấu thời gian tạo không gian và không được là dấu thời gian trong tương lai.

Ngoài deleteTime, bạn cũng có thể đặt createTime để giữ nguyên thời gian tham gia ban đầu của gói thành viên trước đây. Không giống như deleteTime, createTime là không bắt buộc. Nếu bạn không đặt chính sách này, createTime sẽ được tự động tính bằng cách trừ đi 1 micrô giây từ deleteTime. Nếu được đặt, createTime phải nằm trước deleteTime và phải vào hoặc sau thời gian tạo không gian. Thông tin createTime này không được dùng để xác định thời gian lưu giữ dữ liệu và không xuất hiện trong các công cụ dành cho quản trị viên như Bảng điều khiển dành cho quản trị viên của Google và Google Vault.

Mặc dù có thể có nhiều cách để người dùng tham gia và rời khỏi không gian trong nền tảng nhắn tin nguồn (thông qua lời mời, tự tham gia, được người dùng khác thêm), nhưng trong Chat, tất cả các hành động đó đều được biểu thị bằng các trường createTime và deleteTime về tư cách thành viên trước đây dưới dạng được thêm hoặc bị xoá.

Ví dụ sau đây cho thấy cách tạo gói thành viên trước đây trong không gian chế độ nhập:

"""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)

Thay thế đoạn mã sau:

• EMAIL: địa chỉ email của tài khoản người dùng mà bạn đang mạo danh có quyền trên toàn miền.
• SPACE_NAME: tên của không gian được tạo ở chế độ nhập.
• USER_ID: mã nhận dạng duy nhất cho người dùng.

Nhập tài nguyên trong không gian bên ngoài

Bạn chỉ có thể tạo không gian bên ngoài ở chế độ nhập bằng thông tin xác thực thuộc về người dùng trong tổ chức Workspace của bạn. Điều này chỉ áp dụng khi không gian đang ở chế độ nhập. Sau khi không gian hoàn tất chế độ nhập, bạn có thể mời người dùng bên ngoài tham gia các không gian đã nhập (xem mục truy cập) và sử dụng thông tin xác thực của họ để gọi Chat API.

Xác thực tài nguyên đã nhập

Ứng dụng Chat có thể đọc lại và xác thực nội dung của không gian chế độ nhập bằng cách gọi phương thức list trên tài nguyên Message. Bạn có thể đọc các tài nguyên Reaction và Attachment từ bất kỳ trường emojiReactionSummaries và attachment nào của thư được trả về. Các ứng dụng Chat chỉ có thể gọi phương thức này thay mặt cho người dùng bằng cách mạo danh. Để biết thêm thông tin, hãy xem phần Uỷ quyền cho ứng dụng Chat.

Ứng dụng Chat cũng có thể đọc từng tin nhắn để xác thực bằng cách gọi phương thức get trên tài nguyên Message. Ứng dụng trò chuyện chỉ có thể gọi phương thức này để đọc tin nhắn của chính ứng dụng bằng cách sử dụng quyền của riêng ứng dụng. Để biết thêm thông tin, hãy xem phần Uỷ quyền cho ứng dụng Chat.

Ứng dụng trò chuyện cũng có thể liệt kê các gói thành viên trước đây bằng cách gọi phương thức list trên tài nguyên Membership. Sau khi không gian thoát khỏi chế độ nhập, phương thức list sẽ không hiển thị các gói thành viên trước đây nữa. Các ứng dụng Chat chỉ có thể gọi phương thức này thay mặt cho người dùng bằng cách mạo danh. Để biết thêm thông tin, hãy xem phần Uỷ quyền cho ứng dụng Chat.

Bạn có thể đọc các thuộc tính của không gian chế độ nhập bằng cách gọi phương thức get trên tài nguyên Space. Ứng dụng trò chuyện chỉ có thể gọi phương thức này bằng quyền của riêng ứng dụng. Để biết thêm thông tin, hãy xem phần Uỷ quyền cho ứng dụng Chat.

Điều chỉnh sự khác biệt về tài nguyên đã nhập từ dữ liệu nguồn

Nếu bất kỳ tài nguyên nào đã nhập không còn khớp với thực thể ban đầu từ nền tảng nhắn tin nguồn do các thay đổi trong thực thể ban đầu trong quá trình nhập, thì ứng dụng Chat có thể gọi Chat API để sửa đổi tài nguyên trò chuyện đã nhập. Ví dụ: nếu người dùng chỉnh sửa một tin nhắn trong nền tảng nhắn tin nguồn sau khi tin nhắn đó được tạo trong Chat, thì các ứng dụng trong Chat có thể cập nhật tin nhắn đã nhập để phản ánh nội dung hiện tại của tin nhắn gốc.

Tin nhắn

Để cập nhật các trường được hỗ trợ trên một thông báo trong không gian chế độ nhập, hãy gọi phương thức update trên tài nguyên Message. Các ứng dụng Chat chỉ có thể gọi phương thức này bằng chính thẩm quyền được dùng trong quá trình tạo tin nhắn ban đầu. Nếu đã sử dụng tính năng mạo danh người dùng trong quá trình tạo thư ban đầu, bạn phải sử dụng chính người dùng đã mạo danh đó để cập nhật thư đó.

Để xoá một thông báo trong không gian ở chế độ nhập, hãy gọi phương thức delete trên tài nguyên Message. Người tạo tin nhắn ban đầu không cần phải xoá tin nhắn trong không gian ở chế độ nhập và bất kỳ người dùng nào trong miền cũng có thể xoá tin nhắn. Ứng dụng trò chuyện chỉ có thể xoá tin nhắn của chính mình bằng quyền của riêng ứng dụng. Để biết thêm thông tin, hãy xem phần Cho phép ứng dụng trong Chat.

Lượt thể hiện cảm xúc

Để xoá một lượt thể hiện cảm xúc cho một tin nhắn trong không gian ở chế độ nhập, hãy sử dụng phương thức delete trên tài nguyên reactions. Để biết thông tin về các phương thức tài nguyên và loại hỗ trợ xác thực trong không gian chế độ nhập, hãy xem phần Cho phép ứng dụng Chat.

Phần đính kèm:

Để cập nhật tệp đính kèm cho một thư trong không gian chế độ nhập, hãy sử dụng phương thức upload trên tài nguyên media. Để biết thông tin về các phương thức tài nguyên và các loại hỗ trợ xác thực trong không gian chế độ nhập, hãy xem phần Cho phép các ứng dụng trong Chat.

Gói hội viên trước đây

Để xoá gói thành viên trước đây trong không gian ở chế độ nhập, hãy sử dụng phương thức delete trên tài nguyên Membership. Sau khi một không gian thoát khỏi chế độ nhập, phương thức delete sẽ không cho phép bạn xoá các gói thành viên trước đây nữa.

Bạn không thể cập nhật gói thành viên trước đây trong không gian ở chế độ nhập. Nếu muốn chỉnh sửa gói thành viên cũ đã nhập không chính xác, trước tiên, bạn cần xoá gói thành viên đó rồi tạo lại gói thành viên đó trong khi không gian vẫn ở chế độ nhập.

Không gian

Để cập nhật các trường được hỗ trợ trong không gian chế độ nhập, hãy sử dụng phương thức patch trên tài nguyên spaces.

Để xoá không gian chế độ nhập, hãy sử dụng phương thức delete trên tài nguyên spaces.

Để biết thông tin về các phương thức tài nguyên và loại hỗ trợ xác thực trong không gian ở chế độ nhập, hãy xem phần Uỷ quyền ứng dụng Chat.

Chế độ nhập hoàn chỉnh

Trước khi gọi phương thức completeImport, bạn cần đảm bảo rằng bạn đã hoàn tất quá trình xác thực và điều chỉnh sự khác biệt về tài nguyên. Việc thoát khỏi chế độ nhập là một quá trình không thể đảo ngược và chuyển đổi không gian ở chế độ nhập thành không gian thông thường. Không có chỉ báo nào trong Chat cho biết các không gian này được phân bổ cho một lượt nhập dữ liệu.

Hãy lưu ý ngày và giờ bạn gọi completeImport, tên tài nguyên của người dùng đã thực hiện lệnh gọi và phản hồi được trả về. Điều này có thể hữu ích nếu bạn phải gặp phải bất kỳ vấn đề nào và phải điều tra các vấn đề đó.

Để hoàn tất chế độ nhập và cho phép người dùng truy cập vào không gian, ứng dụng Chat có thể gọi phương thức completeImport trên tài nguyên Space. Ứng dụng trò chuyện chỉ có thể thay mặt người dùng gọi phương thức này thông qua việc mạo danh. Để biết thêm thông tin, hãy xem phần Uỷ quyền cho ứng dụng Chat. Người dùng được mạo danh sẽ được thêm vào không gian với tư cách là người quản lý không gian sau khi phương thức này hoàn tất. Bạn phải gọi phương thức này trong vòng 30 ngày kể từ lệnh gọi phương thức create.space ban đầu. Nếu bạn cố gắng gọi phương thức này sau khi khoảng thời gian 30 ngày đã trôi qua, thì lệnh gọi sẽ không thành công vì không gian chế độ nhập bị xoá và ứng dụng Chat không thể truy cập được nữa.

Người dùng được nhập vai trong phương thức completeImport không nhất thiết phải là người tạo không gian.

Ví dụ sau đây cho thấy cách hoàn tất chế độ nhập:

"""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)

Thay thế đoạn mã sau:

• EMAIL: địa chỉ email của tài khoản người dùng mà bạn đang mạo danh có quyền trên toàn miền.
• SPACE_NAME: tên của không gian được tạo ở chế độ nhập.

Cấp quyền truy cập vào không gian sau khi nhập

Để cấp cho người dùng Chat quyền truy cập vào không gian mới nhập gần đây, các ứng dụng Chat có thể tiếp tục sử dụng phạm vi chat.import và hoạt động mạo danh người dùng trong vòng 30 ngày kể từ lệnh gọi phương thức create.space() ban đầu để thực hiện những việc sau:

• Thêm thành viên vào không gian: Gọi phương thức create() trên tài nguyên Membership. Bạn nên tạo tài nguyên Membership ngay sau khi nhập không gian cho các ứng dụng trong Chat để các ứng dụng trong Chat có thể tiếp tục sử dụng phạm vi chat.import và đảm bảo rằng tất cả thành viên đã nhập đều có quyền truy cập vào không gian.
• Đặt đối tượng mục tiêu: Gọi phương thức update() trên tài nguyên Space. Để tìm hiểu cách tạo và thêm đối tượng mục tiêu, hãy xem bài viết Giúp những người dùng cụ thể trong tổ chức Google Workspace có thể tìm thấy không gian Google Chat.

Để sử dụng các phương thức này với phạm vi chat.import, người dùng được nhập vai phải là người quản lý không gian.

Đối với không gian bên ngoài, phương thức create() dành cho thành viên cũng cho phép mời người dùng bên ngoài tổ chức Workspace của bạn. Hãy đảm bảo bạn hiểu rõ tất cả các giới hạn đã biết đối với người dùng bên ngoài.

Khắc phục sự cố

Nếu bạn gặp vấn đề khi nhập phòng Chat, hãy xem các vấn đề sau để được hỗ trợ. Nếu bạn gặp một phản hồi lỗi, hãy ghi lại phản hồi đó (sao chép/dán văn bản vào tài liệu hoặc lưu ảnh chụp màn hình) để tham khảo và khắc phục sự cố sau này.

Khi nhập thành công một không gian, CompleteImportSpace sẽ hoàn tất với trạng thái là OK.

Chưa hoàn tất quá trình nhập trước khi khoảng thời gian 30 ngày hết hạn

Như mô tả trước đó trong phần Tạo không gian ở chế độ nhập, nếu không gian vẫn ở chế độ nhập sau 30 ngày kể từ thời điểm phương thức tạo được gọi, thì không gian đó sẽ tự động bị xoá và không thể truy cập cũng như khôi phục được.

Rất tiếc, không gian đã xoá không còn tồn tại hoặc khôi phục được nữa và bạn phải bắt đầu lại quá trình nhập.

Tìm dấu cách bị thiếu

Nếu bạn không tìm thấy không gian Chat mới, hãy xem bảng sau đây để biết nội dung phản hồi mà bạn nhận được từ CompleteImportSpace, đồng thời xem nội dung giải thích và cách giải quyết vấn đề.