רישום נקודות קצה

בעזרת Agent Registry אתם יכולים לרשום באופן ידני כתובות URL של יעדים, כמו ממשקי API חיצוניים בארכיטקטורת REST, כנקודות קצה מנוהלות, כדי שתוכלו לקבוע באופן מרכזי לאילו יעדים קבוצת הנציגים שלכם יכולה להתחבר.

אפשר לרשום נקודות קצה במיקום אזורי נתמך, במיקום נתמך במספר אזורים או במיקום global. למידע נוסף על מיקומים נתמכים, ראו מיקומים של Agent Registry.

לפני שמתחילים

  1. הגדרת Agent Registry.

  2. אם אתם משתמשים בפרויקט אחד, אתרו את מזהה הפרויקט של פרויקט הפיקוח שבו מופעל Agent Registry. אם הגדרתם גבול ניהול לכמה פרויקטים, השתמשו במזהה של פרויקט הניהול כדי לגלות ולרשום את כל הפרויקטים בגבול, או ציינו מזהה של פרויקט חבר כדי לבצע פעולות בפרויקט יחיד.

  3. כדי להשתמש בפקודות של Google Cloud CLI שמופיעות במסמך הזה, צריך להגדיר את סביבת ה-CLI של gcloud.

התפקידים הנדרשים

כדי לקבל את ההרשאות שנדרשות לרישום נקודות קצה ב-Agent Registry, צריך לבקש מהאדמין להקצות לכם את התפקיד עריכה ב-Agent Registry API (roles/agentregistry.editor) ב-IAM בפרויקט הפיקוח שבו Agent Registry מופעל. להסבר על מתן תפקידים, קראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.

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

רישום נקודת קצה (endpoint)

נקודות קצה הן יעדים חיצוניים בהתאמה אישית, לכן צריך להשתמש ברישום ידני כדי להוסיף אותן ל-Agent Registry:

המסוף

  1. במסוף Google Cloud , נכנסים לדף Agent Registry:

    כניסה ל-Agent Registry

  2. בכלי לבחירת פרויקטים, בוחרים את הפרויקט ב- Google Cloud שבו הגדרתם את Agent Registry.

  3. לוחצים על הכרטיסייה נקודות קצה (endpoints).

  4. לוחצים על הוספת נקודת קצה.

  5. בחלונית Endpoint details, מזינים את השם המוצג, תיאור, האזור הגיאוגרפי וכתובת היעד.

    אם רוצים, לוחצים על Test connection בחלונית הזו כדי לבדוק את החיבור לכתובת היעד.

  6. לוחצים על Save.

gcloud

הדגלים של המפרט שבהם אתם משתמשים קובעים לאיזה אוסף משאבים הרכיב שלכם שייך. כדי לראות מיפוי מלא של דגלים לאוספי משאבים, קראו את המאמר [משאבי שירות ומשאבי גילוי](/agent-registry/data-model#service-resources).

כדי להוסיף את נקודת הקצה ל-Agent Registry, יוצרים משאב Service באמצעות הפקודה gcloud agent-registry services create והדגל --endpoint-spec-type מוגדר ל-no-spec:

gcloud agent-registry services create ENDPOINT_NAME \
    --project=PROJECT_ID \
    --location=REGION \
    --display-name="DISPLAY_NAME" \
    --endpoint-spec-type=no-spec \
    --interfaces=url=ENDPOINT_URL,protocolBinding=PROTOCOL

מחליפים את מה שכתוב בשדות הבאים:

  • ‫ENDPOINT_NAME: השם שרוצים לתת לנקודת הקצה, לדוגמה my-external-api. השם צריך להיות באורך של 4 עד 63 תווים, ויכול להכיל רק אותיות קטנות, מספרים ומקפים.
  • ‫PROJECT_ID: מזהה הפרויקט.
  • ‫REGION: האזור של המרשם.
  • ‫DISPLAY_NAME: השם הקריא לאנשים של נקודת הקצה, לדוגמה My External API.
  • ‫ENDPOINT_URL: כתובת ה-URL המטורגטת, לדוגמה, https://api.example.com/v1/data.
  • ‫PROTOCOL: הקישור לפרוטוקול של הממשק. הערכים התקינים הם http-json,‏ grpc או jsonrpc.

אחרי שיוצרים את המשאב Service, המערכת של Agent Registry יוצרת באופן אוטומטי משאב Endpoint לקריאה בלבד, שסוכנים ומתזמרים יכולים לגלות ולהשתמש בו.

Terraform

בלוק המפרט שאתם מגדירים קובע לאיזה אוסף משאבים הרכיב שלכם שייך. במאמר [משאבי שירות ומשאבי גילוי](/agent-registry/data-model#service-resources) מפורט המיפוי המלא של המפרטים לאוספי המשאבים.

כדי לרשום נקודת קצה חיצונית, מגדירים את המשאב google_agent_registry_service באמצעות הבלוק endpoint_spec:

resource "google_agent_registry_service" "endpoint" {
  location     = "REGION"
  service_id   = "ENDPOINT_NAME"
  display_name = "DISPLAY_NAME"
  description  = "An external REST API registered using Terraform."

  interfaces {
    url              = "ENDPOINT_URL"
    protocol_binding = "PROTOCOL"
  }

  endpoint_spec {
    type = "NO_SPEC"
  }
}

output "endpoint_resource_name" {
  description = "The generated read-only Endpoint resource name."
  value       = google_agent_registry_service.endpoint.registry_resource
}

מחליפים את מה שכתוב בשדות הבאים:

  • ‫REGION: האזור של המרשם.
  • ‫ENDPOINT_NAME: השם הייחודי שרוצים לתת לנקודת הקצה, לדוגמה my-external-api. השם צריך להיות באורך של 4 עד 63 תווים, ויכול להכיל רק אותיות קטנות, מספרים ומקפים.
  • ‫DISPLAY_NAME: השם הקריא לאנשים של נקודת הקצה, לדוגמה My External API.
  • ‫ENDPOINT_URL: כתובת ה-URL המטורגטת, לדוגמה, https://api.example.com/v1/data.
  • ‫PROTOCOL: הקישור לפרוטוקול של הממשק. הערכים התקינים הם HTTP_JSON,‏ GRPC או JSONRPC.

רישום נקודת קצה משולבת ל-Google APIs

בארכיטקטורה של פרויקטים שונים, פרויקט ניהול מרכזי מארח תשתית משותפת כמו Agent Registry ו-Agent Gateway, ופרויקטים נפרדים של Google Cloud מארחים מכונות של סוכנים.

כשמנתבים את תנועת הנתונים של הנציג דרך Agent Gateway במצב תעבורת נתונים יוצאת, תנועה ברשת יוצאת נחסמת כברירת מחדל. כדי לאפשר לסוכנים בפרויקטים נפרדים של Google Cloud לתקשר עם ממשקי API חיוניים שלGoogle Cloud , אתם יכולים לקבץ כמה ממשקי API למשאב מורכב אחד של Service בפרויקט הניהול המרכזי.

קיבוץ הממשקים לנקודת קצה אחת מאפשר לכם לנהל את המדיניות בקלות, כי אתם יכולים לנהל קישור מדיניות אחד של שרת proxy לאימות זהויות (IAP) לכל חבילת ממשקי ה-API העיקריים של Google.

כדי לרשום נקודת קצה מורכבת ל-Google APIs:

gcloud

רושמים את נקודת הקצה עם כמה כתובות URL של ממשקים בפרויקט הניהול המרכזי באמצעות הפקודה gcloud agent-registry services create:

gcloud agent-registry services create SERVICE_NAME \
    --project=CENTRAL_PROJECT_ID \
    --location=REGION \
    --display-name="DISPLAY_NAME" \
    --description="DESCRIPTION" \
    --endpoint-spec-type=no-spec \
    --interfaces=protocolBinding=jsonrpc,url=API_URL \
    --interfaces=protocolBinding=jsonrpc,url=ADDITIONAL_API_URL

מחליפים את מה שכתוב בשדות הבאים:

  • ‫SERVICE_NAME: המזהה של השירות, לדוגמה core-gapi-services. השם צריך להיות באורך של 4 עד 63 תווים, ויכול להכיל רק אותיות קטנות, מספרים ומקפים.
  • ‫CENTRAL_PROJECT_ID: מזהה הפרויקט של פרויקט הפיקוח המרכזי שמארח את Agent Registry ואת Agent Gateway.
  • ‫REGION: האזור שבו נמצאים השער והמרשם.
  • ‫DISPLAY_NAME: השם שקריא לאנשים, לדוגמה Core Google APIs.
  • ‫DESCRIPTION: תיאור קצר, לדוגמה Essential Google APIs for agent operations.
  • ‫API_URL: כתובת ה-URL של ה-API הראשי של Google, למשל https://telemetry.googleapis.com.
  • ‫ADDITIONAL_API_URL: חוזרים על הדגל --interfaces לכל כתובת URL נוספת של Google API או וריאנט שנדרש על ידי הנציגים, כמו https://cloudresourcemanager.googleapis.com,‏ https://iamcredentials.googleapis.com,‏ https://agentregistry.googleapis.com או וריאנטים אזוריים ו-mTLS כמו https://telemetry.mtls.googleapis.com.

Terraform

כדי לרשום את נקודת הקצה המשולבת של Google APIs באמצעות Terraform, מגדירים את המשאב google_agent_registry_service עם כמה בלוקים של interfaces:

resource "google_agent_registry_service" "core_gapi_services" {
  project      = "CENTRAL_PROJECT_ID"
  location     = "REGION"
  service_id   = "SERVICE_NAME"
  display_name = "DISPLAY_NAME"
  description  = "DESCRIPTION"

  endpoint_spec {
    type = "NO_SPEC"
  }

  interfaces {
    url              = "API_URL"
    protocol_binding = "JSONRPC"
  }

  # Add an interfaces block for each additional Google API URL
  interfaces {
    url              = "ADDITIONAL_API_URL"
    protocol_binding = "JSONRPC"
  }
}

מחליפים את מה שכתוב בשדות הבאים:

  • ‫CENTRAL_PROJECT_ID: מזהה הפרויקט של פרויקט הפיקוח המרכזי.
  • ‫REGION: האזור של המרשם.
  • ‫SERVICE_NAME: מזהה השירות, לדוגמה core-gapi-services. השם צריך להיות באורך של 4 עד 63 תווים, ויכול להכיל רק אותיות קטנות, מספרים ומקפים.
  • ‫DISPLAY_NAME: השם שקריא לאנשים, לדוגמה Core Google APIs.
  • ‫DESCRIPTION: תיאור נקודת הקצה.
  • ‫API_URL: כתובת ה-URL של ה-API הראשי של Google, למשל https://telemetry.googleapis.com.
  • ‫ADDITIONAL_API_URL: חוזרים על הבלוק interfaces לכל כתובת URL נוספת של Google API או וריאנט שנדרש על ידי הנציגים, כמו https://cloudresourcemanager.googleapis.com,‏ https://iamcredentials.googleapis.com,‏ https://agentregistry.googleapis.com או וריאנטים אזוריים ו-mTLS כמו https://telemetry.mtls.googleapis.com.

המאמרים הבאים