מעקב אחר פעולות ממושכות

בדף הזה מוסבר איך לנהל את מחזור החיים של פעולה ממושכת (LRO) בחיפוש באמצעות סוכן.

אובייקט של פעולה ממושכת מוחזר כשקריאה לשיטה עשויה להימשך זמן רב. לדוגמה, כשמפעילים את documents.import באמצעות Discovery Engine API או ספריות הלקוח, נוצרת פעולה ממושכת. הפעולה עוקבת אחרי הסטטוס של משימת העיבוד.

אתם יכולים להשתמש ב-methods של פעולות ממושכות ש-Discovery Engine API מספק כדי לבדוק את הסטטוס של הפעולות. אפשר גם להציג רשימה של פעולות או לבצע דגימה של פעולות.

תיעוד של פעולה נשמר למשך כ-30 ימים אחרי שהפעולה מסתיימת, ולכן אי אפשר לראות או לרשום פעולה אחרי התקופה הזו.

הצגת רשימה של פעולות ממושכות

בדוגמה הבאה אפשר לראות איך מציגים את הפעולות של משאב Google Cloud.

הערה: אי אפשר לסנן או להציג בפילוח לדפים פעולות ממושכות בחיפוש הסוכן. כלומר, כשקוראים ל-method operations.list, אי אפשר להשתמש בשדות filter, pageSize או pageToken.

REST

כדי לכלול ברשימה את הפעולות ארוכות הטווח של משאב Google Cloud , פועלים לפי השלב הבא:

• מבצעים קריאה ל-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: המזהה של מאגר הנתונים של חיפוש מבוסס סוכנים שנוצר באמצעות המנוע. בכתובת ה-URL של מסוף Google Cloud , מזהה מאגר הנתונים מופיע אחרי engines/ ולפני /data.

Python

מידע נוסף מופיע בתיעוד העזר של ה-API של חיפוש מבוסס סוכנים Python.

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

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

איך מקבלים פרטים על פעולה ממושכת

בדוגמאות הבאות מוסבר איך לקבל פרטים על פעולה.

REST

כדי לראות את הסטטוס של פעולה ממושכת ואת הפרטים שלה, פועלים לפי השלבים הבאים:

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

   • אחרי שמפעילים שיטה שמחזירה פעולה ממושכת, בודקים את התשובה.

     לדוגמה, אם קוראים ל-documents.import, תחילת התגובה תיראה בערך כך:

     {
       "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",
           }
         }
       ]
     }
     

     הערך name בתגובה מספק את שם הפעולה, שאפשר להשתמש בו כדי לשלוח שאילתה לגבי סטטוס הפעולה. כשמעתיקים את שם הפעולה, לא כוללים את המירכאות.

   • אפשר לקבל את שם הפעולה על ידי הצגת רשימה של פעולות ממושכות.

2. מבצעים קריאה לשיטה operations.get במשאב שיצר את הפעולה:

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

   ‫OPERATION_NAME: צריך לציין את שם הפעולה שרוצים לקבל עליה מידע. אפשר למצוא את שם הפעולה על ידי רישום של פעולות ממושכות.

   השורות הראשונות של התגובה מהפקודה GET נראות כך:

   {
         "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

מידע נוסף מופיע בתיעוד העזר של ה-API של חיפוש מבוסס סוכנים Python.

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

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

דגימה של פעולה ממושכת

בדוגמאות הבאות אפשר לראות איך שולחים שאילתה כדי לבדוק את הסטטוס של פעולה.

REST

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

1. מריצים את הפקודה הבאה, שמפעילה שוב ושוב את השיטה operations.get, עם השהיה מומלצת לפני ניסיון חוזר (backoff) של 10 שניות בין כל בקשה:

   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: מציינים את שם הפעולה שרוצים לבדוק את הסטטוס שלה. אפשר למצוא את שם הפעולה על ידי רישום של פעולות ממושכות. לדוגמה, projects/12345/locations/global/collections/default_collection/dataStores/my-datastore_4321/branches/0/operations/import-documents-56789.

2. מפסיקים את עבודת הבדיקה (Control+Z) אחרי שהסטטוס משתנה ל-"done": true.

Python

מידע נוסף מופיע בתיעוד העזר של ה-API של חיפוש מבוסס סוכנים Python.

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

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

ביטול פעולה ממושכת

בדוגמה הבאה אפשר לראות איך מבטלים פעולה:

REST

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

• מבצעים קריאה ל-operations.cancel:

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

  ‫OPERATION_NAME: מציינים את שם הפעולה שרוצים לבטל. אפשר למצוא את שם הפעולה על ידי רישום של פעולות ממושכות. לדוגמה, projects/12345/locations/global/collections/default_collection/dataStores/my-datastore_4321/branches/0/operations/import-documents-56789.

  אחרי שמתבצעת קריאה ל-API, השרת מנסה לבטל את הפעולה. אלה התוצאות שיוצגו והפעולות שאפשר לבצע:

  • שגיאה בפונקציות "code": 400 ו-"status": "FAILED_PRECONDITION" מציינת שלא ניתן לבטל את הבקשה.

  • אם הביטול יבוצע בהצלחה, יוחזר אובייקט JSON ריק. כדי לאמת את הביטול:

    • משתמשים בשיטה operations.get.

    • אם הפעולה בוטלה בהצלחה, התשובה מ-method‏ operations.get כוללת את השגיאה "code": 1, שמייצגת את קוד הסטטוס CANCELLED.

      לדוגמה:

      {
        "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

מידע נוסף מופיע בתיעוד העזר של ה-API של חיפוש מבוסס סוכנים Python.

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

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