ایجاد و به‌روزرسانی کارت‌های تعاملی

این راهنما نحوه استفاده از API چت گوگل برای ایجاد پیام‌هایی که حاوی کارت‌های تعاملی از طرف کاربران هستند و نحوه به‌روزرسانی ناهمگام آن کارت‌ها را توضیح می‌دهد.

ایجاد و به‌روزرسانی کارت‌ها زمانی مفید است که بخواهید موارد زیر را انجام دهید:

  • کارتی را که نمایانگر یک وظیفه یا منبع خارجی است، از طرف یک کاربر ارسال کنید.
  • وضعیت کارت (مثلاً «در حال انجام» به «تکمیل‌شده») را بر اساس رویدادهای خارجی، بدون انتظار برای تعامل کاربر، به‌روزرسانی کنید.
  • محتوای یک کارت را در پیام کاربر، مانند پیش‌نمایش لینک، به‌روزرسانی کنید.

خارج از برنامه پیش‌نمایش توسعه‌دهندگان ، پیام‌های ایجاد شده با احراز هویت کاربر فقط می‌توانند حاوی متن باشند.

پیش‌نیازها

نود جی اس

پایتون

جاوا

اسکریپت برنامه‌ها

برای دسترسی به ویژگی‌های پیش‌نمایش توسعه‌دهندگان، یک کلید API ایجاد کنید

برای فراخوانی متد API پیش‌نمایش توسعه‌دهنده، باید از یک نسخه پیش‌نمایش توسعه‌دهنده غیرعمومی از سند کشف API استفاده کنید. برای تأیید اعتبار درخواست، باید یک کلید API ارسال کنید.

برای ایجاد کلید API، پروژه Google Cloud برنامه خود را باز کنید و موارد زیر را انجام دهید:

  1. در کنسول گوگل کلود، به Menu > APIs & Services > Credentials بروید.

    به اعتبارنامه‌ها بروید

  2. روی ایجاد اعتبارنامه > کلید API کلیک کنید.
  3. کلید API جدید شما نمایش داده می‌شود.
    • برای کپی کردن کلید API خود جهت استفاده در کد برنامه، روی گزینه کپی کردن کلیک کنید. کلید API را می‌توانید در بخش «کلیدهای API» در اعتبارنامه‌های پروژه خود نیز پیدا کنید.
    • برای جلوگیری از استفاده غیرمجاز، توصیه می‌کنیم مکان و نوع APIهایی که کلید API می‌تواند استفاده شود را محدود کنید. برای جزئیات بیشتر، به افزودن محدودیت‌های API مراجعه کنید.

ایجاد پیام کارت از طرف کاربر

برای ایجاد پیام با کارت‌ها از طرف یک کاربر، از احراز هویت کاربر استفاده کنید.

برای ایجاد پیام، موارد زیر را در درخواست خود مشخص کنید:

  • دامنه‌ی مجوز chat.messages.create یا chat.messages .
  • فیلد cardsV2 در منبع Message ، حاوی داده‌های کارت.
  • cardId مربوط به هر کارت، که برای به‌روزرسانی‌های ناهمزمان مورد نیاز است.

مثال زیر نحوه ایجاد یک پیام با کارت از طرف یک کاربر را نشان می‌دهد:

نود جی اس 

/**
 * 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);

پایتون 

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

جاوا 

/**
 * 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());
  }
}

اسکریپت برنامه‌ها 

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

کارت‌ها را به صورت غیرهمزمان به‌روزرسانی کنید

پس از ایجاد پیام با کارت‌ها، می‌توانید کارت‌ها را به صورت غیرهمزمان با استفاده از احراز هویت برنامه به‌روزرسانی کنید. این به برنامه شما اجازه می‌دهد محتوای کارت را بدون نیاز به تعامل کاربر به‌روزرسانی کند. فقط برنامه چتی که کارت را به پیام کاربر اضافه کرده است می‌تواند آن را جایگزین کند. اگر کاربر متن پیام را ویرایش کند، کارت‌های متعلق به برنامه حذف می‌شوند و برنامه شما دیگر نمی‌تواند آنها را به‌روزرسانی کند.

برای به‌روزرسانی کارت‌ها، متد replaceCards را با کد زیر فراخوانی کنید:

  • دامنه‌ی مجوز chat.bot .
  • name پیامی که باید به‌روزرسانی شود.
  • لیست جدید cardsV2 . این لیست جایگزین تمام کارت‌های موجود در پیام می‌شود. اگر لیست خالی ارائه دهید، کارت‌ها حذف می‌شوند.

مثال زیر نحوه به‌روزرسانی کارت‌های یک پیام را نشان می‌دهد:

نود جی اس 

/**
 * 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);

پایتون 

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

جاوا 

/**
 * 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.");
  }
}

اسکریپت برنامه‌ها 

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

محدودیت‌ها

  • هنگام ایجاد پیام با کارت‌ها از طرف یک کاربر یا به‌روزرسانی کارت‌ها، برنامه چت باید عضوی از فضا باشد. این الزام در موارد زیر اعمال می‌شود:

    این الزام با سایر APIهایی که از احراز هویت کاربر استفاده می‌کنند، متفاوت است، که معمولاً نیازی به عضویت برنامه در این فضا ندارند.

  • متد replaceCards از جایگزینی و حذف کارت پشتیبانی می‌کند و می‌توانید هنگام جایگزینی کارت‌های اضافی، آنها را اضافه کنید، اما نمی‌توانید کارت‌ها را به پیامی که از قبل کارت ندارد، اضافه کنید.

  • برنامه چت فقط می‌تواند کارت‌هایی را که به یک پیام پیوست شده‌اند، جایگزین کند، نه کارت‌هایی که سایر برنامه‌های چت پیوست کرده‌اند.

  • اگر کاربری متن پیام را ویرایش کند، کارت‌های متعلق به برنامه چت حذف می‌شوند و دیگر نمی‌توانید آنها را به‌روزرسانی کنید.