إنشاء البطاقات التفاعلية وتعديلها

يوضّح هذا الدليل كيفية استخدام Google Chat API لإنشاء رسائل تتضمّن بطاقات تفاعلية نيابةً عن المستخدمين، وإرفاق بطاقات بالرسائل الحالية، وتعديل هذه البطاقات بشكل غير متزامن.

يكون إنشاء البطاقات وتعديلها مفيدًا عندما تريد إجراء ما يلي:

  • نشر بطاقة تمثّل مهمة أو مرجعًا خارجيًا نيابةً عن مستخدم
  • أرفِق بطاقة برسالة مستخدم حالية لتوفير سياق أو سير عمل تفاعلي.
  • تعديل حالة البطاقة (مثلاً، من "قيد التقدّم" إلى "مكتملة") استنادًا إلى أحداث خارجية، بدون انتظار تفاعل المستخدم
  • تعديل محتوى بطاقة في رسالة مستخدم، مثل معاينة رابط

المتطلبات الأساسية

Node.js

Python

جافا

برمجة التطبيقات

إنشاء رسالة بطاقة نيابةً عن مستخدم

لإنشاء رسالة تتضمّن بطاقات نيابةً عن مستخدم، استخدِم مصادقة المستخدم.

لإنشاء الرسالة، حدِّد ما يلي في طلبك:

  • نطاق الإذن chat.messages.create أو chat.messages
  • حقل cardsV2 في مرجع Message الذي يحتوي على بيانات البطاقة
  • cardId لكل بطاقة، وهو مطلوب لإجراء التعديلات غير المتزامنة

يوضّح المثال التالي كيفية إنشاء رسالة تتضمّن بطاقة نيابةً عن مستخدم:

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
  const chat = google.chat({version: 'v1'});

  // 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.
    service = build('chat', 'v1', credentials=credentials)

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

إرفاق بطاقات برسالة حالية نيابةً عن مستخدم

لإرفاق بطاقات برسالة حالية نيابةً عن مستخدم، استدعِ طريقة patch باستخدام مصادقة المستخدم.

لإرفاق بطاقات برسالة، حدِّد ما يلي في طلبك:

  • نطاق التفويض chat.messages
  • name الرسالة المطلوب تعديلها، بالتنسيق spaces/{space}/messages/{message}
  • تم ضبط updateMask على cards_v2. عند تعديل رسالة تتضمّن مصادقة المستخدم، يجب أن يكون cards_v2 هو الحقل الوحيد في قناع التعديل. لا يمكنك تعديل الرسالتَين text وcards_v2 في الطلب نفسه.
  • حقل cardsV2 في مرجع Message الذي يحتوي على بيانات البطاقة
  • تمثّل cardId كل بطاقة، وهو أمر ضروري لإجراء التعديلات غير المتزامنة اللاحقة.

يوضّح المثال التالي كيفية إرفاق بطاقة برسالة حالية نيابةً عن مستخدم:

Node.js

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

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

  // Initialize the Chat API
  const chat = google.chat({version: 'v1'});

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

  // Create the request
  const request = {
    name: messageName,
    updateMask: 'cards_v2',
    requestBody: {
      cardsV2: [{
        cardId: 'unique-card-id',
        card: {
          header: {
            title: 'Card Title',
            subtitle: 'Card Subtitle'
          },
          sections: [{
            widgets: [{
              textParagraph: {
                text: 'This card was attached to an existing user message.'
              }
            }]
          }]
        }
      }]
    }
  };

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

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

main().catch(console.error);

Python

"""
This sample shows how to attach a card to an existing message on behalf of a user.
"""
from googleapiclient.discovery import build
import google.auth

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

    # Build the service endpoint for Chat API.
    service = build('chat', 'v1', credentials=credentials)

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

    # Create the request
    result = service.spaces().messages().patch(
        name=message_name,
        updateMask="cards_v2",
        body={
            'cardsV2': [{
                'cardId': 'unique-card-id',
                'card': {
                    'header': {
                        'title': 'Card Title',
                        'subtitle': 'Card Subtitle'
                    },
                    'sections': [{
                        'widgets': [{
                            'textParagraph': {
                                'text': 'This card was attached to an existing user message.'
                            }
                        }]
                    }]
                }
            }]
        }
    ).execute()

    print(result)

if __name__ == "__main__":
    attach_card_to_message()

جافا

/**
 * This sample shows how to attach a card to an existing message 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 AttachCardToMessage {
  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"));
    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 + "?updateMask=cards_v2");

    // Construct the card body
    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 was attached to an existing 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);

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

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

برمجة التطبيقات

/**
 * This sample shows how to attach a card to an existing message on behalf of a user.
 */
function attachCardToMessage() {
  const messageName = 'spaces/SPACE_NAME/messages/MESSAGE_ID';
  const url = `https://chat.googleapis.com/v1/${messageName}?updateMask=cards_v2`;

  const message = {
    cardsV2: [{
      cardId: 'unique-card-id',
      card: {
        header: {
          title: 'Card Title',
          subtitle: 'Card Subtitle'
        },
        sections: [{
          widgets: [{
            textParagraph: {
              text: 'This card was attached to an existing user message.'
            }
          }]
        }]
      }
    }]
  };

  const options = {
    method: 'patch',
    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 attach card: ' + err.message);
  }
}

تعديل البطاقات بشكل غير متزامن

بعد إنشاء رسالة تتضمّن بطاقات أو إرفاق بطاقات برسالة حالية، يمكنك تعديل البطاقات بشكل غير متزامن باستخدام مصادقة التطبيق. يتيح ذلك لتطبيقك إعادة تحميل محتوى البطاقة بدون الحاجة إلى تفاعل المستخدم. لا يمكن استبدال البطاقة إلا من خلال تطبيق Chat الذي أضافها إلى رسالة المستخدم. إذا عدّل المستخدم نص الرسالة، ستتم إزالة البطاقات التي يملكها التطبيق، ولن يتمكّن تطبيقك من تعديلها بعد ذلك.

عند تعديل البطاقات بشكل غير متزامن، يعرض Google Chat مؤشر تم التعديل بجانب معلومات تحديد المصدر الخاصة بالبطاقة لإعلام المستخدمين بأنّه تم تعديل محتوى البطاقة بشكل مستقل عن الرسالة.

لتعديل البطاقات، استخدِم طريقة replaceCards مع ما يلي:

  • نطاق التفويض chat.bot
  • name الرسالة المطلوب تعديلها
  • قائمة cardsV2 الجديدة يؤدي ذلك إلى استبدال جميع البطاقات الحالية في الرسالة. إذا قدّمت قائمة فارغة، ستتم إزالة البطاقات. في حال إزالة جميع البطاقات، لن تتمكّن من استخدام replaceCards لإضافتها مرة أخرى، بل عليك استخدام UpdateMessage مع مصادقة المستخدم لإرفاق بطاقات جديدة.

يوضّح المثال التالي كيفية تعديل بطاقات الرسالة:

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
  const chat = google.chat({version: 'v1'});

  // 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.
    service = build('chat', 'v1', credentials=credentials)

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

القيود

  • عند إنشاء رسائل تتضمّن بطاقات نيابةً عن مستخدم أو تعديل البطاقات، يجب أن يكون تطبيق Chat عضوًا في المساحة. ينطبق هذا الشرط في الحالات التالية:

    يختلف هذا الشرط عن واجهات برمجة التطبيقات الأخرى التي تستخدم مصادقة المستخدم، والتي لا تتطلّب عادةً أن يكون التطبيق عضوًا في مساحة العمل.

  • عند تعديل رسالة تتضمّن مصادقة المستخدم، إذا تم تحديد cards_v2 في updateMask، لا يمكن تعديل أي حقول أخرى (مثل text) في الطلب نفسه.

  • تتيح طريقة replaceCards استبدال البطاقات وإزالتها، ويمكنك إضافة بطاقات إضافية أثناء استبدالها، ولكن لا يمكنك إضافة بطاقات إلى رسالة لا تتضمّن بطاقات. لإرفاق بطاقات برسالة لا تتضمّن بطاقات، استخدِم UpdateMessage مع مصادقة المستخدم.

  • تحديد مصدر البطاقة وملكيتها:

    • يتم تحديد مصدر البطاقات المرفقة برسالة مستخدم على أنّها من تطبيق Chat الذي أرفقها، ويتم تحديد مالكها على أنّه تطبيق Chat، كما هو موضّح في الحقل CardWithId.owner المخصّص للإخراج فقط.
    • يمكن لتطبيق Chat استبدال البطاقات التي أرفقها برسالة فقط، وليس البطاقات التي أرفقتها تطبيقات Chat الأخرى.

  • إذا عدّل المستخدم نص الرسالة، ستتم إزالة البطاقات التي يملكها تطبيق Chat، ولن تتمكّن من تعديلها بعد ذلك.