Compartilhar via

update comando

Atualize uma definição de entidade existente no arquivo de configuração do construtor de API de Dados. Use este comando para ajustar metadados de origem, permissões, exposição (REST/GraphQL), políticas, cache, relações, mapeamentos e metadados descritivos para uma entidade existente.

Dica

Use dab add para criar novas entidades e dab update evoluí-las. Para gerenciar metadados de campo, use --fields.name com --fields.alias, --fields.descriptione --fields.primary-key.

Sintaxe

dab update <entity-name> [options]

Olhar rápido

Opção Resumo
<entity-name> Argumento posicional necessário. Nome da entidade lógica.
-s, --source Nome da tabela de origem, exibição ou procedimento armazenado.
-m, --map Mapeamentos entre campos de banco de dados e nomes expostos.
--permissions Função e ações em role:actions formato.
--description Substitua a descrição da entidade.
-c, --config Caminho para o arquivo de configuração. A resolução padrão se aplica se omitida.
--help Exiba a tela de ajuda.
--version Exibir informações de versão.

Cache

Opção Resumo
--cache.enabled Habilitar ou desabilitar o cache de entidade.
--cache.ttl Tempo de vida útil do cache em segundos.

Fields

Opção Resumo
--fields.exclude Lista separada por vírgulas de campos excluídos.
--fields.include Lista separada por vírgulas de campos incluídos (* = todos).

Metadados de campos

Opção Resumo
--fields.name Nome da coluna de banco de dados a ser descrita.
--fields.alias Alias para o campo.
--fields.description Descrição do campo.
--fields.primary-key Defina esse campo como uma chave primária.

GraphQL

Opção Resumo
--graphql Exposição do GraphQL: false, , true, singularou singular:plural.
--graphql.operation Somente procedimentos armazenados: query ou mutation (mutação padrão).

Permissões e políticas

Opção Resumo
--permissions role:actions para uma única função. Execute várias vezes para várias funções.
--policy-database Filtro no estilo OData injetado na consulta de banco de dados.
--policy-request Filtro de solicitação de pré-base.

Relationships

Opção Resumo
--relationship Nome da relação. Use com opções de relação.
--cardinality Cardinalidade da relação: one ou many.
--target.entity Nome da entidade de destino.
--linking.object Vinculando objeto para muitos para muitos.
--linking.source.fields Vinculando campos de objeto apontando para a origem.
--linking.target.fields Vinculando campos de objeto apontando para o destino.
--relationship.fields Mapeamentos de campo para relações diretas.

REST

Opção Resumo
--rest Exposição REST: false, trueou caminho personalizado.
--rest.methods Somente procedimentos armazenados. Substitua verbos HTTP permitidos.

Mapeamentos

Opção Resumo
-m, --map Mapeamentos entre campos de banco de dados e nomes expostos.

MCP

Opção Resumo
--mcp.dml-tools Habilite ou desabilite as ferramentas DML do MCP para essa entidade.
--mcp.custom-tool Habilitar a ferramenta personalizada MCP (somente procedimentos armazenados).

Source

Opção Resumo
-s, --source Nome do objeto de banco de dados subjacente.
--source.type Tipo de origem: table, viewou stored-procedure.
--source.params Valores de parâmetro padrão para procedimentos armazenados.
--source.key-fields Campos de chave primária para exibições ou tabelas.

Parâmetros (procedimentos armazenados)

Opção Resumo
--parameters.name Lista separada por vírgulas de nomes de parâmetros.
--parameters.description Lista separada por vírgulas de descrições de parâmetro.
--parameters.required Lista separada por vírgulas de sinalizadores necessários.
--parameters.default Lista separada por vírgulas de valores padrão.

--cache.enabled

Habilite ou desabilite o cache para essa entidade.

Example

dab update \
  Book \
  --cache.enabled true

Configuração resultante

{
  "entities": {
    "Book": {
      "cache": {}
    }
  }
}

Observação

Quando o cache está habilitado (o padrão), a CLI grava um objeto vazio cache . A "enabled" propriedade só aparece explicitamente quando definida como false.

--cache.ttl

Defina o tempo de vida útil do cache em segundos. Só será eficaz se o cache estiver habilitado.

Example

dab update \
  Book \
  --cache.ttl 600

Configuração resultante

{
  "entities": {
    "Book": {
      "cache": {
        "ttl-seconds": 600
      }
    }
  }
}

Observação

O fornecimento de TTL (vida útil) quando o cache está desabilitado não tem efeito até que o cache esteja habilitado.

--description

Substitua a descrição da entidade.

Observação

Essa opção está disponível na 2.0.0-rc CLI. O Construtor de API de Dados 2.0 está atualmente em versão prévia. Instalar com dotnet tool install microsoft.dataapibuilder --version 2.0.0-rc --prerelease.

Example

dab update \
  Book \
  --description "Updated description"

Configuração resultante

{
  "entities": {
    "Book": {
      "description": "Updated description"
    }
  }
}

--fields.exclude

Lista separada por vírgulas de campos a serem excluídos.

Example

dab update \
  Book \
  --permissions "anonymous:read" \
  --fields.exclude "internal_flag,secret_note"

Configuração resultante

{
  "entities": {
    "Book": {
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "read",
              "fields": {
                "exclude": [ "internal_flag", "secret_note" ]
              }
            }
          ]
        }
      ]
    }
  }
}

--fields.include

Lista separada por vírgulas de campos a serem incluídos. * inclui todos os campos. Substitui a lista de inclusões existente.

Example

dab update \
  Book \
  --permissions "anonymous:read" \
  --fields.include "id,title,author"

Configuração resultante

{
  "entities": {
    "Book": {
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "read",
              "fields": {
                "exclude": [],
                "include": [ "id", "title", "author" ]
              }
            }
          ]
        }
      ]
    }
  }
}

--graphql

Controlar a exposição do GraphQL.

Example

dab update \
  Book \
  --graphql book:books

Configuração resultante

{
  "entities": {
    "Book": {
      "graphql": {
        "enabled": true,
        "type": {
          "singular": "book",
          "plural": "books"
        }
      }
    }
  }
}

--graphql.operation

Somente procedimentos armazenados. Define o tipo de operação. O padrão é mutation.

Example

dab update \
  RunReport \
  --graphql.operation query

Configuração resultante

{
  "entities": {
    "RunReport": {
      "graphql": {
        "operation": "query"
      }
    }
  }
}

Observação

O fornecimento de --graphql.operation tabelas ou exibições é ignorado.

--permissions

Adiciona ou atualiza permissões para uma única função e suas ações.

Você pode executar dab update várias vezes (uma vez por função) para adicionar várias funções.

Example

dab update \
  Book \
  --permissions "anonymous:read"

dab update \
  Book \
  --permissions "authenticated:create,read,update"

Configuração resultante

{
  "entities": {
    "Book": {
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "read"
            }
          ]
        },
        {
          "role": "authenticated",
          "actions": [
            { "action": "create" },
            { "action": "read" },
            { "action": "update" }
          ]
        }
      ]
    }
  }
}

Observação

Se a função especificada já existir, suas ações serão atualizadas; caso contrário, a função será adicionada.

--policy-database

Filtro no estilo OData acrescentado à consulta de banco de dados.

Example

dab update \
  Book \
  --permissions "anonymous:read" \
  --policy-database "region eq 'US'"

Configuração resultante

{
  "entities": {
    "Book": {
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "read",
              "policy": {
                "database": "region eq 'US'"
              }
            }
          ]
        }
      ]
    }
  }
}

--policy-request

Política de nível de solicitação avaliada antes de atingir o banco de dados.

Example

dab update \
  Book \
  --permissions "anonymous:read" \
  --policy-request "@claims.role == 'admin'"

Configuração resultante

{
  "entities": {
    "Book": {
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "read",
              "policy": {
                "request": "@claims.role == 'admin'"
              }
            }
          ]
        }
      ]
    }
  }
}

--relationship

Defina ou atualize uma relação. Use com outras opções de relação.

Example

dab update \
  User \
  --relationship profile \
  --target.entity Profile \
  --cardinality one \
  --relationship.fields "id:user_id"

Configuração resultante

{
  "entities": {
    "User": {
      "relationships": {
        "profile": {
          "cardinality": "one",
          "target.entity": "Profile",
          "source.fields": [ "id" ],
          "target.fields": [ "user_id" ],
          "linking.source.fields": [],
          "linking.target.fields": []
        }
      }
    }
  }
}

--cardinality

Cardinalidade para a relação. Usar com o --relationship.

Example

dab update \
  User \
  --relationship profile \
  --target.entity Profile \
  --cardinality one \
  --relationship.fields "id:user_id"

--target.entity

Nome da entidade de destino para a relação. Usar com o --relationship.

Example

dab update \
  User \
  --relationship profile \
  --target.entity Profile \
  --cardinality one \
  --relationship.fields "id:user_id"

--linking.object

Somente muitos para muitos. Nome do objeto de banco de dados a ser usado como o objeto de vinculação.

Example

dab update \
  Book \
  --relationship books_authors \
  --target.entity Author \
  --cardinality many \
  --relationship.fields "id:id" \
  --linking.object dbo.books_authors \
  --linking.source.fields book_id \
  --linking.target.fields author_id

--linking.source.fields

Somente muitos para muitos. Lista separada por vírgulas de vinculação de campos de objeto apontando para a entidade de origem.

Example

dab update \
  Book \
  --relationship books_authors \
  --target.entity Author \
  --cardinality many \
  --relationship.fields "id:id" \
  --linking.object dbo.books_authors \
  --linking.source.fields book_id \
  --linking.target.fields author_id

--linking.target.fields

Somente muitos para muitos. Lista separada por vírgulas de vinculação de campos de objeto apontando para a entidade de destino.

Example

dab update \
  Book \
  --relationship books_authors \
  --target.entity Author \
  --cardinality many \
  --relationship.fields "id:id" \
  --linking.object dbo.books_authors \
  --linking.source.fields book_id \
  --linking.target.fields author_id

--relationship.fields

Mapeamentos de campo separados por dois-pontos para relações diretas.

O --relationship.fields valor é uma lista separada por vírgulas de sourceField:targetField pares.

Example

dab update \
  User \
  --relationship profile \
  --target.entity Profile \
  --cardinality one \
  --relationship.fields "id:user_id"

Configuração resultante

{
  "entities": {
    "User": {
      "relationships": {
        "profile": {
          "cardinality": "one",
          "target.entity": "Profile",
          "source.fields": [ "id" ],
          "target.fields": [ "user_id" ],
          "linking.source.fields": [],
          "linking.target.fields": []
        }
      }
    }
  }
}

--rest

Controlar a exposição rest.

Example

dab update \
  Book \
  --rest BooksApi

Configuração resultante

{
  "entities": {
    "Book": {
      "rest": {
        "enabled": true,
        "path": "/BooksApi"
      }
    }
  }
}

--rest.methods

Somente procedimentos armazenados. Substitua os métodos HTTP permitidos. O padrão é POST.

Example

dab update \
  RunReport \
  --rest true \
  --rest.methods GET,POST

Configuração resultante

{
  "entities": {
    "RunReport": {
      "rest": {
        "enabled": true,
        "methods": [ "get", "post" ]
      }
    }
  }
}

Observação

O fornecimento --rest.methods enquanto REST está desabilitado não tem efeito.

-s, --source

Atualize o objeto de banco de dados subjacente.

Example

dab update \
  Book \
  --source dbo.Books

Configuração resultante

{
  "entities": {
    "Book": {
      "source": {
        "object": "dbo.Books",
        "type": "table"
      }
    }
  }
}

--source.type

Altere o tipo de objeto de origem.

Observação

As exibições exigem --source.key-fields. Alterar para view sem especificar campos-chave produz um erro.

Example

dab update \
  Book \
  --source.type view \
  --source.key-fields "id"

Configuração resultante

{
  "entities": {
    "Book": {
      "source": {
        "type": "view",
        "object": "Book"
      },
      "fields": [
        {
          "name": "id",
          "primary-key": true
        }
      ]
    }
  }
}

--source.params

Somente procedimentos armazenados. Valores de parâmetro padrão como name:value pares.

Example

dab update \
  RunReport \
  --source.params "startDate:2024-01-01,endDate:2024-12-31"

Configuração resultante

{
  "entities": {
    "RunReport": {
      "source": {
        "type": "stored-procedure",
        "parameters": [
          {
            "name": "startDate",
            "required": false,
            "default": "2024-01-01"
          },
          {
            "name": "endDate",
            "required": false,
            "default": "2024-12-31"
          }
        ]
      }
    }
  }
}

--source.key-fields

Especifique os campos de chave primária para exibições ou tabelas sem uma chave inferida.

Example

dab update \
  Book \
  --source.type view \
  --source.key-fields "id"

Configuração resultante

{
  "entities": {
    "Book": {
      "source": {
        "type": "view",
        "object": "Book"
      },
      "fields": [
        {
          "name": "id",
          "primary-key": true
        }
      ]
    }
  }
}

Observação

Os modos de exibição sempre exigem campos-chave. A --source.key-fields opção adiciona entradas à fields matriz com "primary-key": true.

-m, --map

Especifique mapeamentos entre nomes de coluna de banco de dados e nomes de campo REST/GraphQL expostos.

Example

dab update \
  Book \
  --map "id:bookId,title:bookTitle"

Configuração resultante

{
  "entities": {
    "Book": {
      "fields": [
        {
          "name": "id",
          "alias": "bookId",
          "primary-key": false
        },
        {
          "name": "title",
          "alias": "bookTitle",
          "primary-key": false
        }
      ]
    }
  }
}

Observação

A --map opção cria entradas na fields matriz com o alias conjunto de propriedades.

--parameters.name

Somente procedimentos armazenados. Lista separada por vírgulas de nomes de parâmetros.

Observação

Essa opção está disponível na 2.0.0-rc CLI. O Construtor de API de Dados 2.0 está atualmente em versão prévia. Instalar com dotnet tool install microsoft.dataapibuilder --version 2.0.0-rc --prerelease.

Dica

Para definir parâmetros de procedimento armazenado, use --parameters.name com --parameters.description, --parameters.requirede --parameters.default.

Example

dab update \
  GetOrdersByDateRange \
  --parameters.name "StartDate,EndDate" \
  --parameters.required "true,true" \
  --parameters.description "Beginning of date range,End of date range"

Configuração resultante

{
  "entities": {
    "GetOrdersByDateRange": {
      "source": {
        "parameters": [
          {
            "name": "StartDate",
            "description": "Beginning of date range",
            "required": true
          },
          {
            "name": "EndDate",
            "description": "End of date range",
            "required": true
          }
        ]
      }
    }
  }
}

--parameters.description

Somente procedimentos armazenados. Lista separada por vírgulas de descrições de parâmetro alinhadas a --parameters.name.

Observação

Essa opção está disponível na 2.0.0-rc CLI. O Construtor de API de Dados 2.0 está atualmente em versão prévia. Instalar com dotnet tool install microsoft.dataapibuilder --version 2.0.0-rc --prerelease.

Example

dab update \
  GetOrdersByDateRange \
  --parameters.name "StartDate,EndDate" \
  --parameters.description "Beginning of date range,End of date range"

--parameters.required

Somente procedimentos armazenados. Lista separada por vírgulas de true/false valores alinhados a --parameters.name.

Observação

Essa opção está disponível na 2.0.0-rc CLI. O Construtor de API de Dados 2.0 está atualmente em versão prévia. Instalar com dotnet tool install microsoft.dataapibuilder --version 2.0.0-rc --prerelease.

Example

dab update \
  GetOrdersByDateRange \
  --parameters.name "StartDate,EndDate" \
  --parameters.required "true,true"

--parameters.default

Somente procedimentos armazenados. Lista separada por vírgulas de valores padrão alinhados a --parameters.name.

Observação

Essa opção está disponível na 2.0.0-rc CLI. O Construtor de API de Dados 2.0 está atualmente em versão prévia. Instalar com dotnet tool install microsoft.dataapibuilder --version 2.0.0-rc --prerelease.

Example

dab update \
  GetOrdersByDateRange \
  --parameters.name "CustomerID" \
  --parameters.default "null"

--fields.name

Nome da coluna de banco de dados a ser descrita.

Observação

Essa opção está disponível na 2.0.0-rc CLI. O Construtor de API de Dados 2.0 está atualmente em versão prévia. Instalar com dotnet tool install microsoft.dataapibuilder --version 2.0.0-rc --prerelease.

Example

dab update \
  Products \
  --fields.name Id \
  --fields.primary-key true \
  --fields.description "Product Id"

Configuração resultante

{
  "entities": {
    "Products": {
      "fields": [
        {
          "name": "Id",
          "description": "Product Id",
          "primary-key": true
        }
      ]
    }
  }
}

--fields.alias

Alias para o campo. Use uma lista separada por vírgulas alinhada a --fields.name.

Observação

Essa opção está disponível na 2.0.0-rc CLI. O Construtor de API de Dados 2.0 está atualmente em versão prévia. Instalar com dotnet tool install microsoft.dataapibuilder --version 2.0.0-rc --prerelease.

Dica

Use --fields.alias com --fields.name para definir nomes de campo expostos.

Example

dab update \
  Products \
  --fields.name "Id,Title" \
  --fields.alias "product_id,product_title"

--fields.description

Descrição do campo. Use uma lista separada por vírgulas alinhada a --fields.name.

Observação

Essa opção está disponível na 2.0.0-rc CLI. O Construtor de API de Dados 2.0 está atualmente em versão prévia. Instalar com dotnet tool install microsoft.dataapibuilder --version 2.0.0-rc --prerelease.

Example

dab update \
  Products \
  --fields.name Id \
  --fields.description "Product Id"

--fields.primary-key

Sinalizador de chave primária para o campo. Use uma lista separada por vírgulas de true/false valores alinhados a --fields.name.

Observação

Essa opção está disponível na 2.0.0-rc CLI. O Construtor de API de Dados 2.0 está atualmente em versão prévia. Instalar com dotnet tool install microsoft.dataapibuilder --version 2.0.0-rc --prerelease.

Dica

Use --fields.primary-key com --fields.name para definir campos de chave primária para exibições ou tabelas sem uma chave inferida.

Example

dab update \
  SalesSummary \
  --fields.name "year,region" \
  --fields.primary-key "true,true"

Configuração resultante

{
  "entities": {
    "SalesSummary": {
      "fields": [
        {
          "name": "year",
          "primary-key": true
        },
        {
          "name": "region",
          "primary-key": true
        }
      ]
    }
  }
}

--mcp.dml-tools

Habilite ou desabilite as ferramentas de DML do MCP (linguagem de manipulação de dados) para essa entidade. O padrão é true.

Observação

Essa opção está disponível na 2.0.0-rc CLI. O Construtor de API de Dados 2.0 está atualmente em versão prévia. Instalar com dotnet tool install microsoft.dataapibuilder --version 2.0.0-rc --prerelease.

Example

dab update \
  Book \
  --mcp.dml-tools false

Configuração resultante

{
  "entities": {
    "Book": {
      "mcp": {
        "dml-tools": false
      }
    }
  }
}

Observação

Quando --mcp.dml-tools for usado, defina mcp usando o formulário de objeto para que a configuração seja explícita.

--mcp.custom-tool

Somente procedimentos armazenados. Habilite a ferramenta personalizada MCP para essa entidade. O padrão é false.

Observação

Essa opção está disponível na 2.0.0-rc CLI. O Construtor de API de Dados 2.0 está atualmente em versão prévia. Instalar com dotnet tool install microsoft.dataapibuilder --version 2.0.0-rc --prerelease.

Example

dab update \
  RunReport \
  --mcp.custom-tool true

Configuração resultante

{
  "entities": {
    "RunReport": {
      "mcp": {
        "custom-tool": true
      }
    }
  }
}

-c, --config

Caminho para o arquivo de configuração.

Example

dab update \
  Book \
  --description "Updated description" \
  --config dab-config.json

--help

Exiba a tela de ajuda.

Example

dab update --help

--version

Exibir informações de versão.

Example

dab update --version

Importante

Alterar o tipo de origem pode invalidar outras propriedades. Por exemplo, as exibições sempre exigem campos-chave; os procedimentos armazenados não podem definir campos-chave.

  • Last updated on