Importowanie danych do Google Chat

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

Poniżej znajdziesz opis całego procesu importowania:

  1. Planowanie importu
  2. Konfigurowanie autoryzacji aplikacji Google Chat
  3. Tworzenie pokoju w trybie importowania
  4. Importowanie zasobów
  5. Weryfikowanie zaimportowanych zasobów
  6. Uwzględnij 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

Google Apps Script

Python

Planowanie importu

Zaplanuj odpowiednio ilość danych do zaimportowania, sprawdź, jak limity i kwoty wykorzystania mogą wpływać na proces importowania, oraz zwróć uwagę na typy pokoi czatu obsługiwane podczas importowania do nowego pokoju. 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 użycia interfejsu API

Czas potrzebny na zaimportowanie danych do Google Chat może się znacznie różnić w zależności od ilości zaimportowanych zasobów Google Chat. Aby określić szacunkowy harmonogram, sprawdź limity korzystania z aplikacji Google Chat oraz ilość danych zaplanowanych do zaimportowania z platformy komunikacyjnej źródłowej.

Podczas importowania wiadomości do pokoju zalecamy rozłożenie wywołań do 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 DIRECT_MESSAGE. Więcej informacji znajdziesz w dokumentacji SpaceType.

Tworzenie pokoju w trybie importowania

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

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

  • Data i godzina – pamiętaj, że tryb importowania musi zostać zakoń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ć.
    • Aby śledzić okres ważności 90 dni, użyj wartości pola importModeExpireTime.
    • 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 importowania 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 pokoju (name) – unikalny identyfikator służący do pobierania informacji o konkretnym pokoju, do którego odwołujesz się w kolejnych krokach podczas importowania treści do pokoju.

Aby zachować czas utworzenia odpowiedniego obiektu czatu z platformy komunikacyjnej źródłowej, możesz ustawić createTime czatu. Wartość parametru createTime musi mieścić się w przedziale od 1 stycznia 2000 r. do bieżącej daty.

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

Ten przykład pokazuje, jak utworzyć pokój w trybie importowania:

Google Apps Script

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

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': '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 chcesz się podszyć, z uprawnieniami na poziomie domeny.
  • DISPLAY_NAME: nazwa pokoju utworzonego w trybie importowania. Musi to być unikalna nazwa pokoju wyświetlana użytkownikom Google Chat. 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 importowania. Podczas tworzenia zasobu w pokoju określasz dane z powiązanego zasobu na platformie wiadomości, z której migrujesz.

Wiadomości

Aplikacje Google Chat mogą importować wiadomości, korzystając z własnych uprawnień lub w imieniu użytkownika przez podszywanie się pod niego. Autor wiadomości to konto użytkownika, którego tożsamość została sfałszowana. Więcej informacji znajdziesz w artykule Autoryzowanie aplikacji Google Chat. Aby zaimportować wiadomość w pokoju w trybie importowania, wywołaj metodę create zasobu Message. Aby zachować czas utworzenia oryginalnej wiadomości z źródłowej platformy do przesyłania wiadomości, możesz ustawić createTime wiadomości. Wartość parametru createTime musi mieścić się w przedziale od uprzednio ustawionego czasu utworzenia pokoju do bieżącego czasu.

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

Wiadomości zawierające adresy URL firm zewnętrznych w pokojach w trybie importowania nie mogą wyświetlać podglądu 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 do tych, którzy otrzymują wzmianki.

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

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)

Zastąp następujące elementy:

Reakcje

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

Załączniki

Aplikacja Google Chat może przesyłać załączniki za pomocą interfejsu Chat API. Informacje o metodach zasobów i typach obsługi uwierzytelniania w pokojach w trybie importowania znajdziesz w artykule Autoryzowanie aplikacji Google Chat. Zalecamy jednak używanie interfejsu Google Drive API do przesyłania załączników jako plików z Dysku Google i linkowania URI plików do odpowiednich wiadomości w przestrzeniach w trybie importowania, aby importować załączniki z innych platform komunikacyjnych. Pozwoli to uniknąć przekroczenia wewnętrznego limitu przesyłania załączników w Google Chat.

Historyczne członkostwa

Historyczne członkostwa to członkostwa utworzone dla użytkowników, którzy opuścili pierwotną instancję pokoju na platformie do przesyłania wiadomości, ale chcesz zatrzymać ich dane w Google Chat. Informacje o dodawaniu nowych członków po tym, jak pokój przestanie być importowany, znajdziesz w artykule Tworzenie zasobu członkostwa.

W wielu przypadkach, gdy ci użytkownicy podlegają zasadom Google dotyczącym przechowywania danych, warto zachować dane (takie jak wiadomości i reakcje) utworzone przez nich w ramach wcześniejszych członkostw w pokoju przed zaimportowaniem ich do Google Chat. Gdy pokój jest w trybie importowania, możesz zaimportować te historyczne członkostwa, używając metody create w zasobach Membership. Aby zachować czas odejścia z historycznego członkostwa, musisz ustawić deleteTime subskrypcji. Czas przerwy musi być dokładny, ponieważ wpływa na to, które dane należy zachować w przypadku tych członkostw. Ponadto deleteTimemusi być późniejszy niż sygnatura czasowa utworzenia pokoju i nie może być sygnaturą czasową w przyszłości.

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

Użytkownik może dołączać do pokoju i opuszczać go na platformie do przesyłania wiadomości źródłowej na wiele sposobów (poprzez zaproszenia, samodzielne dołączanie lub dodawanie przez innego użytkownika). W usłudze Chat wszystkie te działania są reprezentowane przez pola createTime i deleteTime dotyczące historycznego członkostwa, które wskazują, że użytkownik został dodany lub usunięty.

Ten przykład pokazuje, jak utworzyć historyczne członkostwo w pokoju w trybie importowania:

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)

Zastąp następujące elementy:

Importowanie zasobów w pokoju zewnętrznym

Pokój zewnętrzny możesz utworzyć tylko w trybie importowania, używając danych logowania należących do użytkowników w Twojej organizacji Workspace. Dotyczy to tylko sytuacji, gdy pokój jest w trybie importowania. Gdy pokój zakończy importowanie, możesz zaprosić do niego użytkowników zewnętrznych (patrz sekcja dotycząca dostępu) i używać ich danych logowania do wywoływania interfejsu Chat API.

Weryfikacja zaimportowanych zasobów

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

Aplikacja Google Chat może też odczytywać pojedyncze wiadomości w celu ich weryfikacji, wywołując metodę get zasobu Message. Aplikacje do czatu mogą wywoływać tę metodę tylko do odczytania własnych wiadomości, korzystając z własnych uprawnień. Więcej informacji znajdziesz w artykule Autoryzowanie aplikacji na czacie.

Aplikacje do czatu mogą też wyświetlać listę członkostw z przeszłości, wywołując metodę list w zasobie Membership. Gdy pokój przejdzie 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ę pod jego tożsamość. Więcej informacji znajdziesz w artykule Autoryzowanie aplikacji na czacie.

Właściwości pokoju w trybie importowania możesz odczytać, wywołując metodę get w Space zasobie. Odpowiedź będzie też zawierać informacje o importModeExpireTime, dzięki czemu będziesz mieć możliwość śledzenia czasu trwania procesu importowania. Aplikacje do obsługi czatu mogą wywoływać tę metodę tylko przy użyciu własnych uprawnień. Więcej informacji znajdziesz w artykule Autoryzowanie aplikacji na czacie.

Pojednanie różnic między zaimportowanymi zasobami a danymi źródłowymi

Jeśli jakikolwiek zaimportowany zasób nie pasuje już do pierwotnego elementu na platformie do przesyłania wiadomości z powodu zmian w pierwotnym elemencie podczas importowania, aplikacje czatu mogą wywołać interfejs API czatu, 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 ona aktualną treść oryginalnej wiadomości.

Wiadomości

Aby zaktualizować obsługiwane pola w wiadomości w pokoju w trybie importowania, wywołaj metodę update w zasobie Message. Aplikacje do czatu mogą wywoływać tę metodę tylko przy użyciu tego samego uprawnienia, które zostało użyte podczas tworzenia wiadomości. Jeśli podczas tworzenia wiadomości została użyta funkcja podszywania się pod użytkownika, musisz użyć tego samego użytkownika, aby zaktualizować wiadomość.

Aby usunąć wiadomość w pokoju w trybie importowania, wywołaj metodę delete w zasobach Message. Wiadomości w pokoju w trybie importowania nie muszą być usuwane przez pierwotnego autora wiadomości i mogą być usuwane przez osobę podszywającą się pod dowolnego użytkownika w domenie. Aplikacje do czatu mogą usuwać tylko własne wiadomości. 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 na zasobie reactions. Informacje o metodach zasobów i typach obsługi uwierzytelniania w pokojach w trybie importowania znajdziesz w artykule Autoryzowanie aplikacji Google Chat.

Załączniki

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

Historyczne członkostwa

Aby usunąć historyczne członkostwo w przestrzeni w trybie importowania, użyj metody delete w zasobach Membership. Gdy konto wyjdzie z trybu importowania, metoda delete nie pozwoli już na usuwanie wcześniejszych członkostw.

W pokoju w trybie importowania nie można zaktualizować historycznego członkostwa. Jeśli chcesz poprawić nieprawidłowo zaimportowane historyczne członkostwo, musisz je najpierw usunąć, a następnie ponownie utworzyć, gdy pokój jest nadal w trybie importowania.

Pokoje

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

Aby usunąć przestrzeń w trybie importowania, użyj metody delete w zasobach spaces.

Informacje o metodach dostępu i typach uwierzytelniania obsługiwanych w pokojach w trybie importowania znajdziesz w artykule Autoryzowanie aplikacji Google Chat.

Tryb pełnego importu

Przed wywołaniem metody completeImport musisz się upewnić, że weryfikacja i zgodność różnic w zasobach zostały zakończone. Wyjście z pokoju w trybie importowania jest procesem nieodwracalnym i powoduje przekształcenie pokoju w pokoju standardowym. W aplikacji Google Chat nie ma wskaźnika, który wskazywałby, że te pokoje zostały utworzone w wyniku importu danych.

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

Aby zakończyć importowanie i udostępnić pokój użytkownikom, aplikacja Google Chat może wywołać metodę completeImport w zasobach Space. Aplikacje do obsługi czatu mogą wywoływać tę metodę tylko w imieniu użytkownika przez podszywanie się pod niego. Więcej informacji znajdziesz w artykule Autoryzowanie aplikacji na czacie. Po zakończeniu tej metody użytkownik, którego dane są podszywane, zostanie dodany do pokoju jako menedżer pokoju. Ta metoda musi być wywołana w ciągu 90 dni od początkowego 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 Google Chat.

Użytkownik, którego metodą completeImport naśladujemy, nie musi być twórcą pokoju.

Nie wykonuj completeImport zbyt blisko daty importModeExpireTime, ponieważ nie możemy zagwarantować, że prośba dotrze przed importModeExpireTime. Mogą też wystąpić konflikty z przetwarzaniem danych w systemach aktywowanych w dacie wygaśnięcia. Zalecamy, aby zadzwonić do completeImport co najmniej 30 minut przed importModeExpireTime.

Ten przykład pokazuje, jak ukończyć importowanie:

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)

Zastąp następujące elementy:

Przyznawanie dostępu do pokoju po zakończeniu importowania

Aby umożliwić użytkownikom Google Chat dostęp do ostatnio zaimportowanego pokoju, aplikacje Google Chat mogą nadal używać zakresu chat.import i podszywania się pod innych użytkowników przez 90 dni od momentu wywołania metody create.space(), aby:

  • Dodawanie użytkowników do pokoju: wywołaj metodę create() zasobu Membership. Zalecamy, aby aplikacje Google Chat tworzyły zasoby Membership natychmiast po zakończeniu importowania pokoju, aby mogły one nadal korzystać z zakresu chat.import. Upewnij się też, że wszyscy zaimportowani członkowie mają dostęp do pokoju. Najpierw dodaj użytkowników, którzy mogą podlegać zasadom blokady Vault. Pozwoli to zachować zaimportowane wiadomości, nawet jeśli przekroczyły okres przechowywania.
  • Ustaw grupę odbiorców docelowych: wywołaj metodęupdate() zasobu Space. Aby dowiedzieć się, jak tworzyć i dodawać grupy odbiorców, przeczytaj artykuł Ustawianie pokoju Google Chat jako dostępnego dla określonych użytkowników w organizacji Google Workspace.

Aby móc korzystać z tych metod w zakresie chat.import, użytkownik, którego dane są podszywane, musi być menedżerem pokoju.

W przypadku pokoi zewnętrznych metoda członkostwa create() pozwala również zapraszać 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 czatu na czacie masz problem, zapoznaj się z poniższymi problemami, aby uzyskać pomoc. Jeśli otrzymasz odpowiedź z błędem, zapisz ją (skopiuj/wklej tekst do dokumentu lub zapisz zrzut ekranu) na przyszłość lub na potrzeby rozwiązywania problemów.

Gdy przestrzeń zostanie zaimportowana, CompleteImportSpace zakończy się z stanem OK.

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

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

Usunięta przestrzeń nie jest już dostępna i nie można jej odzyskać. Należy ponownie rozpocząć proces importowania.

Wyszukiwanie brakujących pokoi

Jeśli nie możesz znaleźć nowego pokoju Google Chat, sprawdź odpowiedź otrzymaną od CompleteImportSpace w tabeli poniżej, aby zobaczyć wyjaśnienie i sposób rozwiązania problemu.

Otrzymano odpowiedź Etapy analizy Wyjaśnienie Rozdzielczość
CompleteImportSpace zgłasza wyjątek, a wywołanie GetSpace zwraca PERMISSION_DENIED. Sprawdź, kiedy pokój został utworzony. Jeśli minęło więcej niż 90 dni, został on automatycznie usunięty. Dodatkowo nie ma rekordu zaimportowanego pokoju w narzędziu do zarządzania pokojem ani w dzienniku kontrolnym. Od rozpoczęcia procesu importowania minęło ponad 90 dni, a migracja nie została zakończona. Utwórz nowy pokój i ponownie przeprowadź proces importowania.
Funkcja CompleteImportSpace zwraca wartość OK, a wywołanie funkcji GetSpace zwraca wartość PERMISSION_DENIED. W narzędziu do zarządzania przestrzenią nie ma rekordu zaimportowanej przestrzeni, ale w dzienniku kontrolnym widać, że została ona usunięta. Pokój został zaimportowany, ale później usunięty. Utwórz nowy pokój i ponownie przeprowadź proces importowania.