Menelusuri ruang

Panduan ini menjelaskan cara menggunakan metode search() pada resource Space Google Chat API untuk menelusuri ruang bernama di organisasi Google Workspace.

Space Resource mewakili tempat orang dan aplikasi Chat dapat mengirim pesan, berbagi file, dan berkolaborasi. Ada beberapa jenis ruang:

  • Pesan langsung (DM) adalah percakapan antara dua pengguna atau antara pengguna dan aplikasi Chat.
  • Chat grup adalah percakapan antara tiga pengguna atau lebih dan aplikasi Chat.
  • Ruang bernama adalah tempat persisten tempat orang mengirim pesan, berbagi file, dan berkolaborasi.

Jika Anda adalah administrator Google Workspace dan ingin menelusuri semua ruang di organisasi Anda, termasuk ruang pribadi yang belum Anda ikuti, lihat Menelusuri dan mengelola ruang sebagai administrator Google Workspace untuk memanggil API dengan hak istimewa administrator (useAdminAccess=true).

Saat menelusuri ruang dengan autentikasi pengguna tanpa hak istimewa administrator, metode ini akan menelusuri ruang bernama (spaceType dari SPACE) yang dapat diakses oleh pengguna yang diautentikasi, seperti ruang yang dia ikuti, dalam organisasi mereka.

Prasyarat

Node.js

Python

Java

Apps Script

Menelusuri ruang dengan autentikasi pengguna

Untuk menelusuri ruang di Google Chat tanpa hak istimewa administrator, teruskan hal berikut dalam permintaan Anda:

  • Dengan autentikasi pengguna, tentukan cakupan otorisasi chat.spaces.readonly atau chat.spaces.
  • Panggil metode search() pada resource Space.
  • Tetapkan useAdminAccess ke false (atau hapus parameter).
  • Tentukan parameter penelusuran query untuk memfilter hasil:
    • spaceType = "SPACE" - diperlukan saat query ditentukan dan satu-satunya nilai yang didukung adalah SPACE.
    • displayName - filter berdasarkan nama tampilan ruang menggunakan operator HAS (:). Misalnya, displayName:"Project". Teks yang akan dicocokkan akan di-tokenisasi dan setiap token akan dicocokkan dengan awalan secara tidak peka huruf besar/kecil dan independen sebagai substring di mana saja dalam displayName ruang. Catatan: Jika useAdminAccess adalah false, displayName diperlukan dalam kueri Anda untuk mengambil hasil yang bermakna; jika tidak, metode ini akan menampilkan respons kosong.
    • externalUserAllowed - secara opsional, filter berdasarkan apakah tamu eksternal diizinkan di ruang (true atau false).
  • Secara opsional, tentukan pageSize untuk membatasi jumlah maksimum ruang yang akan ditampilkan (hingga 1000), atau pageToken untuk mengambil halaman hasil berikutnya.
  • Secara opsional, tentukan orderBy untuk mengurutkan hasil penelusuran (createTime desc atau relevance desc). Catatan: relevance desc tersedia melalui Program Pratinjau Developer Google Workspace.

Di berbagai kolom dalam kueri, hanya operator AND yang didukung. Contoh: spaceType = "SPACE" AND displayName:"Hello" AND externalUserAllowed = "true". Dalam displayName dan externalUserAllowed, operator OR didukung jika Anda ingin mencocokkan beberapa kriteria.

Contoh berikut menelusuri ruang bernama yang berisi "Project" di nama tampilannya:

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 menampilkan daftar ruang yang dipaginasi yang cocok dengan kueri dan dapat diakses oleh pengguna yang memanggil.