חיפוש מרחבים

במדריך הזה מוסבר איך להשתמש בשיטה search() במשאב Space של Google Chat API כדי לחפש מרחבים משותפים עם שם בארגון Google Workspace.

Spaceמשאב מייצג מקום שבו אנשים ואפליקציות ל-Chat יכולים לשלוח הודעות, לשתף קבצים ולשתף פעולה. יש כמה סוגים של מרחבים:

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

אדמינים ב-Google Workspace שרוצים לחפש בכל המרחבים בארגון, כולל מרחבים פרטיים שהם לא הצטרפו אליהם, יכולים לעיין במאמר חיפוש מרחבים וניהול שלהם כאדמינים ב-Google Workspace כדי להשתמש ב-API עם הרשאות אדמין (useAdminAccess=true).

כשמחפשים מרחבים עם אימות משתמשים בלי הרשאות אדמין, השיטה מחפשת מרחבים עם שמות (spaceType מתוך SPACE) שהמשתמש המאומת יכול לגשת אליהם, כמו מרחבים שהוא חבר בהם, בארגון שלו.

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

Node.js

Python

Java

Apps Script

חיפוש מרחבים עם אימות משתמשים

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

  • באימות משתמשים, מציינים את היקף ההרשאה chat.spaces.readonly או chat.spaces.
  • מבצעים קריאה ל-search() במשאב Space.
  • מגדירים את useAdminAccess לערך false (או משמיטים את הפרמטר).
  • מציינים את הפרמטרים של החיפוש query כדי לסנן את התוצאות:
    • ‫spaceType = "SPACE" – מאפיין חובה אם מציינים את מאפיין query והערך הנתמך היחיד הוא SPACE.
    • ‫displayName – סינון לפי שם התצוגה של המרחב באמצעות האופרטור HAS (:). לדוגמה, displayName:"Project". הטקסט שרוצים להתאים עובר טוקניזציה, וכל טוקן עובר התאמה לקידומת באופן לא תלוי-רישיות ועצמאי כמחרוזת משנה בכל מקום ב-displayName. הערה: אם הערך של useAdminAccess הוא false, צריך לציין את displayName בשאילתה כדי לקבל תוצאות משמעותיות. אחרת, הפונקציה מחזירה תגובה ריקה.
    • ‫externalUserAllowed – אפשר לסנן לפי האם מותר לצרף למרחב משתמשים מחוץ לארגון (true או false).
  • אפשר גם לציין את הפרמטר pageSize כדי להגביל את מספר הרווחים המקסימלי שיוחזרו (עד 1000), או את הפרמטר pageToken כדי לאחזר דפים נוספים של תוצאות.
  • אופציונלי, מציינים orderBy כדי למיין את תוצאות החיפוש (createTime desc או relevance desc). הערה: relevance desc זמין דרך תוכנית התצוגה המקדימה למפתחים של Google Workspace.

בשדות שונים בשאילתה, יש תמיכה רק באופרטורים AND. לדוגמה: spaceType = "SPACE" AND displayName:"Hello" AND externalUserAllowed = "true". בתוך displayName ו-externalUserAllowed, יש תמיכה באופרטורים OR אם רוצים להתאים לכמה קריטריונים.

בדוגמה הבאה מחפשים מרחבים עם שם שמכילים את המילה Project בשם המוצג שלהם:

Node.js

/**
 * This sample shows how to search for spaces without administrator privileges.
 *
 * It relies on the @google-apps/chat npm package.
 */
// Read the documentation for more details:
// https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces/search

const {ChatServiceClient} = require('@google-apps/chat');
const {auth} = require('google-auth-library');

async function main() {
  // Create a client
  const chatClient = new ChatServiceClient({
    authClient: await auth.getClient({
      scopes: ['https://www.googleapis.com/auth/chat.spaces.readonly']
    })
  });

  // Initialize request arguments.
  // When useAdminAccess is false, spaceType and displayName are required in query.
  const request = {
    query: 'spaceType = "SPACE" AND displayName:"Project"',
    useAdminAccess: false
  };

  // Call the API and iterate over the paginated response
  const iterable = chatClient.searchSpacesAsync(request);
  for await (const result of iterable) {
    console.log('Found space:', result.space.displayName, result.space.name);
  }
}

main().catch(console.error);

Python

"""
This sample shows how to search for spaces without administrator privileges.
"""
from google.apps import chat_v1
import google.auth

# Read the documentation for more details:
# https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces/search

def search_spaces():
    # Create a client
    scopes = ["https://www.googleapis.com/auth/chat.spaces.readonly"]
    credentials, _ = google.auth.default(scopes=scopes)
    client = chat_v1.ChatServiceClient(credentials=credentials)

    # Initialize request arguments.
    # When use_admin_access is False, space_type and display_name are required in query.
    request = chat_v1.SearchSpacesRequest(
        query='spaceType = "SPACE" AND displayName:"Project"',
        use_admin_access=False
    )

    # Make the request and iterate over the paginated results.
    page_result = client.search_spaces(request)
    for result in page_result.results:
        print(f"Found space: {result.space.display_name} ({result.space.name})")

if __name__ == "__main__":
    search_spaces()

Java

/**
 * This sample shows how to search for spaces without administrator privileges.
 */
import com.google.chat.v1.ChatServiceClient;
import com.google.chat.v1.ChatServiceClient.SearchSpacesPagedResponse;
import com.google.chat.v1.SearchSpacesRequest;
import com.google.chat.v1.SearchSpaceResult;

// Read the documentation for more details:
// https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces/search

public class SearchSpaces {
  public static void main(String[] args) 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 = AuthenticationUtils.createClientWithUserCredentials(
        ImmutableList.of("https://www.googleapis.com/auth/chat.spaces.readonly"))) {
      SearchSpacesRequest request = SearchSpacesRequest.newBuilder()
          .setQuery("spaceType = \"SPACE\" AND displayName:\"Project\"")
          .setUseAdminAccess(false)
          .build();

      SearchSpacesPagedResponse response = chatServiceClient.searchSpaces(request);

      for (SearchSpaceResult result : response.iterateAll()) {
        System.out.printf("Found space: %s (%s)\n", result.space.getDisplayName(), result.space.getName());
      }
    }
  }
}

Apps Script

/**
 * This sample shows how to search for spaces without administrator privileges.
 */
// Read the documentation for more details:
// https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces/search

function searchSpaces() {
  try {
    // Call the API
    // When useAdminAccess is false, spaceType and displayName are required in query.
    const response = Chat.Spaces.search({
      query: 'spaceType = "SPACE" AND displayName:"Project"',
      useAdminAccess: false
    });

    if (response.results && response.results.length > 0) {
      response.results.forEach(result => {
        console.log('Found space: %s (%s)', result.space.displayName, result.space.name);
      });
    } else {
      console.log('No matching spaces found.');
    }
  } catch (err) {
    console.log('Failed to search spaces: ' + err.message);
  }
}

‫Chat API מחזיר רשימה עם מספור עמודים של חללים שתואמים לשאילתה ושהמשתמש שקורא ל-API יכול לגשת אליהם.