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 zaimportować 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

Planowanie importu

Zaplanuj odpowiednio ilość danych do zaimportowania, sprawdź, jak limity i kwoty limitów mogą wpływać na proces importowania, i poznaj typy pokojów Google Chat obsługiwane podczas importowania do nowego pokoju.

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 wykorzystania aplikacji Google Chat oraz ilość danych zaplanowanych do zaimportowania ze źródłowej platformy do obsługi wiadomości.

Podczas importowania wiadomości do pokoju zalecamy rozłożenie wywołań metody messages.create() w różnych wątkach 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 dotyczącej 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 30 dni. Jeśli po 30 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ć.
  • Nie używaj wartości pola createTime do śledzenia daty wygaśnięcia 30-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łuje się później 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:

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 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 czatu. Zalecamy użycie tej samej wyświetlanej nazwy co miejsce, z którego importujesz dane.

Importuj zasoby

Aby zaimportować zasoby z innych platform do przesyłania wiadomości, musisz utworzyć zasoby Google Chat (takie jak wiadomości, reakcje, załączniki) w pokoju trybu importu. 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 jest ustawiony jako konto użytkownika, którego tożsamość zostaje podszywana. 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 wcześniej 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 nie wysyłają e-maili do żadnych użytkowników, w tym wiadomości zawierających wzmianki użytkowników.

Z przykładu poniżej dowiesz się, 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 chcesz udawać, z uprawnieniami na poziomie domeny.
• SPACE_NAME: nazwa pokoju utworzonego w trybie importowania.

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 identyfikatorów URI plików do odpowiednich wiadomości w przestrzeniach trybu importowania w celu importowania załączników z innych platform komunikacyjnych, aby uniknąć przekroczenia wewnętrznego limitu przesyłania załączników w Google Chat.

Wcześniejsze subskrypcje

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 opuszczenia historycznej subskrypcji, musisz ustawić jej deleteTime. Czas przerwy musi być dokładny, ponieważ wpływa na to, które dane należy zachować w przypadku tych członkostw. Co więcej, ten deleteTime musi 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 ustawiona, wartość createTime jest obliczana automatycznie przez odjęcie 1 mikrosekundy od wartości deleteTime. Jeśli jest ustawiony, createTime musi być wcześniejszy niż deleteTime i musi być ustawiony na czas utworzenia pokoju lub późniejszy. Informacje te createTime nie służą do określania zasad 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:

"""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 chcesz udawać, z uprawnieniami na poziomie domeny.
• SPACE_NAME: nazwa pokoju utworzonego w trybie importowania.
• USER_ID: unikalny identyfikator użytkownika.

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. Ma to zastosowanie tylko wtedy, 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. Możesz odczytać zasoby Reaction i Attachment z pól emojiReactionSummaries i attachment każdej zwróconej wiadomości. Aplikacje do obsługi czatu mogą wywoływać tę metodę tylko w imieniu użytkownika przez przejmowanie tożsamości. 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 o autoryzowaniu aplikacji Google Chat.

Aplikacje do obsługi czatu mogą też wyświetlać historyczne informacje o członkostwie, wywołując metodę list w zasobie Membership. Gdy pokój wyjdzie z trybu importowania, metoda list nie będzie już wyświetlać historii członkostwa w pokoju. 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 zasobie Space. 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 Google Chat.

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

Jeśli dowolny zaimportowany zasób nie pasuje do pierwotnego elementu z platformy komunikatora źródłowego z powodu zmian w pierwotnym elemencie podczas importu, aplikacje Google Chat 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 obsługi 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 obsługi czatu mogą usuwać własne wiadomości tylko za pomocą własnego upoważnienia. Więcej informacji znajdziesz w artykule Autoryzowanie aplikacji na czacie.

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.

Wcześniejsze subskrypcje

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żesz zaktualizować historycznego członkostwa. Jeśli chcesz poprawić nieprawidłowo zaimportowane historyczne członkostwo, musisz je najpierw usunąć, a następnie utworzyć ponownie, 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ń trybu importu, użyj metody delete w zasobie spaces.

Informacje o metodach zasobów 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ź. Jest to pomocne, gdy napotkasz jakieś problemy i musisz je zbadać.

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 rolę odgrywasz w roli użytkownika, zostanie dodany do pokoju jako menedżer pokoju. Tę metodę należy wywołać w ciągu 30 dni od jej początkowego wywołania create.space. Jeśli spróbujesz wywołać tę metodę po upływie 30 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, pod który podszywa się użytkownik, używając metody completeImport, nie musi być twórcą pokoju.

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

"""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 chcesz udawać, z uprawnieniami na poziomie domeny.
• SPACE_NAME: nazwa pokoju utworzonego w trybie importowania.

Przyznawanie dostępu do pokoju po zakończeniu importowania

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

• Dodawanie użytkowników do pokoju: wywołaj metodę create() w zasobie 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.
• 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 używać 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 napotkasz błąd, zapisz odpowiedź (skopiuj i wklej tekst do dokumentu lub zapisz zrzut ekranu), by móc z niej korzystać w przyszłości i rozwiązywać problemy.

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

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

Jak opisano wcześniej w sekcji Tworzenie pokoju w trybie importowania, jeśli po 30 dniach od wywołania metody create pokój będzie nadal 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 uzyskać wyjaśnienie i sposób rozwiązania problemu.