Memantau operasi yang berjalan lama

Halaman ini menjelaskan cara mengelola siklus proses operasi yang berjalan lama (LRO) di Penelusuran Agen.

Objek operasi yang berjalan lama akan ditampilkan saat panggilan ke metode mungkin memerlukan waktu lama untuk diselesaikan. Misalnya, Discovery Engine API membuat operasi yang berjalan lama saat Anda memanggil documents.import melalui API atau Library Klien. Operasi ini melacak status tugas pemrosesan.

Anda dapat menggunakan metode operasi yang berjalan lama yang disediakan Discovery Engine API untuk memeriksa status operasi. Anda juga dapat mencantumkan atau melakukan polling operasi.

Catatan operasi disimpan selama sekitar 30 hari setelah operasi selesai, yang berarti Anda tidak dapat melihat atau mencantumkan operasi setelah waktu tersebut.

Mencantumkan operasi yang berjalan lama

Berikut ini cara mencantumkan operasi untuk a Google Cloud resource.

REST

Untuk mencantumkan operasi yang berjalan lama untuk a Google Cloud resource, ikuti langkah ini:

  • Panggil metode:operations.list

    curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/operations"

    DATA_STORE_ID: ID penyimpanan data Penelusuran Agen yang dibuat dengan mesin Anda. Di URL konsol Google Cloud , ID penyimpanan data muncul setelah engines/ dan sebelum /data.

Python

Untuk mengetahui informasi selengkapnya, lihat Penelusuran Agen Python API dokumentasi referensi.

Untuk melakukan autentikasi ke Penelusuran Agen, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal. 

from typing import Optional

from google.cloud import discoveryengine
from google.longrunning import operations_pb2

# TODO(developer): Uncomment these variables before running the sample.
# project_id = "YOUR_PROJECT_ID"
# location = "YOUR_PROCESSOR_LOCATION"  # Options: "global"
# search_engine_id = "YOUR_SEARCH_ENGINE_ID"

# Create filter in https://google.aip.dev/160 syntax
# operations_filter = "YOUR_FILTER"


def list_operations_sample(
    project_id: str,
    location: str,
    search_engine_id: str,
    operations_filter: Optional[str] = None,
) -> operations_pb2.ListOperationsResponse:
    # Create a client
    client = discoveryengine.DocumentServiceClient()

    # The full resource name of the search engine branch.
    name = f"projects/{project_id}/locations/{location}/collections/default_collection/dataStores/{search_engine_id}"

    # Make ListOperations request
    request = operations_pb2.ListOperationsRequest(
        name=name,
        filter=operations_filter,
    )

    # Make ListOperations request
    response = client.list_operations(request=request)

    # Print the Operation Information
    for operation in response.operations:
        print(operation)

    return response

Mendapatkan detail tentang operasi yang berjalan lama

Berikut ini cara mendapatkan detail tentang operasi.

REST

Untuk mendapatkan status dan melihat detail tentang operasi yang berjalan lama, ikuti langkah-langkah berikut:

  1. Temukan nama operasi dengan salah satu dari dua cara berikut:

    • Setelah melakukan panggilan ke metode yang menampilkan operasi yang berjalan lama, tinjau responsnya.

      Misalnya, jika Anda memanggil documents.import, awal respons akan terlihat seperti ini:

      {
  "operations": [
    {
      "name": "projects/12345/locations/global/collections/default_collection/dataStores/my-datastore_4321/branches/0/operations/import-documents-56789",
      "metadata": {
        "@type": "type.googleapis.com/google.cloud.discoveryengine.v1.ImportDocumentsMetadata",
      }
    }
  ]
}

      Nilai name dalam respons memberikan nama operasi, yang dapat digunakan untuk membuat kueri status operasi. Jangan sertakan tanda kutip saat Anda menyalin nama operasi.

    • Dapatkan nama operasi dengan mencantumkan operasi yang berjalan lama operasi.

  2. Panggil metode operations.get pada resource yang membuat operasi:

    curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://discoveryengine.googleapis.com/v1/OPERATION_NAME"

    OPERATION_NAME: Berikan nama operasi yang informasinya Anda butuhkan. Anda dapat menemukan nama operasi dengan mencantumkan operasi yang berjalan lama.

    Baris pertama respons dari perintah GET akan terlihat seperti ini:

    {
      "name": "projects/12345/locations/global/collections/default_collection/dataStores/my-datastore_4321/branches/0/operations/import-documents-56789",
      "metadata": {
        "@type": "type.googleapis.com/google.cloud.discoveryengine.v1.ImportDocumentsMetadata"
      }
    }

Python

Untuk mengetahui informasi selengkapnya, lihat Penelusuran Agen Python API dokumentasi referensi.

Untuk melakukan autentikasi ke Penelusuran Agen, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal. 

from google.cloud import discoveryengine
from google.longrunning import operations_pb2

# TODO(developer): Uncomment these variables before running the sample.
# Example: `projects/{project}/locations/{location}/collections/{default_collection}/dataStores/{search_engine_id}/branches/{0}/operations/{operation_id}`
# operation_name = "YOUR_OPERATION_NAME"


def get_operation_sample(operation_name: str) -> operations_pb2.Operation:
    # Create a client
    client = discoveryengine.DocumentServiceClient()

    # Make GetOperation request
    request = operations_pb2.GetOperationRequest(name=operation_name)
    operation = client.get_operation(request=request)

    # Print the Operation Information
    print(operation)

    return operation

Polling operasi yang berjalan lama

Berikut ini cara melakukan polling status operasi.

REST

Untuk melakukan polling operasi yang berjalan lama hingga selesai, ikuti langkah-langkah berikut:

  1. Jalankan perintah berikut, yang memanggil metode operations.get berulang kali, menggunakan backoff 10 detik di antara setiap permintaan:

    while true; \
    do curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://discoveryengine.googleapis.com/v1/OPERATION_NAME"; \
    sleep 10; \
    done

    OPERATION_NAME: Berikan nama operasi yang ingin Anda lakukan polling. Anda dapat menemukan nama operasi dengan mencantumkan operasi yang berjalan lama. Misalnya, projects/12345/locations/global/collections/default_collection/dataStores/my-datastore_4321/branches/0/operations/import-documents-56789.

  2. Hentikan tugas polling (Control+Z) setelah status menampilkan "done": true.

Python

Untuk mengetahui informasi selengkapnya, lihat Penelusuran Agen Python API dokumentasi referensi.

Untuk melakukan autentikasi ke Penelusuran Agen, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal. 

from time import sleep

from google.cloud import discoveryengine
from google.longrunning import operations_pb2

# TODO(developer): Uncomment these variables before running the sample.
# Example: `projects/{project}/locations/{location}/collections/{default_collection}/dataStores/{search_engine_id}/branches/{0}/operations/{operation_id}`
# operation_name = "YOUR_OPERATION_NAME"


def poll_operation_sample(
    operation_name: str, limit: int = 10
) -> operations_pb2.Operation:
    # Create a client
    client = discoveryengine.DocumentServiceClient()

    # Make GetOperation request
    request = operations_pb2.GetOperationRequest(name=operation_name)

    for _ in range(limit):
        operation = client.get_operation(request=request)
        # Print the Operation Information
        print(operation)

        # Stop polling when Operation is no longer running
        if operation.done:
            break

        # Wait 10 seconds before polling again
        sleep(10)

    return operation

Membatalkan operasi yang berjalan lama

Berikut ini cara membatalkan operasi:

REST

Untuk membatalkan operasi yang berjalan lama, ikuti langkah-langkah berikut:

  • Panggil metode:operations.cancel

    curl -X post \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   "https://discoveryengine.googleapis.com/v1/OPERATION_NAME":cancel

    OPERATION_NAME: Berikan nama operasi yang ingin Anda batalkan. Anda dapat menemukan nama operasi dengan mencantumkan operasi yang berjalan lama. Misalnya, projects/12345/locations/global/collections/default_collection/dataStores/my-datastore_4321/branches/0/operations/import-documents-56789.

    Setelah panggilan API dilakukan, server akan mencoba membatalkan operasi. Hasil yang Anda lihat dan tindakan yang dapat Anda lakukan adalah sebagai berikut:

    • Error dengan "code": 400 dan "status": "FAILED_PRECONDITION" menunjukkan bahwa permintaan tidak dapat dibatalkan.

    • Pembatalan yang berhasil akan menghasilkan objek JSON kosong. Untuk memverifikasi pembatalan:

      • Gunakan metode operations.get.

      • Jika operasi berhasil dibatalkan, respons dari metode operations.get akan memiliki error "code": 1, yang mewakili kode status CANCELLED.

        Contoh:

        {
  "name": "projects/12345/locations/global/collections/default_collection/dataStores/my-datastore_4321/branches/0/operations/import-documents-56789",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.discoveryengine.v1alpha.ImportDocumentsMetadata",
    "createTime": "2025-04-28T21:29:21.199190Z",
    "updateTime": "2025-04-28T21:31:29.076865Z"
  },
  "done": true,
  "error": {
    "code": 1,
    "message": "Operation projects/12345/locations/global/collections/default_collection/dataStores/my-datastore_4321/branches/0/operations/import-documents-56789 is cancelled."
  }
}

Python

Untuk mengetahui informasi selengkapnya, lihat Penelusuran Agen Python API dokumentasi referensi.

Untuk melakukan autentikasi ke Penelusuran Agen, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal. 

from google.cloud import discoveryengine
from google.longrunning import operations_pb2

# TODO(developer): Uncomment these variables before running the sample.
# Example: `projects/{project}/locations/{location}/collections/{default_collection}/dataStores/{search_engine_id}/branches/{0}/operations/{operation_id}`
# operation_name = "YOUR_OPERATION_NAME"


def cancel_operation_sample(operation_name: str) -> None:
    # Create a client
    client = discoveryengine.DocumentServiceClient()

    # Make CancelOperation request
    request = operations_pb2.CancelOperationRequest(name=operation_name)
    client.cancel_operation(request=request)

    return