MCP Tools Reference: cloudcli.googleapis.com

Strumento: run_bq_command

Esegue un singolo comando dell'interfaccia a riga di comando di BigQuery (bq). Questo strumento ti consente di eseguire qualsiasi comando bq nel progetto dell'utente, inclusi i comandi che creano, aggiornano o eliminano le risorse Google Cloud (ovvero le mutazioni).

AVVISO DI SICUREZZA CRITICO (POTENZIALMENTE DISTRUTTIVO): questo strumento può creare, aggiornare o eliminare le risorse BigQuery (ad es. bq rm, bq cancel, bq query). NON è limitato ai comandi di sola lettura. Utilizza la massima cautela.

COMANDI VIETATI: un agente NON DEVE eseguire i seguenti comandi bq: bq init, bq pyshell, bq shell.

REGOLE DI ESECUZIONE RIGIDE:

  1. Nella stringa di comando DEVE essere specificato almeno uno tra --project_id o --quota_project_id.
  2. ID progetto rispetto al progetto di quota: il flag --project_id specifica il progetto di risorse su cui opera il comando (rispecchia il flag --project di gcloud). Il flag --quota_project_id specifica il progetto a cui vengono addebitati i costi di fatturazione/quota della chiamata API BigQuery downstream (rispecchia il flag --billing-project di gcloud). Se --project_id è specificato nel comando, verrà utilizzato come progetto di fatturazione/quota. Se --project_id non è specificato O se --quota_project_id è specificato in aggiunta, il progetto di fatturazione/quota sarà il progetto impostato nel flag --quota_project_id.
  3. Formattazione dei flag: DEVI sempre utilizzare il segno "=" per separare le chiavi dei flag dai relativi valori per tutte le opzioni lunghe. Corretto: '--project_id=my-project' o '--location=us'. Non corretto: '--project_id my-project' o '--location us'. Non utilizzare spazi tra i flag e i relativi valori.
  4. Nessun valore predefinito di configurazione: il comando bq viene eseguito in modo senza stato; non carica i file di configurazione locali come .bigqueryrc. Pertanto, per tutte le operazioni regionali (ad es. la creazione di un set di dati o l'esecuzione di query su un set di dati regionale), DEVI specificare esplicitamente il flag --location (ad es. --location=us o --location=EU).
  5. Operazioni asincrone: alcuni comandi avviano operazioni a lunga esecuzione sincrone (ad es. l'esecuzione di job di query). Per questi comandi DEVI SEMPRE passare il flag --nosync per evitare timeout dell'agente.
  6. Limitazioni dei comandi: NON DEVI utilizzare i seguenti comandi bq: bq init, bq pyshell, bq shell. L'incanalamento o l'incatenamento dei comandi NON è supportato.
  7. Autocorrezione: se un comando restituisce un errore, analizza stderr, correggi la sintassi o i flag e riprova nell'iterazione successiva.

Esempi di comandi bq di mutazione includono: bq mk, bq rm, bq update, bq insert, bq query (senza --dry_run) e così via. Utilizzo: RunBq(command="bq query --project_id=PROJECT_ID 'SELECT 1'", project="projects/PROJECT_ID", input_files=[{"path": "PATH", "contents": "CONTENTS"}]) Devi fornire il comando bq completo come singola stringa nel parametro "command". Devi fornire il parametro "project" (formato: projects/PROJECT_ID) come progetto di esecuzione dell'API per la fatturazione, l'abilitazione dell'API e i controlli del consumo di quota.

Esempi di comandi/pattern bq:

  1. Esegui una query: bq query --use_legacy_sql=false --project_id=PROJECT_ID 'SELECT * FROMproject.dataset.tableLIMIT 10'
  2. Crea un set di dati: bq mk --dataset --location=us --project_id=PROJECT_ID myDataset
  3. Crea una tabella: bq mk --table --project_id=PROJECT_ID myDataset.myTable name:string,value:integer
  4. Rimuovi un set di dati: bq rm -f --dataset --project_id=PROJECT_ID myDataset
  5. Rimuovi una tabella: bq rm -f -t --project_id=PROJECT_ID myDataset.myTable
  6. Aggiorna la descrizione della tabella: bq update --description="New description" --project_id=PROJECT_ID myDataset.myTable
  7. Elenca i set di dati in un progetto: bq ls --datasets=true --project_id=PROJECT_ID

Il seguente esempio di codice mostra come utilizzare curl per chiamare lo strumento MCP run_bq_command.

Richiesta 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
}'

Schema di input

Messaggio di richiesta per RunBq.

RunBqRequest

Rappresentazione JSON 
{
  "project": string,
  "command": string,
  "inputFiles": [
    {
      object (File)
    }
  ]
}
Campi
project

string

Obbligatorio. Progetto per l'abilitazione dell'API e il consumo di quota per l'API CloudCli.

Il formato deve essere projects/ o projects/
command

string

Obbligatorio. La riga di comando bq completa da eseguire come singola stringa. Esempio: "bq ls my-dataset --location=us"

I modelli linguistici di grandi dimensioni sono istruiti a utilizzare il flag --nosync per le operazioni a lunga esecuzione per evitare timeout.
inputFiles[]

object (File)

Facoltativo. File da rendere disponibili al comando bq per la sua esecuzione.

File

Rappresentazione JSON 
{
  "path": string,
  "contents": string
}
Campi
path

string

Obbligatorio. Percorso file relativo alla home directory. Non deve contenere attraversamenti della directory principale (..) o espansioni della shell.
contents

string

Obbligatorio. Contenuti del file.

Schema di output

Messaggio di risposta per RunBq.

RunBqResponse

Rappresentazione JSON 
{
  "response": {
    object (CliExecutionResponse)
  },
  "outputFiles": [
    {
      object (File)
    }
  ]
}
Campi
response

object (CliExecutionResponse)

La risposta dall'esecuzione dello strumento CLI, contenente stream stdout, stderr indipendenti e un codice di uscita.
outputFiles[]

object (File)

File generati dal comando bq dalla sua esecuzione.

CliExecutionResponse

Rappresentazione JSON 
{
  "stdout": string,
  "stderr": string,
  "exitCode": string
}
Campi
stdout

string

Lo stream stdout dall'esecuzione dello strumento CLI.
stderr

string

Lo stream stderr dall'esecuzione dello strumento CLI.
exitCode

string (int64 format)

Il codice di uscita dell'esecuzione dello strumento CLI.

File

Rappresentazione JSON 
{
  "path": string,
  "contents": string
}
Campi
path

string

Obbligatorio. Percorso file relativo alla home directory. Non deve contenere attraversamenti della directory principale (..) o espansioni della shell.
contents

string

Obbligatorio. Contenuti del file.

Annotazioni dello strumento

Suggerimento distruttivo: ✅ | Suggerimento idempotente: ❌ | Suggerimento di sola lettura: ❌ | Suggerimento open world: ❌