بحث في الرسائل

يوضّح هذا المستند كيفية استخدام طريقة search في المورد Message ضِمن Google Chat API للبحث عن الرسائل التي يمكن للمستخدم الذي تمت مصادقته الوصول إليها.

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

في Chat API، يتم تمثيل رسالة Chat من خلال المورد Message. في حين أنّه بإمكان مستخدمي Chat إرسال رسائل تتضمّن نصًا فقط، يمكن لتطبيقات Chat استخدام العديد من ميزات المراسلة الأخرى، بما في ذلك عرض واجهات مستخدم ثابتة أو تفاعلية، وجمع المعلومات من المستخدمين، وإرسال الرسائل بشكل خاص. لمزيد من المعلومات حول ميزات المراسلة المتاحة لواجهة برمجة تطبيقات Chat، يُرجى الاطّلاع على نظرة عامة على رسائل Google Chat.

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

Node.js

Python

جافا

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

البحث عن الرسائل

للبحث عن الرسائل التي تتضمّن مصادقة المستخدم، مرِّر ما يلي في طلبك:

  • حدِّد نطاق تفويض chat.messages.readonly أو chat.messages.

  • استدعِ طريقة SearchMessages.

  • اضبط parent على spaces/- للبحث في جميع المساحات التي يكون المستخدم عضوًا فيها. سيؤدي استخدام أي قيمة أخرى إلى حدوث خطأ.

  • في الحقل filter، حدِّد سلسلة طلب بحث. يمكن أن يتضمّن طلب البحث كلمات رئيسية وفلاتر.

تبحث عينة التعليمات البرمجية التالية عن الرسائل غير المقروءة التي تحتوي على الكلمة الرئيسية "مهام":

Node.js

/**
 * Searches for messages in Google Chat.
 * @param {string} filter The search query.
 */
async function searchMessages(filter) {
  const {ChatServiceClient} = require('@google-apps/chat').v1;

  // Instantiates a client
  const chatClient = new ChatServiceClient();

  // See https://github.com/googleworkspace/node-samples/blob/main/chat/client-libraries/cloud/authentication-utils.js
  // for an example of how to authenticate the request.

  // Construct request
  const request = {
    // Parent must be "spaces/-" to search across all spaces.
    parent: 'spaces/-',
    filter: filter,
  };

  // Run request
  const iterable = await chatClient.searchMessagesAsync(request);
  for await (const response of iterable) {
    console.log(response);
  }
}

searchMessages('tasks AND is_unread()');

Python

from google.apps import chat_v1

def search_messages(filter_str: str):
    """
    Searches for messages in Google Chat.
    Args:
        filter_str: The search query.
    """
    # Create a client
    client = chat_v1.ChatServiceClient()

    # See https://github.com/googleworkspace/python-samples/blob/main/chat/client-libraries/cloud/authentication_utils.py
    # for an example of how to authenticate the request.

    # Initialize request argument
    request = chat_v1.SearchMessagesRequest(
        # Parent must be "spaces/-" to search across all spaces.
        parent="spaces/-",
        filter=filter_str
    )

    # Make the request
    page_result = client.search_messages(request=request)

    # Handle the response
    for response in page_result:
        print(response)

search_messages('tasks AND is_unread()')

جافا

import com.google.chat.v1.ChatServiceClient;
import com.google.chat.v1.SearchMessageResult;
import com.google.chat.v1.SearchMessagesRequest;

public class SearchMessages {
  public static void main(String[] args) throws Exception {
    searchMessages("tasks AND is_unread()");
  }

  /**
   * Searches for messages in Google Chat.
   *
   * @param filter The search query.
   */
  public static void searchMessages(String filter) throws Exception {
    // See https://github.com/googleworkspace/java-samples/blob/main/chat/client-libraries/cloud/src/main/java/com/google/workspace/api/chat/samples/AuthenticationUtils.java
    // for an example of how to authenticate the request.
    try (ChatServiceClient chatServiceClient = ChatServiceClient.create()) {
      SearchMessagesRequest request =
          SearchMessagesRequest.newBuilder()
              .setParent("spaces/-")
              .setFilter(filter)
              .build();
      for (SearchMessageResult result : chatServiceClient.searchMessages(request).iterateAll()) {
        System.out.println(result.getMessage().getText());
      }
    }
  }
}

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

javascript /** * Searches for messages in Google Chat. */ function searchMessages() { const filter = 'tasks AND is_unread()'; const url = 'https://chat.googleapis.com/v1/spaces/-/messages:search'; const request_payload = { filter: filter }; try { const response = UrlFetchApp.fetch(url, { method: 'post', headers: { 'Authorization': 'Bearer ' + ScriptApp.getOAuthToken() }, contentType: 'application/json', payload: JSON.stringify(request_payload) }); if (response.results) { for (const result of response.results) { console.log('Message text: %s', result.message.text); } } else { console.log('No messages found.'); } } catch (err) { console.log('Failed to search messages with error: %s', err.message); } }

استخدام فلاتر البحث وعوامل التشغيل

يمكنك تحسين نتائج البحث باستخدام الكلمات الرئيسية والحقول والدوال في حقل filter. لمزيد من المعلومات، يُرجى الاطّلاع على SearchMessagesRequest.

للبحث عن الرسائل التي تحتوي على نص معيّن، أدخِل الكلمات الرئيسية. على سبيل المثال، للبحث عن البلاغات المعلقة، استخدِم pending reports.

البحث حسب الحقل

يمكنك فلترة النتائج حسب حقول الرسائل أو المساحات المحدّدة. على سبيل المثال:

  • create_time: فلترة الرسائل حسب وقت إنشائها مثال: create_time > "2023-01-01T00:00:00Z"
  • sender.name: فلترة حسب اسم مورد المُرسِل مثال: sender.name = "users/1234567890"
  • space.name: لحصر البحث على مساحة معيّنة مثال: space.name = "spaces/ABCDEFGH"
  • space.display_name: لفلترة المساحات استنادًا إلى تطابق جزئي مع الاسم المعروض. تقتصر النتائج على أفضل خمس مساحات مطابقة. مثال: space.display_name:Project
  • attachment: للتحقّق من وجود مرفقات مثال: attachment:*
  • annotations.user_mentions.user.name: الفلترة حسب الإشارات مثال: annotations.user_mentions.user.name:"users/me"

البحث باستخدام الدوال

تتوفّر الفلترة المتقدّمة من خلال الوظائف التالية:

  • has_link: تعرض هذه السمة الرسائل التي تحتوي على رابط تشعّبي واحد على الأقل.
  • is_unread: تعرض هذه السمة الرسائل التي لم يقرأها المستخدم.

في الحقول المختلفة، لا يُسمح إلا بعوامل التشغيل AND. على سبيل المثال: sender.name = "users/me" AND is_unread().