Parâmetros e propriedades da ação Extract do SqlPackage

  • Artigo

A ação Extract do SqlPackage cria um esquema de um banco de dados conectado a um arquivo DACPAC (.dacpac). Por padrão, os dados não são incluídos no arquivo .dacpac. Para incluir dados, use a opção Exportar ação ou as propriedades de extração ExtractAllTableData/TableData.

Observação

Embora o Microsoft Entra ID seja o novo nome do Azure Active Directory (Azure AD), para evitar a interrupção de ambientes existentes, o Azure AD ainda permanecerá em alguns elementos codificados, como campos de interface do usuário, provedores de conexão, códigos de erro e cmdlets. Neste artigo, os dois nomes são intercambiáveis.

Sintaxe da linha de comando

O SqlPackage inicia as ações especificadas usando os parâmetros, as propriedades e as variáveis do sqlcmd especificados na linha de comando.

SqlPackage /Action:Extract {parameters} {properties}

Observação

Quando um banco de dados com as credenciais de senha (por exemplo, um usuário de autenticação do SQL) é extraído, a senha é substituída por outra senha de complexidade adequada. Os usuários do SqlPackage ou do DacFx devem alterar a senha após a publicação do DACPAC.

Exemplos

# example extract to create a schema-only .dacpac file connecting using SQL authentication
SqlPackage /Action:Extract /TargetFile:{filename}.dacpac /DiagnosticsFile:{logFile}.log /p:ExtractAllTableData=false /p:VerifyExtraction=true \
    /SourceServerName:{serverFQDN} /SourceDatabaseName:{databaseName} /SourceUser:{username} /SourcePassword:{password}

# example extract to create a .sql file containing the schema definition of the database
SqlPackage /Action:Extract /TargetFile:{filename}.dacpac /DiagnosticsFile:{logFile}.log /SourceServerName:{serverFQDN} \
    /SourceDatabaseName:{databaseName} /SourceUser:{username} /SourcePassword:{password} /p:ExtractTarget=File

# example extract to create a .dacpac file with data connecting using SQL authentication
SqlPackage /Action:Extract /TargetFile:{filename}.dacpac /DiagnosticsFile:{logFile}.log /p:ExtractAllTableData=true /p:VerifyExtraction=true \
    /SourceServerName:{serverFQDN} /SourceDatabaseName:{databaseName} /SourceUser:{username} /SourcePassword:{password}


# example extract to create a schema-only .dacpac file connecting using Microsoft Entra managed identity
SqlPackage /Action:Extract /TargetFile:"C:\AdventureWorksLT.dacpac" \
    /SourceConnectionString:"Server=tcp:{yourserver}.database.windows.net,1433;Initial Catalog=AdventureWorksLT;Authentication=Active Directory Managed Identity;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;"


# example extract to create a schema-only .dacpac file connecting using Microsoft Entra username and password
SqlPackage /Action:Extract /TargetFile:"C:\AdventureWorksLT.dacpac" \
    /SourceConnectionString:"Server=tcp:{yourserver}.database.windows.net,1433;Initial Catalog=AdventureWorksLT;Authentication=Active Directory Password;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;User ID={yourusername};Password={yourpassword}"


# example extract to create a schema-only .dacpac file connecting using Microsoft Entra universal authentication
SqlPackage /Action:Extract /TargetFile:"C:\AdventureWorksLT.dacpac" /UniversalAuthentication:True \
    /SourceConnectionString:"Server=tcp:{yourserver}.database.windows.net,1433;Initial Catalog=AdventureWorksLT;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;"

# example extract to create a schema-only .dacpac file connecting using an access token associated with a service principal
$Account = Connect-AzAccount -ServicePrincipal -Tenant $Tenant -Credential $Credential
$AccessToken_Object = (Get-AzAccessToken -Account $Account -Resource "https://database.windows.net/")
$AccessToken = $AccessToken_Object.Token

SqlPackage /at:$AccessToken /Action:Extract /TargetFile:"C:\AdventureWorksLT.dacpac" \
    /SourceConnectionString:"Server=tcp:{yourserver}.database.windows.net,1433;Initial Catalog=AdventureWorksLT;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;"
# OR
SqlPackage /at:$($AccessToken_Object.Token) /Action:Extract /TargetFile:"C:\AdventureWorksLT.dacpac" \
    /SourceConnectionString:"Server=tcp:{yourserver}.database.windows.net,1433;Initial Catalog=AdventureWorksLT;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;"

Parâmetros da ação Extract

Parâmetro Forma abreviada Valor Descrição
/AccessToken: /at: {string} Especifica o token de acesso da autenticação com base em token a ser utilizado quando se conectar ao banco de dados de destino.
/Action: /a: Extract Especifica a ação a ser executada.
/AzureCloudConfig: /acc: {string} Especifica os pontos de extremidade personalizados para conectar ao Microsoft Entra ID no formato: AzureActiveDirectoryAuthority={value};DatabaseServicePrincipalName={value}".
/Diagnostics: /d: {True|False} Especifica se o log de diagnósticos é emitido como saída para o console. Usa False como padrão.
/DiagnosticsFile: /df: {string} Especifica um arquivo para armazenar logs de diagnóstico.
/MaxParallelism: /mp: {int} Especifica o grau de paralelismo para operações simultâneas que são executadas em um banco de dados. O valor padrão é 8.
/OverwriteFiles: /of: {True|False} Especifica se o SqlPackage deve substituir os arquivos existentes. Se você especificar false, isso fará com que o SqlPackage anule a ação se um arquivo existente for encontrado. O valor padrão é True.
/Properties: /p: {PropertyName}={Value} Especifica um par nome-valor para uma propriedade específica da ação; {PropertyName}={Value}.
/Quiet: /q: {True|False} Especifica se os comentários detalhados serão suprimidos. Usa False como padrão.
/SourceConnectionString: /scs: {string} Especifica uma cadeia de conexão válida do SQL Server/do Azure para o banco de dados de origem. Se esse parâmetro for especificado, ele deverá ser usado exclusivamente entre todos os outros parâmetros de origem.
/SourceDatabaseName: /sdn: {string} Define o nome do banco de dados de origem.
/SourceEncryptConnection: /sec: {Optional|Mandatory|Strict|True|False} Especifica se a criptografia SQL deve ser usada para a conexão do banco de dados de origem. O valor padrão é True.
/SourceHostNameInCertificate: /shnic: {string} Especifica o valor usado para validar o certificado TLS/SSL do SQL Server de origem quando a camada de comunicação é criptografada usando TLS.
/SourcePassword: /sp: {string} Para cenários de autenticação do SQL Server, define a senha a ser usada para acessar o banco de dados de origem.
/SourceServerName: /ssn: {string} Define o nome do servidor que hospeda o banco de dados de origem.
/SourceTimeout: /st: {int} Especifica o tempo limite para estabelecer uma conexão com o banco de dados de origem em segundos.
/SourceTrustServerCertificate: /stsc: {True|False} Especifica se o protocolo TLS será usado para criptografar a conexão de banco de dados de origem e ignorar a verificação da cadeia de certificados para validar a confiança. O valor padrão é Falso.
/SourceUser: /su: {string} Para cenários de autenticação do SQL Server, define o usuário do SQL Server a ser utilizado para acessar o banco de dados de origem.
/TargetFile: /tf: {string} Especifica um arquivo de destino (ou seja, um arquivo .dacpac) no armazenamento local a ser usado como destino da ação em vez de um banco de dados. Se esse parâmetro for usado, nenhum outro parâmetro de destino será válido. Esse parâmetro será inválido para ações que dão suporte apenas a destinos de banco de dados.
/TenantId: /tid: {string} Representa a ID do locatário ou o nome de domínio do Microsoft Entra. Essa opção é necessária para dar suporte a usuários convidados ou importados do Microsoft Entra e a contas Microsoft, como outlook.com, hotmail.com ou live.com. Se esse parâmetro for omitido, a ID de locatário padrão do Microsoft Entra ID será usada, supondo que o usuário autenticado seja um usuário nativo desse locatário. No entanto, nesse caso, não há suporte para usuários convidados ou importados e/ou contas da Microsoft hospedadas nesse Microsoft Entra ID, e a operação falhará.
Para saber mais, confira Autenticação universal com o Banco de Dados SQL e Azure Synapse Analytics (suporte do SSMS para MFA).
/ThreadMaxStackSize: /tmss: {int} Especifica o tamanho máximo em megabytes para o thread que executa a ação do SqlPackage. Essa opção só deve ser usada ao encontrar exceções de excedente de pilha que ocorrem durante a análise de instruções Transact-SQL muito grandes.
/UniversalAuthentication: /ua: {True|False} Especifica se a autenticação universal deve ser usada. Quando definido como True, o protocolo de autenticação interativo é ativado para dar suporte a MFA (autenticação multifator). Essa opção também pode ser usada para autenticação do Microsoft Entra sem MFA, usando um protocolo interativo que exige que o usuário digite seu nome de usuário e senha ou autenticação integrada (credenciais do Windows). Quando /UniversalAuthentication está definido como True, nenhuma autenticação do Microsoft Entra pode ser especificada em SourceConnectionString (/scs). Quando /UniversalAuthentication está definido como False, a autenticação do Microsoft Entra deve ser especificada em SourceConnectionString (/scs).
Para saber mais, confira Autenticação universal com o Banco de Dados SQL e Azure Synapse Analytics (suporte do SSMS para MFA).

Propriedades específicas da ação Extrair

Propriedade Valor Descrição
/p: AzureSharedAccessSignatureToken=(STRING) Token SAS (assinatura de acesso compartilhado) do Azure. Confira SqlPackage para Azure Synapse Analytics e SqlPackage com dados em arquivos Parquet.
/p: AzureStorageBlobEndpoint=(STRING) Ponto de extremidade de Armazenamento de Blobs do Azure. Confira SqlPackage para Azure Synapse Analytics e SqlPackage com dados em arquivos Parquet.
/p: AzureStorageContainer=(STRING) Contêiner do Armazenamento de Blobs do Azure. Confira SqlPackage para Azure Synapse Analytics e SqlPackage com dados em arquivos Parquet.
/p: AzureStorageKey=(STRING) Chave de conta de armazenamento do Azure. Confira SqlPackage para Azure Synapse Analytics e SqlPackage com dados em arquivos Parquet.
/p: AzureStorageRootPath=(STRING) Caminho raiz do armazenamento dentro do contêiner. Sem essa propriedade, o caminho padrão é servername/databasename/timestamp/. Confira SqlPackage para Azure Synapse Analytics e SqlPackage com dados em arquivos Parquet.
/p: CommandTimeout=(INT32 '60') Especifica o tempo limite do comando em segundos ao executar consultas com relação ao SQL Server.
/p: CompressionOption=({Normal|Maximum|Fast|SuperFast|NotCompressed} 'Normal') Especifica o tipo de compactação.
/p: DacApplicationDescription=(STRING) Define a descrição do aplicativo a ser armazenada nos metadados do DACPAC.
/p: DacApplicationName=(STRING) Definiu o nome do aplicativo a ser armazenado nos metadados do DACPAC. O valor padrão é o nome do banco de dados.
/p: DacMajorVersion=(INT32 '1') Define a versão principal a ser armazenada nos metadados do DACPAC.
/p: DacMinorVersion=(INT32 '0') Define a versão secundária a ser armazenada nos metadados do DACPAC.
/p: DatabaseLockTimeout=(INT32 '60') Especifica o tempo limite de bloqueio do banco de dados em segundos ao executar consultas em SQL Server. Use -1 para esperar indefinidamente.
/p: ExtractAllTableData=(BOOLEAN 'False') Indica se os dados de todas as tabelas de usuários são extraídos. Se "true", os dados de todas as tabelas de usuários serão extraídos, e você não poderá especificar tabelas de usuários individuais para extrair dados. Se "false", especifique uma ou mais tabelas de usuário para extrair dados.
/p: ExtractApplicationScopedObjectsOnly=(BOOLEAN 'True') Se for verdadeiro, apenas extrairá objetos com escopo para o aplicativo da origem especificada. Se for falso, extrairá todos os objetos com escopo para o aplicativo da origem especificada.
/p: ExtractReferencedServerScopedElements=(BOOLEAN 'True') Se true, extrairá logon, auditoria de servidor e objetos de credencial referenciados pelos objetos do banco de dados de origem.
/p: ExtractTarget=({DacPac|File|Flat|ObjectType|Schema|SchemaObjectType} 'DacPac') Especifica formatos de saída alternativos do esquema de banco de dados, o padrão é 'DacPac' para gerar apenas um arquivo .dacpac. Opções adicionais geram um ou mais arquivos .sql organizados por 'SchemaObjectType' (arquivos em pastas para cada esquema e tipo de objeto), 'Schema' (arquivos em pastas para cada esquema), 'ObjectType' (arquivos em pastas para cada tipo de objeto), 'Flat' (todos os arquivos na mesma pasta) ou 'File' (apenas um arquivo).
/p: ExtractUsageProperties=(BOOLEAN 'False') Especifica se propriedades de uso, como contagem de linhas da tabela e tamanho do índice, serão extraídas do banco de dados.
/p: HashObjectNamesInLogs=(BOOLEAN 'False') Especifica se todos os nomes de objetos nos logs devem ser substituídos por um valor de hash aleatório.
/p: IgnoreExtendedProperties=(BOOLEAN 'False') Especifica se as propriedades estendidas devem ser ignoradas.
/p: IgnorePermissions=(BOOLEAN 'True') Especifica se as permissões devem ser ignoradas.
/p: IgnoreUserLoginMappings=(BOOLEAN 'False') Especifica se os relacionamentos entre usuários e logons devem ser ignorados.
/p: LongRunningCommandTimeout=(INT32 '0') Especifica o tempo limite do comando de execução prolongada em segundos ao executar consultas com relação ao SQL Server. Use 0 para esperar indefinidamente.
/p: Storage=({File|Memory}) Especifica o tipo de armazenamento de backup para o modelo de esquema usado durante a extração. "Memory" é o padrão para a versão do .NET Core do SqlPackage. "File" só está disponível e é o padrão para a versão do .NET Framework do SqlPackage.
/p: TableData=(STRING) Indica a tabela a partir da qual os dados serão extraídos. Especifique o nome da tabela com ou sem os colchetes ao redor das partes do nome no seguinte formato: nome_esquema.identificador_tabela. Essa propriedade pode ser especificada várias vezes para indicar várias opções. Aplica-se a dados extraídos para arquivos Parquet e .dacpac.
/p: TempDirectoryForTableData=(STRING) Especifica o diretório temporário usado para armazenar em buffer os dados da tabela antes de serem gravados no arquivo do pacote.
/p: VerifyExtraction=(BOOLEAN 'False') Especifica se o modelo de esquema extraído deve ser verificado.

Próximas etapas