البحث عن مساحات

يوضّح هذا الدليل كيفية استخدام طريقة search() في مورد Space ضِمن Google Chat API للبحث عن مساحات مُسمّاة في مؤسسة Google Workspace.

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

  • الرسائل المباشرة (DMs) هي محادثات بين مستخدمَين أو بين مستخدم وتطبيق Chat.
  • المحادثات الجماعية هي محادثات بين ثلاثة مستخدمين أو أكثر وتطبيقات Chat.
  • المساحات المُسمّاة هي أماكن دائمة يرسل فيها المستخدمون الرسائل ويشاركون الملفات ويتعاونون معًا.

إذا كنت مشرفًا في Google Workspace وأردت البحث في جميع المساحات في مؤسستك، بما في ذلك المساحات الخاصة التي لم تنضم إليها، يُرجى الاطّلاع على مقالة البحث عن المساحات وإدارتها بصفتك مشرفًا في Google Workspace لاستدعاء واجهة برمجة التطبيقات بامتيازات المشرف (useAdminAccess=true).

عند البحث عن مساحات باستخدام مصادقة المستخدم بدون امتيازات المشرف، تبحث الطريقة عن المساحات المُسمّاة (spaceType من SPACE) التي يمكن للمستخدم الذي تم التحقّق من هويته الوصول إليها، مثل المساحات التي يكون عضوًا فيها، ضِمن مؤسسته.

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

Node.js

  • حساب Google Workspace Business أو Enterprise مع إمكانية الوصول إلى Google Chat

Python

  • حساب Google Workspace Business أو Enterprise مع إمكانية الوصول إلى Google Chat

جافا

  • حساب Google Workspace Business أو Enterprise مع إمكانية الوصول إلى Google Chat

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

  • حساب Google Workspace Business أو Enterprise مع إمكانية الوصول إلى Google Chat

البحث عن مساحات باستخدام مصادقة المستخدم

للبحث عن مساحات في 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 Developer Preview.

في الحقول المختلفة في الطلب، لا تتوفّر إلا عوامل التشغيل 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()

جافا

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

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

/**
 * 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 قائمة مساحات مقسّمة على صفحات تطابق الطلب ويمكن للمستخدم الذي يستدعي واجهة برمجة التطبيقات الوصول إليها.