חיפוש בהודעות

במאמר הזה מוסבר איך להשתמש ב-method ‏search במשאב Message של Google Chat API כדי לחפש הודעות שהמשתמש המאומת יכול לגשת אליהן.

באמצעות אימות משתמשים, אתם יכולים לחפש הודעות בכל השיחות שהמשתמש הצטרף אליהן, או בשיחה ספציפית. לדוגמה, אפשר לחפש הודעות שמכילות מילות מפתח ספציפיות, מזכירות את המשתמש, לא נקראו או כוללות קבצים מצורפים.

ב-Chat API, הודעה ב-Chat מיוצגת על ידי משאב Message. משתמשי Chat יכולים לשלוח רק הודעות שמכילות טקסט, אבל אפליקציות ל-Chat יכולות להשתמש בהרבה תכונות אחרות של הודעות, כולל הצגת ממשקי משתמש סטטיים או אינטראקטיביים, איסוף מידע מהמשתמשים ושליחת הודעות באופן פרטי. מידע נוסף על תכונות ההודעות שזמינות ב-Chat API מופיע בסקירה הכללית על הודעות ב-Google Chat.

דרישות מוקדמות

Node.js

Python

Java

Apps Script

חיפוש הודעות

כדי לחפש הודעות עם אימות משתמש, צריך להעביר את הפרטים הבאים בבקשה:

  • מציינים את היקף ההרשאות של chat.messages.readonly או chat.messages.

  • מבצעים קריאה ל-method‏ SearchMessages.

  • מגדירים את parent לערך spaces/- כדי לחפש בכל המרחבים שהמשתמש חבר בהם. שימוש בכל ערך אחר יוביל לשגיאה.

  • בשדה filter, מציינים מחרוזת של שאילתת חיפוש. השאילתה יכולה לכלול מילות מפתח ומסננים.

בדוגמת הקוד הבאה מחפשים הודעות שלא נקראו שמכילות את מילת המפתח tasks:

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

Java

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

Apps Script

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