ניהול וגילוי של נקודות קצה

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

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

1. הגדרת Agent Registry.

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

3. רושמים נקודות קצה ב-Agent Registry.

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

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

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

• למצוא נקודות קצה: צפייה ב-Agent Registry API ‏ (roles/agentregistry.viewer)
• לעדכן ולמחוק נקודות קצה: עריכה של Agent Registry API (roles/agentregistry.editor)

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

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

נקודות קצה (endpoints) של Discover

כדי לעיין בכתובות ה-URL לטירגוט ובממשקי ה-API בארכיטקטורת REST שרשומים בסביבה שלכם, הציגו את רשימת המשאבים הזמינים של Endpoint.

הצגת רשימה של כל נקודות הקצה

מציגים את כל נקודות הקצה הרשומות בסביבה:

המסוף

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

   כניסה ל-Agent Registry

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

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

   בדף מוצגת רשימה של כל נקודות הקצה הרשומות והפרטים שלהן, כמו שם, תיאור ומיקום.

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

gcloud

כדי להציג את כל נקודות הקצה במיקום מסוים, מריצים את הפקודה gcloud agent-registry endpoints list:

gcloud agent-registry endpoints list \
    --project=PROJECT_ID \
    --location=REGION

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

• ‫PROJECT_ID: מזהה הפרויקט.
• ‫REGION: האזור של המרשם.

סינון נקודות קצה רשומות

אם יש לכם כמה נקודות קצה, אתם יכולים לסנן את הרשימה לפי המטא-נתונים של נקודת הקצה:

המסוף

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

   כניסה ל-Agent Registry

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

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

   בדף מוצגת רשימה של כל נקודות הקצה הרשומות והפרטים שלהן, כמו שם, תיאור ומיקום.

4. כדי לסנן לפי מיקום, לוחצים על התפריט Location, בוחרים את המיקומים שרוצים לסנן ולוחצים על Apply.

   בדף מוצגת רשימה מסוננת של נקודות הקצה הרשומות בהתאם לתנאים שבחרתם.

gcloud

כדי לסנן את הרשימה כך שתחזיר רק משאבים שתואמים למטא-נתונים ספציפיים, מעבירים את הדגל --filter לפקודה gcloud agent-registry endpoints list:

gcloud agent-registry endpoints list \
    --project=PROJECT_ID \
    --location=REGION \
    --filter="FILTER_EXPRESSION"

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

• ‫PROJECT_ID: מזהה הפרויקט.
• ‫REGION: האזור של המרשם.
• ‫FILTER_EXPRESSION: ביטוי הסינון של נקודות הקצה שרוצים לסנן. לדוגמה, כדי לסנן לפי השם המוצג, משתמשים ב-displayName='DISPLAY_NAME'. כדי לסנן לפי מזהה נקודת הקצה (URN) הייחודי ברמה הגלובלית, משתמשים ב-endpointId='urn:endpoint:ENDPOINT_URN'.

Terraform

כדי לאחזר נקודת קצה רשומה ספציפית על ידי סינון לפי המטא-נתונים שלה, מגדירים את מקור הנתונים google_agent_registry_endpoint באמצעות הארגומנט filter:

data "google_agent_registry_endpoint" "filtered_endpoint" {
  location = "REGION"
  filter   = "displayName=\"DISPLAY_NAME\""
}

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

• ‫REGION: האזור של המרשם.
• ‫DISPLAY_NAME: השם הקריא לאנשים של נקודת הקצה (endpoint) שלפיה רוצים לסנן, לדוגמה Example API Endpoint.

הצגת פרטים מנקודת קצה (endpoint)

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

המסוף

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

   כניסה ל-Agent Registry

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

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

   בדף מוצגת רשימה של כל נקודות הקצה הרשומות והפרטים שלהן, כמו שם, תיאור ומיקום.

4. לוחצים על השם של נקודת הקצה שרוצים לראות.

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

gcloud

כדי לאחזר מטא-נתונים מפורטים על נקודת קצה ספציפית, כולל כתובת ה-URL המלאה של הממשק והקישור לפרוטוקול, מריצים את הפקודה gcloud agent-registry endpoints describe:

gcloud agent-registry endpoints describe ENDPOINT_NAME \
    --project=PROJECT_ID \
    --location=REGION

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

• ‫PROJECT_ID: מזהה הפרויקט.
• ‫REGION: האזור של המרשם.
• ‫ENDPOINT_NAME: שם נקודת הקצה, לדוגמה my-external-api.

Terraform

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

data "google_agent_registry_endpoint" "my_endpoint" {
  location    = "REGION"
  endpoint_id = "ENDPOINT_NAME"
}

output "endpoint_create_time" {
  description = "The timestamp when the endpoint was registered."
  value       = data.google_agent_registry_endpoint.my_endpoint.create_time
}

output "endpoint_update_time" {
  description = "The timestamp when the endpoint was last updated."
  value       = data.google_agent_registry_endpoint.my_endpoint.update_time
}

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

• ‫REGION: האזור של המרשם.
• ‫ENDPOINT_NAME: המזהה הייחודי של נקודת הקצה, לדוגמה my-external-api.

עדכון נקודת קצה (endpoint)

אם כתובת ה-URL הבסיסית של נקודת קצה חיצונית משתנה, אתם יכולים לעדכן את פרטי הממשק של נקודת הקצה.

ב-Agent Registry, משאבי Endpoint הם משאבי גילוי לקריאה בלבד. לכן, כדי לעדכן נקודת קצה רשומה, צריך לעדכן ישירות את המשאב Service שניתן לכתיבה.

כדי לעדכן נקודת קצה:

המסוף

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

   כניסה ל-Agent Registry

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

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

   בדף מוצגת רשימה של כל נקודות הקצה הרשומות והפרטים שלהן, כמו שם, תיאור ומיקום.

4. לוחצים על השם של נקודת הקצה שרוצים לעדכן.

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

5. לוחצים על עריכה.

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

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

gcloud

מריצים את הפקודה gcloud agent-registry services update עם הדגל --interfaces כדי לציין את כתובת היעד החדשה:

gcloud agent-registry services update ENDPOINT_NAME \
    --project=PROJECT_ID \
    --location=REGION \
    --interfaces=url=ENDPOINT_URL,protocolBinding=PROTOCOL

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

• ‫ENDPOINT_NAME: שם נקודת הקצה, לדוגמה my-external-api.
• ‫PROJECT_ID: מזהה הפרויקט שבו נוצר המשאב Service.
• ‫REGION: האזור של המרשם.
• ‫ENDPOINT_URL: כתובת היעד החדשה, לדוגמה https://new-api.example.com/v1/data.
• ‫PROTOCOL: הקישור לפרוטוקול של הממשק. הערכים התקינים הם http-json,‏ grpc או jsonrpc.

Terraform

כדי לעדכן כתובת URL של נקודת קצה או קישור לפרוטוקול באמצעות Terraform, משנים את הבלוק interfaces של המשאב הקיים google_agent_registry_service בהגדרות, ואז מריצים את הפקודה terraform apply:

resource "google_agent_registry_service" "endpoint" {
  location     = "REGION"
  service_id   = "ENDPOINT_NAME"
  display_name = "DISPLAY_NAME"

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

  endpoint_spec {
    type = "NO_SPEC"
  }
}

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

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

הסרה של נקודת קצה (endpoint)

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

כדי להסיר נקודת קצה מהמרשם:

המסוף

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

   כניסה ל-Agent Registry

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

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

   בדף מוצגת רשימה של כל נקודות הקצה הרשומות והפרטים שלהן, כמו שם, תיאור ומיקום.

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

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

5. לוחצים על מחיקה.

6. בחלון Delete endpoint, מזינים את הערך DELETE כדי לאשר את הפעולה.

7. לוחצים על Delete.

gcloud

מריצים את הפקודה gcloud agent-registry services delete:

gcloud agent-registry services delete ENDPOINT_NAME \
    --project=PROJECT_ID \
    --location=REGION

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

• ‫ENDPOINT_NAME: השם של נקודת הקצה שרוצים להסיר, לדוגמה my-external-api.
• ‫PROJECT_ID: מזהה הפרויקט שבו נוצר המשאב Service.
• ‫REGION: האזור של המרשם.

Terraform

מסירים את המשאב google_agent_registry_service שמייצג את נקודת הקצה מההגדרות של Terraform, ואז מריצים את הפקודה terraform apply.