Importowanie danych do Google Chat

Interfejs Google Chat API umożliwia importowanie danych z innych platform do przesyłania wiadomości do Google Chat. Możesz importować istniejące wiadomości, załączniki, reakcje, członkostwa i obiekty pokoju z innych platform do przesyłania wiadomości do odpowiednich zasobów interfejsu Chat API. Możesz zaimportować te dane, tworząc pokoje czatu w trybie importowania i importując do nich dane. Po zakończeniu procesu te pokoje staną się standardowymi pokojami czatu.

Poniżej znajdziesz opis całego procesu importowania:

1. Zaplanuj import
2. Konfigurowanie autoryzacji aplikacji Google Chat
3. Tworzenie pokoju w trybie importu
4. Importowanie zasobów
5. Weryfikowanie zaimportowanych zasobów
6. Uzgodnij różnice między zaimportowanymi zasobami a danymi źródłowymi
7. Tryb pełnego importu
8. Przyznawanie dostępu do pokoju po włączeniu trybu importowania
9. Rozwiązywanie problemów

Wymagania wstępne

Planowanie importu

Odpowiednio zaplanuj ilość danych do zaimportowania, dowiedz się, jak limity wykorzystania i limity mogą wpłynąć na proces importowania, i poznaj typy przestrzeni w Chat, które są obsługiwane podczas importowania do nowej przestrzeni. Jeśli jesteś administratorem, przeczytaj artykuł Importowanie danych wiadomości z innej usługi do Google Chat i postępuj zgodnie z instrukcjami.

Sprawdzanie limitów wykorzystania interfejsu API

Czas potrzebny na zaimportowanie danych do Google Chat może się znacznie różnić w zależności od liczby zasobów Google Chat do zaimportowania. Sprawdź limity użytkowania aplikacji Chat i ilość danych zaplanowanych do importowania z platformy źródłowej, aby określić szacowany harmonogram.

Podczas importowania wiadomości do pokoju zalecamy rozłożenie wywołań metody messages.create() na różne wątki wiadomości.

Określ obsługiwane przestrzenie do zaimportowania

Tryb importowania obsługuje tylko SpaceType z SPACE i GROUP_CHAT. Nie obsługuje ona języka DIRECT_MESSAGE. Więcej informacji znajdziesz w dokumentacjiSpaceType.

Tworzenie pokoju w trybie importowania

Aby utworzyć pokój w trybie importowania, wywołaj metodę create w zasobie Space i ustaw importMode na true.

Podczas tworzenia pokoju w trybie importowania pamiętaj o tych kwestiach:

• Data i godzina – pamiętaj, że tryb importowania musi zostać ukończony w ciągu 90 dni. Jeśli po 90 dniach od wywołania metody spaces.create() pokój będzie nadal w trybie importowania, zostanie on automatycznie usunięty, stanie się niedostępny i nie będzie można go odzyskać.
  • Użyj wartości pola importModeExpireTime, aby śledzić upływ 90-dniowego okresu.
  • Nie używaj wartości pola createTime do śledzenia upływu 90-dniowego okresu. Nie zawsze jest to takie samo jak w przypadku wywołania metody spaces.create(). W trybie importu pole createTime można ustawić na historyczną sygnaturę czasową, w której pokój został utworzony w źródle, aby zachować pierwotny czas utworzenia.
• Nazwa zasobu przestrzeni (name) – unikalny identyfikator używany do pobierania informacji o konkretnej przestrzeni. Jest on używany w późniejszych krokach podczas importowania treści do przestrzeni.

Aby zachować czas utworzenia odpowiedniego obiektu przestrzeni z źródłowej platformy komunikacyjnej, możesz ustawić createTime przestrzeni. Ten createTime musi mieć wartość z zakresu od 1 stycznia 2000 r. do chwili obecnej.

Aby utworzyć zewnętrzny pokój w trybie importowania, ustaw wartość externalUserAllowed na true. Po zakończeniu importu możesz dodać użytkowników zewnętrznych.

Poniższy przykład pokazuje, jak utworzyć pokój w trybie importowania:

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)

Zastąp następujące elementy:

• EMAIL: adres e-mail konta użytkownika, którego tożsamość jest podszywana w ramach uprawnień w całej domenie.
• DISPLAY_NAME: nazwa pokoju utworzonego w trybie importowania. Musi to być unikalna nazwa przestrzeni wyświetlana użytkownikom Chatu. Zalecamy użycie tej samej nazwy wyświetlanej co w przypadku przestrzeni, z której importujesz dane.

Importowanie zasobów

Aby zaimportować zasoby z innych platform do obsługi wiadomości, utwórz zasoby Google Chat (takie jak wiadomości, reakcje, załączniki) w pokoju w trybie importu. Gdy tworzysz zasób w pokoju, określasz dane z powiązanego zasobu na platformie do obsługi wiadomości, z której przeprowadzasz migrację.

Wiadomości

Aplikacje do obsługi czatu mogą importować wiadomości na podstawie własnych uprawnień lub w imieniu użytkownika przez podszywanie się pod niego. Autorem wiadomości jest konto użytkownika, którego tożsamość została przejęta. Więcej informacji znajdziesz w artykule Autoryzowanie aplikacji Google Chat. Aby zaimportować wiadomość do pokoju w trybie importowania, wywołaj metodę create w Messagezasobie. Aby zachować czas utworzenia oryginalnej wiadomości z platformy źródłowej, możesz ustawić createTime wiadomości. Ten parametr createTime musi mieć wartość z zakresu od czasu utworzenia przestrzeni, który został wcześniej ustawiony, do bieżącego czasu.

Wiadomości w tym samym pokoju nie mogą zawierać tego samego znacznika createTime, nawet jeśli poprzednie wiadomości z tym znacznikiem zostały usunięte.

Wiadomości zawierające adresy URL innych firm w pokojach w trybie importowania nie mogą renderować podglądów linków w Google Chat.

Gdy tworzysz wiadomości w trybie importowania, pokoje nie wysyłają powiadomień ani e-maili do żadnych użytkowników, w tym wiadomości zawierających wzmianki o użytkownikach.

Ten przykład pokazuje, jak utworzyć wiadomość w pokoju w trybie importowania:

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

Zastąp następujące elementy:

• EMAIL: adres e-mail konta użytkownika, którego tożsamość podszywasz z uprawnieniami w całej domenie.
• SPACE_NAME: nazwa pokoju utworzonego w trybie importu.

Reakcje

Aplikacja Chat może importować reakcje na wiadomości za pomocą interfejsu Chat API. Informacje o metodach zasobów i typach uwierzytelniania obsługiwanych w przestrzeniach w trybie importowania znajdziesz w artykule Autoryzowanie aplikacji Google Chat.

Załączniki

Aplikacja do obsługi czatu może przesyłać załączniki za pomocą interfejsu Chat API. Informacje o metodach zasobów i typach uwierzytelniania obsługiwanych w przestrzeniach w trybie importowania znajdziesz w artykule Autoryzowanie aplikacji Google Chat. Zdecydowanie zalecamy jednak używanie interfejsu Google Drive API do przesyłania załączników jako plików na Dysk Google i łączenia identyfikatorów URI plików z odpowiednimi wiadomościami w przestrzeniach trybu importowania, aby importować załączniki z innych platform do przesyłania wiadomości i uniknąć osiągnięcia wewnętrznego limitu przesyłania załączników w Google Chat.

Historia członkostwa

Historyczne członkostwa to członkostwa utworzone dla użytkowników, którzy opuścili już pierwotny pokój na źródłowej platformie do przesyłania wiadomości, ale chcesz zachować ich dane w Google Chat. Informacje o dodawaniu nowych osób, gdy pokój nie jest już w trybie importowania, znajdziesz w artykule Tworzenie zasobu członkostwa.

W wielu przypadkach, gdy ci historyczni członkowie podlegają zasadom przechowywania danych w Google, chcesz zachować dane (takie jak wiadomości i reakcje) utworzone przez historycznych członków w pokoju przed zaimportowaniem ich do Google Chat. Gdy pokój jest w trybie importowania, możesz zaimportować do niego te historyczne członkostwa za pomocą metody create w zasobie Membership. Aby zachować czas urlopu w przypadku historycznego członkostwa, musisz ustawić deleteTime członkostwa. Ten czas opuszczenia musi być dokładny, ponieważ wpływa na to, które dane mają być przechowywane w przypadku tych członkostw. Ponadto deleteTimemusi być późniejsza niż sygnatura czasowa utworzenia pokoju i nie może być sygnaturą czasową z przyszłości.

Oprócz parametru deleteTime możesz też ustawić parametr createTime, aby zachować pierwotny czas dołączenia do historycznej oferty. W przeciwieństwie do deleteTime element createTime jest opcjonalny. Jeśli nie jest ustawiona, wartość createTime jest obliczana automatycznie przez odjęcie 1 mikrosekundy od wartości deleteTime. Jeśli jest ustawiona, wartość createTime musi być wcześniejsza niż deleteTime i musi przypadać w dniu utworzenia pokoju lub później. Te createTimeinformacje nie są używane do określania czasu przechowywania danych i nie są widoczne w narzędziach administracyjnych, takich jak konsola administracyjna Google i Google Vault.

Użytkownik może dołączyć do pokoju i opuścić go na wiele sposobów na źródłowej platformie do przesyłania wiadomości (przez zaproszenia, samodzielne dołączenie, dodanie przez innego użytkownika), ale w Google Chat te działania są reprezentowane przez pola createTime i deleteTime w historii członkostwa jako dodanie lub usunięcie.

Poniższy przykład pokazuje, jak utworzyć historyczne członkostwo w przestrzeni w trybie importowania:

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

Zastąp następujące elementy:

• EMAIL: adres e-mail konta użytkownika, którego tożsamość podszywasz z uprawnieniami w całej domenie.
• SPACE_NAME: nazwa pokoju utworzonego w trybie importu.
• USER_ID: unikalny identyfikator użytkownika.

Importowanie zasobów w pokoju zewnętrznym

Zewnętrzny pokój czatu w trybie importowania możesz utworzyć tylko przy użyciu danych logowania użytkowników w organizacji Workspace. Dotyczy to tylko sytuacji, gdy pokój jest w trybie importowania. Gdy pokój zakończy tryb importowania, można zaprosić do niego użytkowników zewnętrznych (patrz sekcja dostępu), a ich dane logowania mogą być używane do wywoływania interfejsu Chat API.

Weryfikowanie zaimportowanych zasobów

Aplikacja Google Chat może odczytać i zweryfikować zawartość pokoju w trybie importowania, wywołując list metodę w Messagezasobie. Zasoby Reaction i Attachment możesz odczytać z pól emojiReactionSummaries i attachment w dowolnej zwróconej wiadomości. Aplikacje do czatu mogą wywoływać tę metodę w imieniu użytkownika tylko przez personifikację. Więcej informacji znajdziesz w artykule Autoryzowanie aplikacji Google Chat.

Aplikacja Google Chat może też odczytywać poszczególne wiadomości w celu weryfikacji, wywołując metodę get w zasobie Message. Aplikacje do obsługi czatu mogą wywoływać tę metodę tylko w celu odczytywania własnych wiadomości, korzystając z własnych uprawnień. Więcej informacji znajdziesz w artykule Autoryzowanie aplikacji Google Chat.

Aplikacje do czatu mogą też wyświetlać listę historycznych członkostw, wywołując metodę list w Membershipzasobie. Gdy pokój wyjdzie z trybu importowania, metoda list nie będzie już udostępniać historycznych członkostw. Aplikacje do czatu mogą wywoływać tę metodę tylko w imieniu użytkownika przez podszywanie się. Więcej informacji znajdziesz w artykule Autoryzowanie aplikacji Google Chat.

Właściwości przestrzeni w trybie importowania możesz odczytać, wywołując metodę get w zasobie Space. W odpowiedzi pojawi się też pole importModeExpireTime, dzięki czemu będziesz mieć możliwość śledzenia czasu potrzebnego na ukończenie procesu importu. Aplikacje do obsługi czatu mogą wywoływać tę metodę tylko na podstawie własnych uprawnień. Więcej informacji znajdziesz w artykule Autoryzowanie aplikacji Google Chat.

Uzgodnij różnice między zaimportowanymi zasobami a danymi źródłowymi

Jeśli którykolwiek z zaimportowanych zasobów nie pasuje już do pierwotnego elementu z źródłowej platformy komunikacyjnej z powodu zmian wprowadzonych w tym elemencie podczas importowania, aplikacje do obsługi czatu mogą wywołać interfejs Chat API, aby zmodyfikować zaimportowany zasób czatu. Jeśli na przykład użytkownik edytuje wiadomość na źródłowej platformie do przesyłania wiadomości po jej utworzeniu w Google Chat, aplikacje Google Chat mogą zaktualizować zaimportowaną wiadomość, aby odzwierciedlała bieżącą treść oryginalnej wiadomości.

Wiadomości

Aby zaktualizować obsługiwane pola w wiadomości w pokoju w trybie importu, wywołaj metodę update w zasobie Message. Aplikacje do obsługi czatu mogą wywoływać tę metodę tylko przy użyciu tych samych uprawnień, które zostały użyte podczas tworzenia pierwszej wiadomości. Jeśli podczas tworzenia pierwszej wiadomości użyto personifikacji użytkownika, do zaktualizowania tej wiadomości musisz użyć tego samego użytkownika.

Aby usunąć wiadomość w pokoju w trybie importu, wywołaj metodę delete w zasobie Message. Wiadomości w pokoju w trybie importowania nie muszą być usuwane przez pierwotnego twórcę wiadomości i mogą być usuwane przez podszywanie się pod dowolnego użytkownika w domenie. Aplikacje do obsługi czatu mogą usuwać tylko własne wiadomości, korzystając z własnych uprawnień. Więcej informacji znajdziesz w artykule Autoryzowanie aplikacji Google Chat.

Reakcje

Aby usunąć reakcję na wiadomość w pokoju w trybie importowania, użyj metody delete w zasobie reactions. Informacje o metodach zasobów i typach uwierzytelniania obsługiwanych w przestrzeniach w trybie importowania znajdziesz w artykule Autoryzowanie aplikacji Google Chat.

Załączniki

Aby zaktualizować załączniki do wiadomości w przestrzeni w trybie importowania, użyj metody upload w zasobie media. Informacje o metodach zasobów i typach uwierzytelniania obsługiwanych w przestrzeniach w trybie importowania znajdziesz w artykule Autoryzowanie aplikacji Google Chat.

Historia członkostwa

Aby usunąć historyczne członkostwo w przestrzeni w trybie importu, użyj metody delete w zasobie Membership. Gdy przestrzeń wyjdzie z trybu importowania, metoda delete nie będzie już umożliwiać usuwania historycznych członkostw.

Nie możesz zaktualizować historycznego członkostwa w pokoju w trybie importowania. Jeśli chcesz poprawić nieprawidłowo zaimportowane historyczne członkostwo, musisz najpierw je usunąć, a następnie utworzyć ponownie, gdy przestrzeń jest nadal w trybie importowania.

Pokoje

Aby zaktualizować obsługiwane pola w przestrzeni trybu importu, użyj metody patch w zasobie spaces.

Aby usunąć przestrzeń trybu importu, użyj metody delete w przypadku zasobu spaces.

Informacje o metodach zasobów i typach uwierzytelniania obsługiwanych w przestrzeniach w trybie importowania znajdziesz w artykule Autoryzowanie aplikacji do obsługi czatu.

Tryb pełnego importu

Zanim wywołasz metodę completeImport, upewnij się, że weryfikacja i uzgadnianie różnic w zasobach zostały zakończone. Wyjście z trybu importowania jest nieodwracalne i powoduje przekształcenie pokoju w trybie importowania w zwykły pokój. W Chat nie ma wskaźnika, który przypisywałby te pokoje do importu danych.

Zanotuj datę i godzinę wywołania completeImport, nazwę zasobu użytkownika, który wywołał funkcję, oraz zwróconą odpowiedź. Może to być przydatne, jeśli napotkasz problemy i będziesz musiał je zbadać.

Aby ukończyć tryb importowania i udostępnić pokój użytkownikom, aplikacja Google Chat może wywołać metodę completeImport w Spacezasobie. Aplikacje do czatu mogą wywoływać tę metodę w imieniu użytkownika tylko przez podszywanie się. Więcej informacji znajdziesz w artykule Autoryzowanie aplikacji Google Chat. Po zakończeniu tej metody użytkownik, którego tożsamość została przejęta, zostanie dodany do pokoju jako menedżer pokoju. Ta metoda musi być wywoływana w ciągu 90 dni od pierwszego wywołania metody create.space. Jeśli spróbujesz wywołać tę metodę po upływie 90 dni, wywołanie zakończy się niepowodzeniem, ponieważ pokój w trybie importowania zostanie usunięty i nie będzie już dostępny dla aplikacji Chat.

Użytkownik, którego tożsamość jest podszywana w metodzie completeImport, nie musi być twórcą przestrzeni.

Nie wywołuj funkcji completeImport zbyt blisko importModeExpireTime, ponieważ nie możemy zagwarantować, że żądanie dotrze przed importModeExpireTime. Może to też powodować konflikty z przetwarzaniem danych w systemach uruchamianych w momencie wygaśnięcia. Zalecamy zadzwonić pod numer completeImport co najmniej 30 minut przed importModeExpireTime.

Poniższy przykład pokazuje, jak zakończyć tryb importu:

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

Zastąp następujące elementy:

• EMAIL: adres e-mail konta użytkownika, którego tożsamość podszywasz z uprawnieniami w całej domenie.
• SPACE_NAME: nazwa pokoju utworzonego w trybie importu.

Przyznawanie dostępu do pokoju po trybie importowania

Aby umożliwić użytkownikom Google Chat dostęp do niedawno zaimportowanego pokoju, aplikacje na czacie mogą nadal używać zakresu chat.import i podszywania się pod użytkownika w ciągu 90 dni od pierwszego wywołania metody create.space() w celu wykonania tych czynności:

• Dodaj użytkowników do pokoju: wywołaj metodę create() na zasobie Membership. Zalecamy, aby aplikacje Google Chat tworzyły zasoby Membership natychmiast po zakończeniu importowania pokoju, dzięki czemu aplikacje Google Chat będą mogły nadal korzystać z zakresu chat.import i zapewnić, że wszyscy zaimportowani użytkownicy będą mieli dostęp do pokoju. Priorytetowo traktuj dodawanie członków, którzy mogą podlegać zasadom blokady Vault, które umożliwiają zachowywanie zaimportowanych wiadomości nawet wtedy, gdy przekroczą one okres przechowywania.
• Ustawianie grupy docelowej: wywołaj update() metodę w zasobie Space. Aby dowiedzieć się, jak tworzyć i dodawać grupy odbiorców, przeczytaj artykuł Udostępnianie pokoju w Google Chat konkretnym użytkownikom w organizacji Google Workspace.

Aby używać tych metod w zakresie chat.import, użytkownik, którego tożsamość jest podszywana, musi być menedżerem pokoju.

W przypadku pokoi zewnętrznych metoda członkostwa create() umożliwia też zapraszanie użytkowników spoza organizacji Workspace. Upewnij się, że znasz wszystkie znane ograniczenia dotyczące użytkowników zewnętrznych.

Rozwiązywanie problemów

Jeśli podczas importowania przestrzeni w Google Chat wystąpi problem, zapoznaj się z poniższymi informacjami. Jeśli otrzymasz odpowiedź o błędzie, zanotuj ją (skopiuj i wklej tekst do dokumentu lub zapisz zrzut ekranu), aby móc z niej skorzystać w przyszłości podczas rozwiązywania problemów.

Gdy pokój zostanie zaimportowany, CompleteImportSpace zakończy się ze stanem OK.

Nie udało Ci się dokończyć importu przed upływem 90-dniowego okresu

Jak opisano wcześniej w artykule Tworzenie pokoju w trybie importowania, jeśli po 90 dniach od wywołania metody tworzenia pokój będzie nadal w trybie importowania, zostanie on automatycznie usunięty, stanie się niedostępny i nie będzie można go odzyskać.

Usunięty pokój nie jest już dostępny ani nie można go odzyskać, więc proces importowania trzeba rozpocząć od nowa.

Jeśli miejsce nie zostało zaimportowane, ponieważ zawiera zbyt dużo danych, aby można je było zaimportować w 90-dniowym okresie przy obecnych limitach wykorzystania, podziel je na 2 lub więcej mniejszych miejsc do archiwizacji i ponownie rozpocznij proces importowania.

Znajdowanie brakujących pokoi

Jeśli nie możesz znaleźć nowego pokoju czatu, zapoznaj się z tabelą poniżej, aby sprawdzić odpowiedź otrzymaną od CompleteImportSpace i zobaczyć wyjaśnienie oraz sposób rozwiązania problemu.