Tworzenie i aktualizowanie interaktywnych kart

Z tego przewodnika dowiesz się, jak za pomocą interfejsu Google Chat API tworzyć wiadomości zawierające interaktywne karty w imieniu użytkowników oraz jak asynchronicznie aktualizować te karty.

Tworzenie i aktualizowanie kart jest przydatne, gdy chcesz:

publikować w imieniu użytkownika karty reprezentujące zadanie lub zasób zewnętrzny;
Aktualizuj stan karty (np. z „W trakcie” na „Ukończono”) na podstawie zdarzeń zewnętrznych bez czekania na interakcję użytkownika.
odświeżanie treści karty w wiadomości użytkownika, np. podglądu linku;

Poza programem wczesnego dostępu dla deweloperów wiadomości utworzone z uwierzytelnianiem użytkownika mogą zawierać tylko tekst.

Wymagania wstępne

Node.js

Konto Google Workspace w wersji Business lub Enterprise z dostępem do Google Chat.

Skonfiguruj środowisko:
- Utwórz projekt Google Cloud.
- Skonfiguruj ekran zgody OAuth.
- Włącz i skonfiguruj interfejs Google Chat API, podając nazwę, ikonę i opis aplikacji do obsługi czatu.
- Zainstaluj bibliotekę klienta interfejsu Google API dla Node.js.
- Utwórz dane logowania, które będą zależeć od sposobu uwierzytelniania w żądaniu do interfejsu Google Chat API:
  - Aby uwierzytelnić się jako użytkownik Chatu, utwórz dane logowania identyfikatora klienta OAuth i zapisz je jako plik JSON o nazwie credentials.json w katalogu lokalnym.
  - Aby uwierzytelnić się jako aplikacja do obsługi czatu, utwórz dane logowania konta usługi i zapisz je w pliku JSON o nazwie credentials.json.
Wybierz zakres autoryzacji w zależności od tego, czy chcesz uwierzytelnić się jako użytkownik, czy jako aplikacja do obsługi czatu.

Python

Konto Google Workspace w wersji Business lub Enterprise z dostępem do Google Chat.

Skonfiguruj środowisko:
- Utwórz projekt Google Cloud.
- Skonfiguruj ekran zgody OAuth.
- Włącz i skonfiguruj interfejs Google Chat API, podając nazwę, ikonę i opis aplikacji do obsługi czatu.
- Zainstaluj bibliotekę klienta interfejsu API Google dla języka Python.
- Utwórz dane logowania, które będą zależeć od sposobu uwierzytelniania w żądaniu do interfejsu Google Chat API:
  - Aby uwierzytelnić się jako użytkownik Chatu, utwórz dane logowania identyfikatora klienta OAuth i zapisz je jako plik JSON o nazwie credentials.json w katalogu lokalnym.
  - Aby uwierzytelnić się jako aplikacja do obsługi czatu, utwórz dane logowania konta usługi i zapisz je w pliku JSON o nazwie credentials.json.
Wybierz zakres autoryzacji w zależności od tego, czy chcesz uwierzytelnić się jako użytkownik, czy jako aplikacja do obsługi czatu.

Java

Konto Google Workspace w wersji Business lub Enterprise z dostępem do Google Chat.

Skonfiguruj środowisko:
- Utwórz projekt Google Cloud.
- Skonfiguruj ekran zgody OAuth.
- Włącz i skonfiguruj interfejs Google Chat API, podając nazwę, ikonę i opis aplikacji do obsługi czatu.
- Zainstaluj bibliotekę klienta interfejsów API Google w języku Java.
- Utwórz dane logowania, które będą zależeć od sposobu uwierzytelniania w żądaniu do interfejsu Google Chat API:
  - Aby uwierzytelnić się jako użytkownik Chatu, utwórz dane logowania identyfikatora klienta OAuth i zapisz je jako plik JSON o nazwie credentials.json w katalogu lokalnym.
  - Aby uwierzytelnić się jako aplikacja do obsługi czatu, utwórz dane logowania konta usługi i zapisz je w pliku JSON o nazwie credentials.json.
Wybierz zakres autoryzacji w zależności od tego, czy chcesz uwierzytelnić się jako użytkownik, czy jako aplikacja do obsługi czatu.

Google Apps Script

Konto Google Workspace w wersji Business lub Enterprise z dostępem do Google Chat.

Skonfiguruj środowisko:
- Utwórz projekt Google Cloud.
- Skonfiguruj ekran zgody OAuth.
- Włącz i skonfiguruj interfejs Google Chat API, podając nazwę, ikonę i opis aplikacji do obsługi czatu.
- Utwórz samodzielny projekt Apps Script i włącz zaawansowaną usługę czatu.
- W tym przewodniku musisz użyć uwierzytelniania użytkownika lub aplikacji. Aby uwierzytelnić się jako aplikacja do obsługi czatu, utwórz dane logowania konta usługi. Instrukcje znajdziesz w artykule Uwierzytelnianie i autoryzowanie jako aplikacja Google Chat.
Wybierz zakres autoryzacji w zależności od tego, czy chcesz uwierzytelnić się jako użytkownik, czy jako aplikacja do obsługi czatu.

Tworzenie klucza interfejsu API umożliwiającego dostęp do funkcji wersji przedpremierowej dla programistów

Aby wywołać metodę interfejsu API wersji przedpremierowej dla programistów, musisz użyć niepublicznej wersji przedpremierowej dla programistów dokumentu opisującego interfejs API. Aby uwierzytelnić żądanie, musisz przekazać klucz interfejsu API.

Aby utworzyć klucz interfejsu API, otwórz projekt Google Cloud swojej aplikacji i wykonaj te czynności:

W konsoli Google Cloud otwórz Menu > Interfejsy API i usługi > Dane logowania.
Przejdź do danych logowania
Kliknij Utwórz dane logowania > Klucz interfejsu API.
Wyświetli się nowy klucz interfejsu API.
- Kliknij Kopiuj , aby skopiować klucz interfejsu API do użycia w kodzie aplikacji. Klucz interfejsu API można też znaleźć w sekcji „Klucze interfejsu API” w danych logowania projektu.
- Aby można było zapobiec nieautoryzowanemu użyciu, zalecamy ograniczenie miejsc i interfejsów API, w których można używać klucza API. Więcej informacji znajdziesz w sekcji Dodawanie ograniczeń interfejsu API.

Tworzenie wiadomości z kartą w imieniu użytkownika

Aby utworzyć wiadomość z kartami w imieniu użytkownika, użyj uwierzytelniania użytkownika.

Aby utworzyć wiadomość, w żądaniu podaj te informacje:

Zakres autoryzacji chat.messages.create lub chat.messages.
Pole cardsV2 w zasobie Message zawierające dane karty.
W przypadku każdej karty musisz podać cardId, co jest wymagane w przypadku aktualizacji asynchronicznych.

Poniższy przykład pokazuje, jak utworzyć wiadomość z kartą w imieniu użytkownika:

Node.js

/**
 * This sample shows how to create a message with a card on behalf of a user.
 */
const {google} = require('googleapis');
const {auth} = require('google-auth-library');

async function main() {
  // Create a client
  const authClient = await auth.getClient({
    scopes: ['https://www.googleapis.com/auth/chat.messages.create']
  });
  google.options({auth: authClient});

  // Initialize the Chat API with Developer Preview labels
  const chat = await google.discoverAPI(
    'https://chat.googleapis.com/$discovery/rest?version=v1&labels=DEVELOPER_PREVIEW&key=API_KEY'
  );

  // The space to create the message in.
  const parent = 'spaces/SPACE_NAME';

  // Create the request
  const request = {
    parent: parent,
    requestBody: {
      text: 'Here is a card created on my behalf:',
      cardsV2: [{
        cardId: 'unique-card-id',
        card: {
          header: {
            title: 'Card Title',
            subtitle: 'Card Subtitle'
          },
          sections: [{
            widgets: [{
              textParagraph: {
                text: 'This card is attached to a user message.'
              }
            }]
          }]
        }
      }]
    }
  };

  // Call the API
  const response = await chat.spaces.messages.create(request);

  // Handle the response
  console.log(response.data);
}

main().catch(console.error);

Python

"""
This sample shows how to create a message with a card on behalf of a user.
"""
from google.oauth2 import service_account
from googleapiclient.discovery import build
import google.auth

def create_message_with_card():
    # Create a client
    scopes = ["https://www.googleapis.com/auth/chat.messages.create"]
    credentials, _ = google.auth.default(scopes=scopes)

    # Build the service endpoint for Chat API with Developer Preview labels.
    service = build(
        'chat',
        'v1',
        credentials=credentials,
        discoveryServiceUrl='https://chat.googleapis.com/$discovery/rest?version=v1&labels=DEVELOPER_PREVIEW&key=API_KEY'
    )

    # The space to create the message in.
    parent = "spaces/SPACE_NAME"

    # Create the request
    result = service.spaces().messages().create(
        parent=parent,
        body={
            'text': 'Here is a card created on my behalf:',
            'cardsV2': [{
                'cardId': 'unique-card-id',
                'card': {
                    'header': {
                        'title': 'Card Title',
                        'subtitle': 'Card Subtitle'
                    },
                    'sections': [{
                        'widgets': [{
                            'textParagraph': {
                                'text': 'This card is attached to a user message.'
                            }
                        }]
                    }]
                }
            }]
        }
    ).execute()

    print(result)

if __name__ == "__main__":
    create_message_with_card()

Java

/**
 * This sample shows how to create a message with a card on behalf of a user.
 */
import com.google.api.client.googleapis.javanet.GoogleNetHttpTransport;
import com.google.api.client.http.GenericUrl;
import com.google.api.client.http.HttpRequest;
import com.google.api.client.http.HttpRequestFactory;
import com.google.api.client.http.HttpTransport;
import com.google.api.client.http.json.JsonHttpContent;
import com.google.api.client.json.gson.GsonFactory;
import com.google.auth.http.HttpCredentialsAdapter;
import com.google.auth.oauth2.GoogleCredentials;
import java.util.Arrays;
import java.util.Collections;
import java.util.HashMap;
import java.util.Map;

public class CreateMessageWithCard {
  public static void main(String[] args) throws Exception {
    HttpTransport transport = GoogleNetHttpTransport.newTrustedTransport();
    GsonFactory jsonFactory = GsonFactory.getDefaultInstance();

    GoogleCredentials credentials = GoogleCredentials.getApplicationDefault()
        .createScoped(Arrays.asList("https://www.googleapis.com/auth/chat.messages.create"));
    HttpRequestFactory requestFactory = transport.createRequestFactory(new HttpCredentialsAdapter(credentials));

    String parent = "spaces/SPACE_NAME";
    GenericUrl url = new GenericUrl("https://chat.googleapis.com/v1/" + parent + "/messages");

    // Construct the message body
    Map<String, Object> message = new HashMap<>();
    message.put("text", "Here is a card created on my behalf:");

    Map<String, Object> header = new HashMap<>();
    header.put("title", "Card Title");
    header.put("subtitle", "Card Subtitle");

    Map<String, Object> textParagraph = new HashMap<>();
    textParagraph.put("text", "This card is attached to a user message.");

    Map<String, Object> widget = new HashMap<>();
    widget.put("textParagraph", textParagraph);

    Map<String, Object> section = new HashMap<>();
    section.put("widgets", Collections.singletonList(widget));

    Map<String, Object> card = new HashMap<>();
    card.put("header", header);
    card.put("sections", Collections.singletonList(section));

    Map<String, Object> cardWithId = new HashMap<>();
    cardWithId.put("cardId", "unique-card-id");
    cardWithId.put("card", card);

    message.put("cardsV2", Collections.singletonList(cardWithId));

    HttpRequest request = requestFactory.buildPostRequest(url, new JsonHttpContent(jsonFactory, message));
    System.out.println(request.execute().parseAsString());
  }
}

Google Apps Script

/**
 * This sample shows how to create a message with a card on behalf of a user.
 */
function createMessageWithCard() {
  const parent = 'spaces/SPACE_NAME';
  const url = `https://chat.googleapis.com/v1/${parent}/messages`;

  const message = {
    text: 'Here is a card created on my behalf:',
    cardsV2: [{
      cardId: 'unique-card-id',
      card: {
        header: {
          title: 'Card Title',
          subtitle: 'Card Subtitle'
        },
        sections: [{
          widgets: [{
            textParagraph: {
              text: 'This card is attached to a user message.'
            }
          }]
        }]
      }
    }]
  };

  const options = {
    method: 'post',
    headers: {
      Authorization: 'Bearer ' + ScriptApp.getOAuthToken()
    },
    contentType: 'application/json',
    payload: JSON.stringify(message),
    muteHttpExceptions: true
  };

  try {
    const response = UrlFetchApp.fetch(url, options);
    console.log(response.getContentText());
  } catch (err) {
    console.log('Failed to create message: ' + err.message);
  }
}

Asynchroniczne aktualizowanie kart

Po utworzeniu wiadomości z kartami możesz je aktualizować asynchronicznie za pomocą uwierzytelniania aplikacji. Dzięki temu aplikacja może odświeżać zawartość karty bez interakcji użytkownika. Tylko aplikacja do obsługi czatu, która dodała kartę do wiadomości użytkownika, może ją zastąpić. Jeśli użytkownik zmodyfikuje tekst wiadomości, karty należące do aplikacji zostaną usunięte i aplikacja nie będzie mogła ich już aktualizować.

Aby zaktualizować karty, wywołaj metodę replaceCards z tymi parametrami:

chat.botZakres autoryzacji.
name wiadomości do zaktualizowania.
Nowa lista cardsV2. Spowoduje to zastąpienie wszystkich istniejących kart w wiadomości. Jeśli podasz pustą listę, karty zostaną usunięte.

Ten przykład pokazuje, jak zaktualizować karty wiadomości:

Node.js

/**
 * This sample shows how to update cards on a message.
 */
const {google} = require('googleapis');
const {auth} = require('google-auth-library');

async function main() {
  // Create a client with app credentials
  const authClient = await auth.getClient({
    scopes: ['https://www.googleapis.com/auth/chat.bot']
  });
  google.options({auth: authClient});

  // Initialize the Chat API with Developer Preview labels
  const chat = await google.discoverAPI(
    'https://chat.googleapis.com/$discovery/rest?version=v1&labels=DEVELOPER_PREVIEW&key=API_KEY'
  );

  // The message to update.
  const messageName = 'spaces/SPACE_NAME/messages/MESSAGE_ID';

  // Create the request
  const request = {
    name: messageName,
    requestBody: {
      cardsV2: [{
        cardId: 'unique-card-id',
        card: {
          header: {
            title: 'Updated Card Title',
            subtitle: 'Updated Card Subtitle'
          },
          sections: [{
            widgets: [{
              textParagraph: {
                text: 'The card content has been updated asynchronously.'
              }
            }]
          }]
        }
      }]
    }
  };

  // Call the API
  await chat.spaces.messages.replaceCards(request);
  console.log('Cards updated.');
}

main().catch(console.error);

Python

"""
This sample shows how to update cards on a message.
"""
from google.oauth2 import service_account
from googleapiclient.discovery import build
import google.auth

def replace_message_cards():
    # Create a client with app credentials
    scopes = ["https://www.googleapis.com/auth/chat.bot"]
    credentials, _ = google.auth.default(scopes=scopes)

    # Build the service endpoint for Chat API with Developer Preview labels.
    service = build(
        'chat',
        'v1',
        credentials=credentials,
        discoveryServiceUrl='https://chat.googleapis.com/$discovery/rest?version=v1&labels=DEVELOPER_PREVIEW&key=API_KEY'
    )

    # The message to update.
    message_name = "spaces/SPACE_NAME/messages/MESSAGE_ID"

    # Create the request
    result = service.spaces().messages().replaceCards(
        name=message_name,
        body={
            'cardsV2': [{
                'cardId': 'unique-card-id',
                'card': {
                    'header': {
                        'title': 'Updated Card Title',
                        'subtitle': 'Updated Card Subtitle'
                    },
                    'sections': [{
                        'widgets': [{
                            'textParagraph': {
                                'text': 'The card content has been updated asynchronously.'
                            }
                        }]
                    }]
                }
            }]
        }
    ).execute()

    print("Cards updated.")

if __name__ == "__main__":
    replace_message_cards()

Java

/**
 * This sample shows how to update cards on a message.
 */
import com.google.api.client.googleapis.javanet.GoogleNetHttpTransport;
import com.google.api.client.http.GenericUrl;
import com.google.api.client.http.HttpRequest;
import com.google.api.client.http.HttpRequestFactory;
import com.google.api.client.http.HttpTransport;
import com.google.api.client.http.json.JsonHttpContent;
import com.google.api.client.json.gson.GsonFactory;
import com.google.auth.http.HttpCredentialsAdapter;
import com.google.auth.oauth2.GoogleCredentials;
import java.util.Arrays;
import java.util.Collections;
import java.util.HashMap;
import java.util.Map;

public class ReplaceMessageCards {
  public static void main(String[] args) throws Exception {
    HttpTransport transport = GoogleNetHttpTransport.newTrustedTransport();
    GsonFactory jsonFactory = GsonFactory.getDefaultInstance();

    GoogleCredentials credentials = GoogleCredentials.getApplicationDefault()
        .createScoped(Arrays.asList("https://www.googleapis.com/auth/chat.bot"));
    HttpRequestFactory requestFactory = transport.createRequestFactory(new HttpCredentialsAdapter(credentials));

    String messageName = "spaces/SPACE_NAME/messages/MESSAGE_ID";
    GenericUrl url = new GenericUrl("https://chat.googleapis.com/v1/" + messageName + ":replaceCards");

    // Construct the body
    Map<String, Object> header = new HashMap<>();
    header.put("title", "Updated Card Title");
    header.put("subtitle", "Updated Card Subtitle");

    Map<String, Object> textParagraph = new HashMap<>();
    textParagraph.put("text", "The card content has been updated asynchronously.");

    Map<String, Object> widget = new HashMap<>();
    widget.put("textParagraph", textParagraph);

    Map<String, Object> section = new HashMap<>();
    section.put("widgets", Collections.singletonList(widget));

    Map<String, Object> card = new HashMap<>();
    card.put("header", header);
    card.put("sections", Collections.singletonList(section));

    Map<String, Object> cardWithId = new HashMap<>();
    cardWithId.put("cardId", "unique-card-id");
    cardWithId.put("card", card);

    Map<String, Object> body = new HashMap<>();
    body.put("cardsV2", Collections.singletonList(cardWithId));

    HttpRequest request = requestFactory.buildPostRequest(url, new JsonHttpContent(jsonFactory, body));
    request.execute();
    System.out.println("Cards updated.");
  }
}

Google Apps Script

/**
 * This sample shows how to update cards on a message.
 */
function replaceMessageCards() {
  const messageName = 'spaces/SPACE_NAME/messages/MESSAGE_ID';
  const url = `https://chat.googleapis.com/v1/${messageName}:replaceCards`;

  const request = {
    cardsV2: [{
      cardId: 'unique-card-id',
      card: {
        header: {
          title: 'Updated Card Title',
          subtitle: 'Updated Card Subtitle'
        },
        sections: [{
          widgets: [{
            textParagraph: {
              text: 'The card content has been updated asynchronously.'
            }
          }]
        }]
      }
    }]
  };

  const options = {
    method: 'post',
    headers: {
      Authorization: 'Bearer ' + ScriptApp.getOAuthToken()
    },
    contentType: 'application/json',
    payload: JSON.stringify(request),
    muteHttpExceptions: true
  };

  try {
    const response = UrlFetchApp.fetch(url, options);
    console.log('Cards updated.');
  } catch (err) {
    console.log('Failed to update cards: ' + err.message);
  }
}

Ograniczenia

Podczas tworzenia wiadomości z kartami w imieniu użytkownika lub aktualizowania kart aplikacja do obsługi czatu musi być członkiem pokoju. Ten wymóg obowiązuje, gdy:
- Tworzenie wiadomości z kartami w imieniu użytkownika.
- Wymiana lub aktualizacja kart w wiadomości.
To wymaganie różni się od innych interfejsów API, które używają uwierzytelniania użytkownika i zwykle nie wymagają, aby aplikacja była członkiem pokoju.
Metoda replaceCards obsługuje wymianę i usuwanie kart. Podczas wymiany możesz dodać dodatkowe karty, ale nie możesz dodawać kart do wiadomości, które nie mają jeszcze kart.
Aplikacja Chat może zastępować tylko karty, które zostały dołączone do wiadomości przez tę aplikację, a nie karty dołączone przez inne aplikacje Chat.
Jeśli użytkownik zmodyfikuje tekst wiadomości, karty należące do aplikacji do obsługi czatu zostaną usunięte i nie będzie można ich już aktualizować.

Tworzenie i aktualizowanie interaktywnych kart Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

Wymagania wstępne

Node.js

Python

Java

Google Apps Script

Tworzenie klucza interfejsu API umożliwiającego dostęp do funkcji wersji przedpremierowej dla programistów

Tworzenie wiadomości z kartą w imieniu użytkownika

Node.js

Python

Java

Google Apps Script

Asynchroniczne aktualizowanie kart

Node.js

Python

Java

Google Apps Script

Ograniczenia

Powiązane artykuły

Tworzenie i aktualizowanie interaktywnych kart