MCP Tools Reference: cloudcli.googleapis.com

כלי: run_bq_command

מריץ פקודה אחת של BigQuery CLI (bq). הכלי הזה מאפשר להריץ כל פקודת bq בפרויקט של המשתמש, כולל פקודות שיוצרות, מעדכנות או מוחקות משאבי GCP (כלומר, מוטציות).

אזהרת בטיחות חשובה (עלולה לגרום נזק): הכלי הזה יכול ליצור, לעדכן או למחוק משאבי BigQuery (למשל, bq rm,‏ bq cancel,‏ bq query). הוא לא מוגבל לפקודות לקריאה בלבד. חשוב לנהוג בזהירות רבה.

פקודות אסורות: סוכן לא יכול להריץ את פקודות ה-bq הבאות: bq init, ‏ bq pyshell, ‏ bq shell.

כללי ביצוע מחמירים:

  1. צריך לציין לפחות אחד מהערכים --project_id או --quota_project_id במחרוזת הפקודה.
  2. מזהה הפרויקט לעומת פרויקט המכסה: הדגל ‎--project_id מציין את פרויקט המשאבים שהפקודה פועלת עליו (זהה לדגל ‎--project של gcloud). הדגל ‎--quota_project_id מציין את הפרויקט שמחויב על השימוש במכסה/חיוב של קריאה ל-API של BigQuery במורד הזרם (זהה לדגל --billing-project של gcloud). אם מציינים את --project_id בפקודה, הוא ישמש כפרויקט לחיוב או למכסה. אם לא מציינים את --project_id או אם מציינים גם את --quota_project_id, הפרויקט לחיוב או למכסה יהיה הפרויקט שמוגדר בדגל --quota_project_id.
  3. פורמט הדגל: תמיד צריך להשתמש בסימן '=' כדי להפריד בין מפתחות הדגל לבין הערכים שלהם בכל האפשרויות הארוכות. נכון: '--project_id=my-project' או '--location=us'. שגוי: '--project_id my-project' או '--location us'. אל תוסיפו רווחים בין הדגלים לבין הערכים שלהם.
  4. אין הגדרות ברירת מחדל: הפקודה bq מופעלת בלי שמירת מצב. היא לא טוענת קובצי תצורה מקומיים כמו ‎.bigqueryrc. לכן, בכל הפעולות האזוריות (למשל, יצירת מערך נתונים או שליחת שאילתה למערך נתונים אזורי), חובה לציין במפורש את הדגל --location (למשל, --location=us או --location=EU).
  5. פעולות אסינכרוניות: פקודות מסוימות מפעילות פעולות סינכרוניות ממושכות (למשל, הפעלת משימות של שאילתות). תמיד צריך להעביר את הדגל --nosync לפקודות האלה כדי למנוע פסק זמן של הסוכן.
  6. הגבלות על פקודות: אסור להשתמש בפקודות bq הבאות: bq init, ‏ bq pyshell, ‏ bq shell. אין תמיכה בצינורות או בשרשור של פקודות.
  7. תיקון עצמי: אם פקודה מחזירה שגיאה, המודל ינתח את stderr, יתקן את התחביר או את האפשרויות וינסה שוב באיטרציה הבאה.

דוגמאות לפקודות bq שמשנות את הנתונים: bq mk,‏ bq rm,‏ bq update,‏ bq insert,‏ bq query (ללא --dry_run) וכו'. אופן השימוש: RunBq(command="bq query --project_id=PROJECT_ID 'SELECT 1'", project="projects/PROJECT_ID", input_files=[{"path": "PATH", "contents": "CONTENTS"}]) חובה לציין את פקודת bq המלאה כמחרוזת אחת בפרמטר 'command'. חובה לציין את הפרמטר project (בפורמט: projects/PROJECT_ID) כפרויקט ההפעלה של ה-API לצורכי חיוב, הפעלת ה-API ובדיקות של ניצול המכסה.

דוגמאות לפקודות או לתבניות של פקודות bq:

  1. מריצים שאילתה: bq query --use_legacy_sql=false --project_id=PROJECT_ID 'SELECT * FROMproject.dataset.tableLIMIT 10'
  2. יצירת מערך נתונים: bq mk --dataset --location=us --project_id=PROJECT_ID myDataset
  3. יצירת טבלה: bq mk --table --project_id=PROJECT_ID myDataset.myTable name:string,value:integer
  4. הסרת מערך נתונים: bq rm -f --dataset --project_id=PROJECT_ID myDataset
  5. הסרת טבלה: bq rm -f -t --project_id=PROJECT_ID myDataset.myTable
  6. עדכון תיאור הטבלה: bq update --description="New description" --project_id=PROJECT_ID myDataset.myTable
  7. הצגת רשימה של מערכי נתונים בפרויקט: bq ls --datasets=true --project_id=PROJECT_ID

בדוגמת הקוד הבאה מוצג שימוש בפקודה curl כדי להפעיל את הכלי run_bq_command MCP.

בקשת Curl 
curl --location 'https://cloudcli.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "run_bq_command",
    "arguments": {
      // provide these details according to the tool's MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

סכימת הקלט

הודעת בקשה ל-RunBq.

RunBqRequest

ייצוג JSON 
{
  "project": string,
  "command": string,
  "inputFiles": [
    {
      object (File)
    }
  ]
}
שדות
project

string

חובה. פרויקט להפעלת ה-API ולצריכת המכסה של CloudCli API.

הפורמט צריך להיות projects/ או projects/
command

string

חובה. שורת הפקודה המלאה של bq להרצה כמחרוזת אחת. דוגמה: "bq ls my-dataset --location=us"

מודלי שפה גדולים מקבלים הוראה להשתמש בדגל --nosync לפעולות ארוכות טווח כדי למנוע פסק זמן.
inputFiles[]

object (File)

זה שינוי אופציונלי. קבצים שיהיו זמינים לפקודת bq להרצה.

קובץ

ייצוג JSON 
{
  "path": string,
  "contents": string
}
שדות
path

string

חובה. נתיב הקובץ ביחס לספריית הבית. אסור להשתמש בתווים '..' (מעבר לספריית האב) או בהרחבות של מעטפת.
contents

string

חובה. תוכן הקובץ.

סכימת הפלט

הודעת התגובה של RunBq.

RunBqResponse

ייצוג JSON 
{
  "response": {
    object (CliExecutionResponse)
  },
  "outputFiles": [
    {
      object (File)
    }
  ]
}
שדות
response

object (CliExecutionResponse)

התגובה מהרצת כלי ה-CLI, שמכילה stdout, ‏ stderr stream וקוד יציאה עצמאיים.
outputFiles[]

object (File)

קבצים שנוצרו על ידי הפקודה bq מההרצה שלה.

CliExecutionResponse

ייצוג JSON 
{
  "stdout": string,
  "stderr": string,
  "exitCode": string
}
שדות
stdout

string

הפלט הרגיל (stdout) מההרצה של כלי ה-CLI.
stderr

string

מקור הנתונים stderr מהרצת כלי ה-CLI.
exitCode

string (int64 format)

קוד היציאה של הרצת כלי ה-CLI.

קובץ

ייצוג JSON 
{
  "path": string,
  "contents": string
}
שדות
path

string

חובה. נתיב הקובץ ביחס לספריית הבית. אסור להשתמש בתווים '..' (מעבר לספריית האב) או בהרחבות של מעטפת.
contents

string

חובה. תוכן הקובץ.

הערות על כלים

רמז הרסני: ✅ | רמז אידמפוטנטי: ❌ | רמז לקריאה בלבד: ❌ | רמז לעולם פתוח: ❌