Ta strona została przetłumaczona przez Cloud Translation API.

Odpowiadanie na polecenia z ukośnikiem w Google Chat

Przedpremierowa wersja dla deweloperów: dostępna w ramach programu Google Workspace dla deweloperów, który zapewnia wcześniejszy dostęp do niektórych funkcji.

Na tej stronie znajdziesz informacje o tym, jak skonfigurować aplikację Google Chat, aby reagowała na polecenia z użyciem znaku ukośnika.

W Google Chat dodatki są widoczne dla użytkowników jako aplikacje Google Chat. Więcej informacji znajdziesz w artykule Więcej informacji o rozszerzaniu Google Chat.

Polecenie po ukośniku to popularny sposób uruchamiania aplikacji Google Chat i nawiązywania interakcji z nią. Polecenia po ukośniku pomagają też użytkownikom odkrywać i korzystać z kluczowych funkcji aplikacji. Aby zdecydować, czy warto skonfigurować polecenia po ukośniku, i poznać sposób projektowania interakcji z użytkownikiem, zapoznaj się z dokumentacją interfejsu API Google Chat Definiowanie wszystkich ścieżek użytkownika.

Jak użytkownicy korzystają z poleceń po ukośniku

Aby użyć polecenia po ukośniku, użytkownicy wpisują ukośnik (/), a następnie krótkie polecenie tekstowe, takie jak /about, aby uzyskać informacje o aplikacji Chat. Użytkownicy mogą odkryć dostępne polecenia po ukośniku, wpisując ukośnik w Google Chat. Spowoduje to wyświetlenie okna z listą dostępnych poleceń w aplikacji Chat:

Ilustracja 1. Okno, które pojawia się, gdy użytkownicy wpisują znak ukośnika w Google Chat.

Gdy użytkownik wyśle wiadomość zawierającą polecenie po ukośniku, będzie ona widoczna tylko dla niego i aplikacji Google Chat. Jeśli aplikacja Google Chat została dodana do pokoju z wieloma osobami, możesz odpowiedzieć na polecenie po ukośniku prywatnie, aby zachować prywatność interakcji między użytkownikiem a aplikacją Google Chat.

Na przykład, aby dowiedzieć się więcej o aplikacji Google Chat znalezionej w pokoju, użytkownicy mogą użyć poleceń takich jak /about lub /help. Aby uniknąć powiadamiania wszystkich innych osób w przestrzeni, aplikacja Google Chat może odpowiadać prywatnie, podając informacje o tym, jak korzystać z aplikacji Google Chat i uzyskać pomoc.

Wymagania wstępne

Node.js

dodatek do Google Workspace, który rozszerza Google Chat; Aby go utworzyć, wykonaj czynności opisane w krótkim przewodniku po HTTP.

Google Apps Script

dodatek do Google Workspace, który rozszerza Google Chat; Aby utworzyć taki skrypt, zapoznaj się z krótkim przewodnikiem po Apps Script.

Konfigurowanie polecenia po ukośniku

Z tej sekcji dowiesz się, jak skonfigurować polecenie /:

Utwórz nazwę dla polecenia po ukośniku.
Skonfiguruj polecenie po ukośniku w interfejsie Google Chat API.

Nazwij polecenie po ukośniku

Nazwa polecenia po ukośniku to to, co użytkownicy wpisują w wiadomości w Google Chat, aby wywołać tę aplikację. Pod nazwą pojawia się też krótki opis, który informuje użytkowników, jak używać polecenia:

Rysunek 2. Nazwa i opis polecenia po ukośniku.

Wybierając nazwę i opis polecenia po ukośniku, weź pod uwagę te rekomendacje:

Aby nadać nazwę poleceniu po ukośniku:
- Używaj krótkich, opisowych i użytecznych słów lub wyrażeń, aby polecenia były jasne i proste dla użytkownika. Na przykład zamiast /createAReminder użyj /remindMe.
- Jeśli polecenie składa się z więcej niż jednego słowa, ułatwij użytkownikom jego odczytanie, używając małych liter w przypadku pierwszego słowa, a potem wielkich liter w przypadku pierwszych liter pozostałych słów. Na przykład zamiast /updatecontact użyj /updateContact.
- Zastanów się, czy użyć niepowtarzalnej czy wspólnej nazwy polecenia. Jeśli polecenie opisuje typowe działanie lub funkcję, możesz użyć powszechnej nazwy, którą użytkownicy rozpoznają i oczekują, np. /settings lub /feedback. W przeciwnym razie używaj unikalnych nazw poleceń, ponieważ jeśli nazwa Twojego polecenia jest taka sama jak w innych aplikacjach do czatu, użytkownik musi przefiltrować podobne polecenia, aby znaleźć i użyć Twojego.
Aby opisać polecenie po ukośniku:
- Opis powinien być krótki i jasny, aby użytkownicy wiedzieli, czego się spodziewać, gdy wywołają polecenie.
- Poinformuj użytkowników, czy w przypadku polecenia obowiązują jakieś wymagania dotyczące formatowania. Jeśli na przykład utworzysz polecenie /remindMe, które wymaga argumentu tekst, ustaw opis na coś takiego jak Remind me to do [something] at [time].
- Poinformuj użytkowników, czy aplikacja Google Chat ma odpowiadać wszystkim w pokoju, czy tylko użytkownikowi, który wywołał polecenie. Na przykład w przypadku polecenia z ukośnikiem /about możesz je opisać jako Learn about this app (Only visible to you).

Konfigurowanie polecenia po ukośniku w Google Chat API

Aby utworzyć polecenie z ukośnikiem, musisz podać informacje o nim w konfiguracji interfejsu Google Chat API w aplikacji Google Chat.

Aby skonfigurować polecenie z ukośnikiem w Google Chat API, wykonaj te czynności:

W konsoli Google Cloud kliknij Menu > Interfejsy API i usługi > Włączone interfejsy API i usługi > Interfejs Google Chat API

Otwórz stronę interfejsu Google Chat API
Kliknij Konfiguracja.
W sekcji Ustawienia zaawansowane kliknij Aktywatory i sprawdź, czy pole MESSAGE zawiera odpowiedni aktywator, np. punkt końcowy HTTP lub funkcję Apps Script. W następującej sekcji musisz użyć tego skrótu, aby odpowiedzieć na polecenie.
W sekcji Polecenia po ukośniku kliknij Dodaj polecenie po ukośniku.
Wpisz nazwę, identyfikator i opis polecenia:
1. Nazwa: wyświetlana nazwa polecenia i tekst, który użytkownicy wpisują, aby wywołać aplikację. Musi zaczynać się ukośnikiem, zawierać tylko tekst i mieć maksymalnie 50 znaków.
2. Opis: tekst opisujący sposób użycia i sformatowania polecenia. Opis może mieć maksymalnie 50 znaków.
3. Identyfikator polecenia: liczba z zakresu od 1 do 1000, której używa aplikacja Google Chat do rozpoznawania polecenia po ukośniku i zwracania odpowiedzi.
Opcjonalnie: jeśli chcesz, aby aplikacja Google Chat odpowiadała na komendę za pomocą okna dialogowego, zaznacz pole wyboru Otwórz okno dialogowe.
Kliknij Zapisz.

Polecenie po ukośniku zostało skonfigurowane w aplikacji Google Chat.

Odpowiedź na polecenie po ukośniku

Gdy użytkownicy tworzą wiadomość w Google Chat, Twoja aplikacja Google Chat otrzymuje obiekt zdarzenia zawierający informacje o wiadomości. Obiekt event zawiera ładunek z informacjami o poleceniu użytym w wiadomości (w tym o identyfikatorze polecenia), aby umożliwić zwrócenie odpowiedniej odpowiedzi.

Aby odpowiedzieć na polecenie po ukośniku, musisz zaimplementować wyzwalacz wiadomości, aby aplikacja Google Chat mogła obsługiwać obiekty zdarzeń zawierające metadane poleceń po ukośniku.

Aplikacja Google Chat odpowiada prywatnie na komendę /help, aby wyjaśnić, jak uzyskać pomoc.

Poniższy kod pokazuje przykład aplikacji Google Chat, która odpowiada na polecenie /about za pomocą wiadomości tekstowej. Aby odpowiadać na polecenia po ukośniku, aplikacja do obsługi czatu obsługuje obiekty zdarzeń z wyzwalacza Wiadomość. Gdy ładunek obiektu zdarzenia zawiera znak slash (/) i identyfikator polecenia, aplikacja do czatu zwraca działanie DataActions z obiektem createMessageAction:

Node.js

// The ID of the slash command "/about".
// It's not enabled by default, set to the actual ID to enable it. You must
// use the same ID as set in the Google Chat API configuration.
const ABOUT_COMMAND_ID = 0;

/**
 * Google Cloud Function that responds to messages sent from a
 * Google Chat space.
 *
 * @param {Object} req Request sent from Google Chat space
 * @param {Object} res Response to send back
 */
exports.avatarApp = function avatarApp(req, res) {
    if (req.method === 'GET' || !req.body.chat) {
        return res.send('Hello! This function is meant to be used ' +
            'in a Google Chat Space.');
    }

    // Stores the Google Chat event as a variable.
    const chatMessage = req.body.chat.messagePayload.message;

    if (chatMessage.slashCommand) {
        // Executes the slash command logic based on its ID.
        // Slash command IDs are set in the Google Chat API configuration.
        switch (chatMessage.slashCommand.commandId) {
            case ABOUT_COMMAND_ID:
                return res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
                    text: 'The Avatar app replies to Google Chat messages.'
                }}}}});
        }
    }

    // Replies with the sender's avatar in a card otherwise.
    const displayName = chatMessage.sender.displayName;
    const avatarUrl = chatMessage.sender.avatarUrl;
    res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
        text: 'Here\'s your avatar',
        cardsV2: [{
            cardId: 'avatarCard',
            card: {
                name: 'Avatar Card',
                header: {
                    title: `Hello ${displayName}!`,
                },
                sections: [{
                    widgets: [{
                        textParagraph: { text: 'Your avatar picture: ' }
                    }, {
                        image: { imageUrl: avatarUrl }
                    }]
                }]
            }
        }]
    }}}}});
};

Google Apps Script

// The ID of the slash command "/about".
// It's not enabled by default, set to the actual ID to enable it. You must
// use the same ID as set in the Google Chat API configuration.
const ABOUT_COMMAND_ID = 0;

/**
 * Responds to a MESSAGE event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onMessage(event) {
    // Stores the Google Chat event as a variable.
    const chatMessage = event.chat.messagePayload.message;

    if (chatMessage.slashCommand) {
        // Executes the slash command logic based on its ID.
        // Slash command IDs are set in the Google Chat API configuration.
        switch (chatMessage.slashCommand.commandId) {
            case ABOUT_COMMAND_ID:
                return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
                    text: 'The Avatar app replies to Google Chat messages.'
                }}}}};
        }
    }

    // Replies with the sender's avatar in a card otherwise.
    const displayName = chatMessage.sender.displayName;
    const avatarUrl = chatMessage.sender.avatarUrl;
    return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
        text: 'Here\'s your avatar',
        cardsV2: [{
            cardId: 'avatarCard',
            card: {
                name: 'Avatar Card',
                header: {
                    title: `Hello ${displayName}!`,
                },
                sections: [{
                    widgets: [{
                        textParagraph: { text: 'Your avatar picture: ' }
                    }, {
                        image: { imageUrl: avatarUrl }
                    }]
                }]
            }
        }]
    }}}}};
}

Aby użyć tego przykładowego kodu, zastąp ABOUT_COMMAND_ID identyfikatorem polecenia, który został określony podczas konfigurowania ukośnika w Google Chat API.