MCP Tools Reference: dataform.googleapis.com

Ferramenta: create_workflow_invocation

Cria uma nova invocação de fluxo de trabalho em um determinado repositório do Dataform.

O valor de parâmetro parent precisa estar no formato projects/{project_id}/locations/{location}/repositories/{repository}.

O valor do parâmetro compilation_result ou workflow_config é obrigatório.

  • Se você usar compilation_result, o valor de parâmetro precisará estar no formato projects/{project_id}/locations/{location}/repositories/{repository}/compilationResults/{compilation_result}.
  • Se você usar workflow_config, o valor de parâmetro precisará estar no formato projects/{project_id}/locations/{location}/repositories/{repository}/workflowConfigs/{workflow_config}.

Pré-requisito: para acionar uma invocação, primeiro crie um compilation_result usando a ferramenta create_compilation_result ou um workflow_config usando a ferramenta create_workflow_config. Não é possível acionar uma invocação diretamente do código bruto do repositório.

A invocação do fluxo de trabalho é executada em uma conta de serviço determinada pela origem da compilação:

  • Se você estiver usando compilation_result, defina o valor do parâmetro invocationConfig.serviceAccount. Se omitido, o service_account padrão do repositório será usado.
  • Se você estiver usando workflow_config, não defina o parâmetro invocationConfig. A invocação é executada automaticamente na conta de serviço configurada nessa configuração de fluxo de trabalho.

A conta de serviço não pode ser o agente de serviço padrão do Dataform. A conta de serviço precisa ter as permissões necessárias para executar o fluxo de trabalho, e o usuário precisa estar autorizado a atuar como a conta de serviço selecionada. Essa autorização geralmente é concedida pelo papel de Usuário da conta de serviço (roles/iam.serviceAccountUser), que pode ser concedido na própria conta de serviço ou no projeto que a contém.

O exemplo de código a seguir mostra como usar curl para chamar a ferramenta MCP create_workflow_invocation.

Solicitação curl 
curl --location 'https://dataform.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "create_workflow_invocation",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Esquema de entrada

Mensagem de solicitação CreateWorkflowInvocation.

CreateWorkflowInvocationRequest

Representação JSON 
{
  "parent": string,
  "workflowInvocation": {
    object (WorkflowInvocation)
  }
}
Campos
parent

string

Obrigatório. O repositório em que a invocação do fluxo de trabalho será criada. Precisa estar no formato projects/*/locations/*/repositories/*.
workflowInvocation

object (WorkflowInvocation)

Obrigatório. O recurso de invocação de fluxo de trabalho a ser criado.

WorkflowInvocation

Representação JSON 
{
  "name": string,
  "invocationConfig": {
    object (InvocationConfig)
  },
  "state": enum (State),
  "invocationTiming": {
    object (Interval)
  },
  "resolvedCompilationResult": string,
  "dataEncryptionState": {
    object (DataEncryptionState)
  },
  "privateResourceMetadata": {
    object (PrivateResourceMetadata)
  },
  "pipelineConfig": {
    object (PipelineConfig)
  },

  // Union field compilation_source can be only one of the following:
  "compilationResult": string,
  "workflowConfig": string
  // End of list of possible types for union field compilation_source.

  // Union field _internal_metadata can be only one of the following:
  "internalMetadata": string
  // End of list of possible types for union field _internal_metadata.
}
Campos
name

string

Apenas saída. O nome da invocação do fluxo de trabalho.
invocationConfig

object (InvocationConfig)

Imutável. Se não for definido, um InvocationConfig padrão será usado.
state

enum (State)

Apenas saída. O estado atual desta invocação de fluxo de trabalho.
invocationTiming

object (Interval)

Apenas saída. Detalhes de tempo desta invocação de fluxo de trabalho.
resolvedCompilationResult

string

Apenas saída. O resultado da compilação resolvido que foi usado para criar essa invocação. Estará no formato projects/*/locations/*/repositories/*/compilationResults/*.
dataEncryptionState

object (DataEncryptionState)

Apenas saída. Só é definido se o repositório tiver uma chave do KMS.
privateResourceMetadata

object (PrivateResourceMetadata)

Apenas saída. Metadados que indicam se este recurso tem escopo de usuário. O recurso WorkflowInvocation é user_scoped somente se for originado de um resultado de compilação e esse resultado estiver no escopo do usuário.
pipelineConfig

object (PipelineConfig)

Apenas saída. As opções de pipeline que definem o tipo e o caminho do pipeline no repositório Git.
Campo de união compilation_source. A origem do resultado da compilação a ser usada para esta invocação. compilation_source pode ser apenas de um dos tipos a seguir:
compilationResult

string

Imutável. O nome do resultado da compilação a ser usado para esta invocação. Precisa estar no formato projects/*/locations/*/repositories/*/compilationResults/*.
workflowConfig

string

Imutável. O nome da configuração de fluxo de trabalho a ser invocada. Precisa estar no formato projects/*/locations/*/repositories/*/workflowConfigs/*.

Campo de união _internal_metadata.

_internal_metadata pode ser apenas de um dos tipos a seguir:
internalMetadata

string

Apenas saída. Todas as informações de metadados usadas internamente para veicular o recurso. Por exemplo: carimbos de data/hora, flags, campos de status etc. O formato desse campo é uma string JSON.

InvocationConfig

Representação JSON 
{
  "includedTargets": [
    {
      object (Target)
    }
  ],
  "includedTags": [
    string
  ],
  "transitiveDependenciesIncluded": boolean,
  "transitiveDependentsIncluded": boolean,
  "fullyRefreshIncrementalTablesEnabled": boolean,
  "serviceAccount": string,

  // Union field _query_priority can be only one of the following:
  "queryPriority": enum (QueryPriority)
  // End of list of possible types for union field _query_priority.
}
Campos
includedTargets[]

object (Target)

Opcional. O conjunto de identificadores de ação a serem incluídos.
includedTags[]

string

Opcional. O conjunto de tags a serem incluídas.
transitiveDependenciesIncluded

boolean

Opcional. Quando definido como "true", as dependências transitivas das ações incluídas serão executadas.
transitiveDependentsIncluded

boolean

Opcional. Quando definido como "true", as dependências transitivas das ações incluídas serão executadas.
fullyRefreshIncrementalTablesEnabled

boolean

Opcional. Quando definido como "true", todas as tabelas incrementais serão atualizadas por completo.
serviceAccount

string

Opcional. A conta de serviço para executar invocações de fluxo de trabalho.

Campo de união _query_priority.

_query_priority pode ser apenas de um dos tipos a seguir:
queryPriority

enum (QueryPriority)

Opcional. Especifica a prioridade da execução de consultas no BigQuery. Para mais informações, acesse https://cloud.google.com/bigquery/docs/running-queries#queries.

Destino

Representação JSON 
{
  "database": string,
  "schema": string,
  "name": string
}
Campos
database

string

Opcional. O banco de dados da ação (ID do projeto do Google Cloud) .
schema

string

Opcional. O esquema da ação (ID do conjunto de dados do BigQuery), em database.
name

string

Opcional. O nome da ação, dentro de database e schema.

Intervalo

Representação JSON 
{
  "startTime": string,
  "endTime": string
}
Campos
startTime

string (Timestamp format)

Opcional. Início inclusivo do intervalo.

Se especificado, um carimbo de data/hora correspondente a esse intervalo precisará ser igual ou posterior ao início.

Usa o padrão RFC 3339, em que a saída gerada é sempre convertida em Z e tem 0, 3, 6 ou 9 dígitos fracionários. Além de Z, outros ajustes também são aceitos. Exemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".
endTime

string (Timestamp format)

Opcional. Fim exclusivo do intervalo.

Se especificado, um carimbo de data/hora correspondente a esse intervalo precisará ser anterior ao fim.

Usa o padrão RFC 3339, em que a saída gerada é sempre convertida em Z e tem 0, 3, 6 ou 9 dígitos fracionários. Além de Z, outros ajustes também são aceitos. Exemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".

Carimbo de data/hora

Representação JSON 
{
  "seconds": string,
  "nanos": integer
}
Campos
seconds

string (int64 format)

Representa os segundos do horário UTC desde a época Unix 1970-01-01T00:00:00Z. Precisa estar entre -62135596800 e 253402300799 (o que corresponde a 0001-01-01T00:00:00Z a 9999-12-31T23:59:59Z).
nanos

integer

Frações não negativas de um segundo com resolução de nanossegundos. Esse campo é a parte de nanossegundos da duração, não uma alternativa aos segundos. Os valores de segundos negativos com frações ainda precisam ter valores em nanossegundos não negativos que representam períodos posteriores. O valor precisa ser de 0 a 999.999.999 (inclusive).

DataEncryptionState

Representação JSON 
{
  "kmsKeyVersionName": string
}
Campos
kmsKeyVersionName

string

Obrigatório. O nome da versão da chave do KMS com que os dados de um recurso são criptografados.

PrivateResourceMetadata

Representação JSON 
{
  "userScoped": boolean
}
Campos
userScoped

boolean

Apenas saída. Se for "true", esse recurso terá escopo de usuário, ou seja, será um espaço de trabalho ou terá origem em um espaço de trabalho.

PipelineConfig

Representação JSON 
{
  "pipelineType": enum (PipelineType),
  "path": string
}
Campos
pipelineType

enum (PipelineType)

Obrigatório. O tipo do pipeline.
path

string

Obrigatório. O caminho relativo no repositório Git em que o pipeline está definido. Por exemplo, para um pipeline do Dataform, é um caminho para a pasta em que workflow_settings.yaml ou dataform.json está localizado.

QueryPriority

Tipos de prioridade para execução de consultas no BigQuery.

Tipos enumerados
QUERY_PRIORITY_UNSPECIFIED Valor padrão. Esse valor não é usado.
INTERACTIVE A consulta será executada no BigQuery com prioridade interativa. Para mais informações, acesse https://cloud.google.com/bigquery/docs/running-queries#queries.
BATCH A consulta será executada no BigQuery com prioridade de lote. Para mais informações, acesse https://cloud.google.com/bigquery/docs/running-queries#batchqueries.

Estado

Representa o estado atual de uma invocação de fluxo de trabalho.

Tipos enumerados
STATE_UNSPECIFIED Valor padrão. Esse valor não é usado.
RUNNING A invocação do fluxo de trabalho está em execução.
SUCCEEDED A invocação do fluxo de trabalho foi concluída. Um estado terminal.
CANCELLED A invocação do fluxo de trabalho foi cancelada. Um estado terminal.
FAILED A invocação do fluxo de trabalho falhou. Um estado terminal.
CANCELING A invocação do fluxo de trabalho está sendo cancelada, mas algumas ações ainda estão em execução.

PipelineType

O tipo do pipeline. Isso pode ser estendido no futuro. Em caso de UNSPECIFIED, o erro será gerado.

Tipos enumerados
PIPELINE_TYPE_UNSPECIFIED Valor padrão. Esse valor não é usado.
DATAFORM Pipeline regular do Dataform.
SQL Ativo de arquivo único SQL.
NOTEBOOK Ativo de arquivo único do notebook.

Esquema de saída

Representa uma única invocação de um resultado de compilação.

WorkflowInvocation

Representação JSON 
{
  "name": string,
  "invocationConfig": {
    object (InvocationConfig)
  },
  "state": enum (State),
  "invocationTiming": {
    object (Interval)
  },
  "resolvedCompilationResult": string,
  "dataEncryptionState": {
    object (DataEncryptionState)
  },
  "privateResourceMetadata": {
    object (PrivateResourceMetadata)
  },
  "pipelineConfig": {
    object (PipelineConfig)
  },

  // Union field compilation_source can be only one of the following:
  "compilationResult": string,
  "workflowConfig": string
  // End of list of possible types for union field compilation_source.

  // Union field _internal_metadata can be only one of the following:
  "internalMetadata": string
  // End of list of possible types for union field _internal_metadata.
}
Campos
name

string

Apenas saída. O nome da invocação do fluxo de trabalho.
invocationConfig

object (InvocationConfig)

Imutável. Se não for definido, um InvocationConfig padrão será usado.
state

enum (State)

Apenas saída. O estado atual desta invocação de fluxo de trabalho.
invocationTiming

object (Interval)

Apenas saída. Detalhes de tempo desta invocação de fluxo de trabalho.
resolvedCompilationResult

string

Apenas saída. O resultado da compilação resolvido que foi usado para criar essa invocação. Estará no formato projects/*/locations/*/repositories/*/compilationResults/*.
dataEncryptionState

object (DataEncryptionState)

Apenas saída. Só é definido se o repositório tiver uma chave do KMS.
privateResourceMetadata

object (PrivateResourceMetadata)

Apenas saída. Metadados que indicam se este recurso tem escopo de usuário. O recurso WorkflowInvocation é user_scoped somente se for originado de um resultado de compilação e esse resultado estiver no escopo do usuário.
pipelineConfig

object (PipelineConfig)

Apenas saída. As opções de pipeline que definem o tipo e o caminho do pipeline no repositório Git.
Campo de união compilation_source. A origem do resultado da compilação a ser usada para esta invocação. compilation_source pode ser apenas de um dos tipos a seguir:
compilationResult

string

Imutável. O nome do resultado da compilação a ser usado para esta invocação. Precisa estar no formato projects/*/locations/*/repositories/*/compilationResults/*.
workflowConfig

string

Imutável. O nome da configuração de fluxo de trabalho a ser invocada. Precisa estar no formato projects/*/locations/*/repositories/*/workflowConfigs/*.

Campo de união _internal_metadata.

_internal_metadata pode ser apenas de um dos tipos a seguir:
internalMetadata

string

Apenas saída. Todas as informações de metadados usadas internamente para veicular o recurso. Por exemplo: carimbos de data/hora, flags, campos de status etc. O formato desse campo é uma string JSON.

InvocationConfig

Representação JSON 
{
  "includedTargets": [
    {
      object (Target)
    }
  ],
  "includedTags": [
    string
  ],
  "transitiveDependenciesIncluded": boolean,
  "transitiveDependentsIncluded": boolean,
  "fullyRefreshIncrementalTablesEnabled": boolean,
  "serviceAccount": string,

  // Union field _query_priority can be only one of the following:
  "queryPriority": enum (QueryPriority)
  // End of list of possible types for union field _query_priority.
}
Campos
includedTargets[]

object (Target)

Opcional. O conjunto de identificadores de ação a serem incluídos.
includedTags[]

string

Opcional. O conjunto de tags a serem incluídas.
transitiveDependenciesIncluded

boolean

Opcional. Quando definido como "true", as dependências transitivas das ações incluídas serão executadas.
transitiveDependentsIncluded

boolean

Opcional. Quando definido como "true", as dependências transitivas das ações incluídas serão executadas.
fullyRefreshIncrementalTablesEnabled

boolean

Opcional. Quando definido como "true", todas as tabelas incrementais serão atualizadas por completo.
serviceAccount

string

Opcional. A conta de serviço para executar invocações de fluxo de trabalho.

Campo de união _query_priority.

_query_priority pode ser apenas de um dos tipos a seguir:
queryPriority

enum (QueryPriority)

Opcional. Especifica a prioridade da execução de consultas no BigQuery. Para mais informações, acesse https://cloud.google.com/bigquery/docs/running-queries#queries.

Destino

Representação JSON 
{
  "database": string,
  "schema": string,
  "name": string
}
Campos
database

string

Opcional. O banco de dados da ação (ID do projeto do Google Cloud) .
schema

string

Opcional. O esquema da ação (ID do conjunto de dados do BigQuery), em database.
name

string

Opcional. O nome da ação, dentro de database e schema.

Intervalo

Representação JSON 
{
  "startTime": string,
  "endTime": string
}
Campos
startTime

string (Timestamp format)

Opcional. Início inclusivo do intervalo.

Se especificado, um carimbo de data/hora correspondente a esse intervalo precisará ser igual ou posterior ao início.

Usa o padrão RFC 3339, em que a saída gerada é sempre convertida em Z e tem 0, 3, 6 ou 9 dígitos fracionários. Além de Z, outros ajustes também são aceitos. Exemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".
endTime

string (Timestamp format)

Opcional. Fim exclusivo do intervalo.

Se especificado, um carimbo de data/hora correspondente a esse intervalo precisará ser anterior ao fim.

Usa o padrão RFC 3339, em que a saída gerada é sempre convertida em Z e tem 0, 3, 6 ou 9 dígitos fracionários. Além de Z, outros ajustes também são aceitos. Exemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".

Carimbo de data/hora

Representação JSON 
{
  "seconds": string,
  "nanos": integer
}
Campos
seconds

string (int64 format)

Representa os segundos do horário UTC desde a época Unix 1970-01-01T00:00:00Z. Precisa estar entre -62135596800 e 253402300799 (o que corresponde a 0001-01-01T00:00:00Z a 9999-12-31T23:59:59Z).
nanos

integer

Frações não negativas de um segundo com resolução de nanossegundos. Esse campo é a parte de nanossegundos da duração, não uma alternativa aos segundos. Os valores de segundos negativos com frações ainda precisam ter valores em nanossegundos não negativos que representam períodos posteriores. O valor precisa ser de 0 a 999.999.999 (inclusive).

DataEncryptionState

Representação JSON 
{
  "kmsKeyVersionName": string
}
Campos
kmsKeyVersionName

string

Obrigatório. O nome da versão da chave do KMS com que os dados de um recurso são criptografados.

PrivateResourceMetadata

Representação JSON 
{
  "userScoped": boolean
}
Campos
userScoped

boolean

Apenas saída. Se for "true", esse recurso terá escopo de usuário, ou seja, será um espaço de trabalho ou terá origem em um espaço de trabalho.

PipelineConfig

Representação JSON 
{
  "pipelineType": enum (PipelineType),
  "path": string
}
Campos
pipelineType

enum (PipelineType)

Obrigatório. O tipo do pipeline.
path

string

Obrigatório. O caminho relativo no repositório Git em que o pipeline está definido. Por exemplo, para um pipeline do Dataform, é um caminho para a pasta em que workflow_settings.yaml ou dataform.json está localizado.

QueryPriority

Tipos de prioridade para execução de consultas no BigQuery.

Tipos enumerados
QUERY_PRIORITY_UNSPECIFIED Valor padrão. Esse valor não é usado.
INTERACTIVE A consulta será executada no BigQuery com prioridade interativa. Para mais informações, acesse https://cloud.google.com/bigquery/docs/running-queries#queries.
BATCH A consulta será executada no BigQuery com prioridade de lote. Para mais informações, acesse https://cloud.google.com/bigquery/docs/running-queries#batchqueries.

Estado

Representa o estado atual de uma invocação de fluxo de trabalho.

Tipos enumerados
STATE_UNSPECIFIED Valor padrão. Esse valor não é usado.
RUNNING A invocação do fluxo de trabalho está em execução.
SUCCEEDED A invocação do fluxo de trabalho foi concluída. Um estado terminal.
CANCELLED A invocação do fluxo de trabalho foi cancelada. Um estado terminal.
FAILED A invocação do fluxo de trabalho falhou. Um estado terminal.
CANCELING A invocação do fluxo de trabalho está sendo cancelada, mas algumas ações ainda estão em execução.

PipelineType

O tipo do pipeline. Isso pode ser estendido no futuro. Em caso de UNSPECIFIED, o erro será gerado.

Tipos enumerados
PIPELINE_TYPE_UNSPECIFIED Valor padrão. Esse valor não é usado.
DATAFORM Pipeline regular do Dataform.
SQL Ativo de arquivo único SQL.
NOTEBOOK Ativo de arquivo único do notebook.

Anotações de ferramentas

As anotações de ferramentas são enviadas aos clientes do MCP para descrever o risco básico de uma determinada ferramenta. A maioria dos clientes trata essas dicas como não confiáveis, mas elas podem ser usadas para decidir quando um pedido de confirmação pode ser enviado a um usuário.

Além da string de título, as seguintes dicas booleanas são definidas da seguinte maneira:

  • readOnlyHint: se for "true", a ferramenta não vai modificar o ambiente. Padrão: false.
  • destructiveHint: se for "true", a ferramenta poderá realizar ações destrutivas. Se for "false", a ferramenta só poderá realizar ações aditivas. Padrão: verdadeiro.
  • idempotentHint: se for "true", chamar a ferramenta repetidamente com os mesmos argumentos não terá efeito adicional no ambiente dela. Padrão: false.
  • openWorldHint: se for "true", a ferramenta poderá interagir com um "mundo aberto" de entidades externas. Se for "false", a ferramenta só poderá interagir com entidades internas. Por exemplo, uma ferramenta de pesquisa na Web seria de mundo aberto, enquanto uma ferramenta de memória não seria.

Dica destrutiva: ❌ | Dica idempotente: ❌ | Dica somente leitura: ❌ | Dica de mundo aberto: ❌