sp_addpullsubscription_agent (Transact-SQL)

Aplica-se a: SQL Server Instância Gerenciada de SQL do Azure

Adiciona um novo trabalho agendado de agente usado para sincronizar uma assinatura pull com uma publicação transacional. Esse procedimento armazenado é executado no Assinante no banco de dados de assinatura.

Convenções de sintaxe de Transact-SQL

Sintaxe

sp_addpullsubscription_agent
    [ @publisher = ] N'publisher'
    [ , [ @publisher_db = ] N'publisher_db' ]
    , [ @publication = ] N'publication'
    [ , [ @subscriber = ] N'subscriber' ]
    [ , [ @subscriber_db = ] N'subscriber_db' ]
    [ , [ @subscriber_security_mode = ] subscriber_security_mode ]
    [ , [ @subscriber_login = ] N'subscriber_login' ]
    [ , [ @subscriber_password = ] N'subscriber_password' ]
    [ , [ @distributor = ] N'distributor' ]
    [ , [ @distribution_db = ] N'distribution_db' ]
    [ , [ @distributor_security_mode = ] distributor_security_mode ]
    [ , [ @distributor_login = ] N'distributor_login' ]
    [ , [ @distributor_password = ] N'distributor_password' ]
    [ , [ @optional_command_line = ] N'optional_command_line' ]
    [ , [ @frequency_type = ] frequency_type ]
    [ , [ @frequency_interval = ] frequency_interval ]
    [ , [ @frequency_relative_interval = ] frequency_relative_interval ]
    [ , [ @frequency_recurrence_factor = ] frequency_recurrence_factor ]
    [ , [ @frequency_subday = ] frequency_subday ]
    [ , [ @frequency_subday_interval = ] frequency_subday_interval ]
    [ , [ @active_start_time_of_day = ] active_start_time_of_day ]
    [ , [ @active_end_time_of_day = ] active_end_time_of_day ]
    [ , [ @active_start_date = ] active_start_date ]
    [ , [ @active_end_date = ] active_end_date ]
    [ , [ @distribution_jobid = ] distribution_jobid OUTPUT ]
    [ , [ @encrypted_distributor_password = ] encrypted_distributor_password ]
    [ , [ @enabled_for_syncmgr = ] N'enabled_for_syncmgr' ]
    [ , [ @ftp_address = ] N'ftp_address' ]
    [ , [ @ftp_port = ] ftp_port ]
    [ , [ @ftp_login = ] N'ftp_login' ]
    [ , [ @ftp_password = ] N'ftp_password' ]
    [ , [ @alt_snapshot_folder = ] N'alt_snapshot_folder' ]
    [ , [ @working_directory = ] N'working_directory' ]
    [ , [ @use_ftp = ] N'use_ftp' ]
    [ , [ @publication_type = ] publication_type ]
    [ , [ @dts_package_name = ] N'dts_package_name' ]
    [ , [ @dts_package_password = ] N'dts_package_password' ]
    [ , [ @dts_package_location = ] N'dts_package_location' ]
    [ , [ @reserved = ] N'reserved' ]
    [ , [ @offloadagent = ] N'offloadagent' ]
    [ , [ @offloadserver = ] N'offloadserver' ]
    [ , [ @job_name = ] N'job_name' ]
    [ , [ @job_login = ] N'job_login' ]
    [ , [ @job_password = ] N'job_password' ]
[ ; ]

Argumentos

@publisher [ = ] N'editor'

O nome do Editor. @publisher é sysname, sem padrão.

Observação

O nome do servidor pode ser especificado como <Hostname>,<PortNumber> para uma instância padrão ou <Hostname>\<InstanceName>,<PortNumber> para uma instância nomeada. Especifique o número da porta para sua conexão quando o SQL Server for implantado no Linux ou Windows com uma porta personalizada e o serviço do navegador estiver desabilitado. O uso de números de porta personalizados para distribuidor remoto se aplica ao SQL Server 2019 (15.x) e versões posteriores.

@publisher_db [ = ] N'publisher_db'

O nome do banco de dados Publicador. @publisher_db é sysname, com um padrão de NULL. @publisher_db é ignorado pelos Publicadores Oracle.

@publication [ = ] N'publicação'

O nome da publicação. @publication é sysname, sem padrão.

@subscriber [ = ] N'assinante'

O nome da instância do Assinante ou o nome do ouvinte do AG se o banco de dados do assinante estiver em um grupo de disponibilidade. @subscriber é sysname, com um padrão de NULL.

Observação

Esse parâmetro foi preterido e é mantido para compatibilidade com versões anteriores de scripts.

Ao executar sp_addpullsubscription_agent para um assinante que faz parte de um AG, defina @subscriber como o nome do ouvinte do AG. Se você executar o SQL Server 2016 (13.x) e versões anteriores ou o SQL Server 2017 (14.x) antes da 16, o procedimento armazenado será executado sem retornar um erro, mas o parâmetro @subscriber no Replication Distribution Agent não fará referência ao nome do ouvinte do AG; o parâmetro será criado com o nome do servidor do assinante no qual o comando é executado. Para corrigir esse problema, atualize manualmente o parâmetro @subscriber do trabalho do Agente de Distribuição com o valor do nome do ouvinte do AG.

@subscriber_db [ = ] N'subscriber_db'

O nome do banco de dados de assinatura. @subscriber_db é sysname, com um padrão de NULL.

Observação

Esse parâmetro foi preterido e é mantido para compatibilidade com versões anteriores de scripts.

@subscriber_security_mode [ = ] subscriber_security_mode

O modo de segurança a ser usado ao se conectar a um Assinante durante a sincronização. @subscriber_security_mode é int, com um padrão de NULL.

  • 0 especifica a autenticação do SQL Server
  • 1 especifica a autenticação do Windows

Observação

Esse parâmetro foi preterido e é mantido para compatibilidade com versões anteriores de scripts. O Agente de Distribuição sempre conecta ao Assinante local usando a Autenticação do Windows. Se um valor diferente de NULL ou 1 for especificado para esse parâmetro, uma mensagem de aviso será retornada.

@subscriber_login [ = ] N'subscriber_login'

O login do Assinante a ser usado ao se conectar a um Assinante ao sincronizar. @subscriber_login é sysname, com um padrão de NULL.

Observação

Esse parâmetro foi preterido e é mantido para compatibilidade com versões anteriores de scripts. Se um valor for especificado para esse parâmetro, uma mensagem de aviso será retornada, mas o valor será ignorado.

@subscriber_password [ = ] N'subscriber_password'

A senha do assinante. subscriber_password é necessário se subscriber_security_mode estiver definido como 0. @subscriber_password é sysname, com um padrão de NULL. Se uma senha de assinante for usada, ela será criptografada automaticamente.

Observação

Esse parâmetro foi preterido e é mantido para compatibilidade com versões anteriores de scripts. Se um valor for especificado para esse parâmetro, uma mensagem de aviso será retornada, mas o valor será ignorado.

@distributor [ = ] N'distribuidor'

O nome do Distribuidor. @distributor é sysname, com um padrão do valor especificado por @publisher.

@distribution_db [ = ] N'distribution_db'

O nome do banco de dados de distribuição. @distribution_db é sysname, com um padrão de NULL.

@distributor_security_mode [ = ] distributor_security_mode

Observação

O Microsoft Entra ID era conhecido anteriormente como Azure Active Directory (Azure AD).

O modo de segurança a ser usado ao se conectar a um Distribuidor durante a sincronização. @distributor_security_mode é int, com um padrão de 1. Os seguintes valores definem o modo de segurança:

  • 0 especifica a autenticação do SQL Server.
  • 1 especifica a autenticação do Windows.
  • 2 especifica a autenticação de senha do Microsoft Entra a partir do SQL Server 2022 (16.x) 6.
  • 3 especifica a autenticação integrada do Microsoft Entra a partir do SQL Server 2022 (16.x) 6.
  • 4 especifica a autenticação de token do Microsoft Entra a partir do SQL Server 2022 (16.x) 6.

Importante

Quando possível, use a autenticação do Windows.

@distributor_login [ = ] N'distributor_login'

O login do Distribuidor a ser usado ao se conectar a um Distribuidor durante a sincronização. @distributor_login é sysname, com um padrão de NULL. @distributor_login é necessário se @distributor_security_mode estiver definido como 0.

@distributor_password [ = ] N'distributor_password'

A senha do Distribuidor. distributor_password é necessário se distributor_security_mode estiver definido como 0. @distributor_password é sysname, com um padrão de NULL.

Importante

Não use uma senha em branco. Use uma senha forte. Quando possível, solicite que os usuários insiram as credenciais de segurança em tempo de execução. Se for necessário armazenar credenciais em um arquivo de script, você deverá proteger o arquivo para impedir acesso não autorizado.

@optional_command_line [ = ] N'optional_command_line'

Um prompt de comando opcional fornecido ao Agente de Distribuição. Por exemplo, -DefinitionFile C:\Distdef.txt ou -CommitBatchSize 10. @optional_command_line é nvarchar(4000), com um padrão de uma cadeia de caracteres vazia.

@frequency_type [ = ] frequency_type

A frequência com que o Agente de Distribuição deve ser agendado. @frequency_type é int e pode ser um dos seguintes valores.

Valor Descrição
1 Uma vez
2 (padrão) Sob demanda
4 Diário
8 Semanal
16 Mensal
32 Relativo ao mês
64 Iniciar automaticamente
128 Recorrente

Observação

Especificar um valor de 64 faz com que o Distribution Agent seja executado no modo contínuo. Isso corresponde à configuração do -Continuous parâmetro para o agente. Para obter mais informações, consulte Replication Distribution Agent.

@frequency_interval [ = ] frequency_interval

O valor a ser aplicado à frequência definida por @frequency_type. @frequency_interval é int, com um padrão de 1.

@frequency_relative_interval [ = ] frequency_relative_interval

A data do Agente de Distribuição. Esse parâmetro é usado quando @frequency_type é definido como 32 (relativo mensal). @frequency_relative_interval é int e pode ser um dos seguintes valores.

Valor Descrição
1 (padrão) Primeiro
2 Segundo
4 Terceiro
8 Quarto
16 Last

@frequency_recurrence_factor [ = ] frequency_recurrence_factor

O fator de recorrência usado por @frequency_type. @frequency_recurrence_factor é int, com um padrão de 1.

@frequency_subday [ = ] frequency_subday

Especifica a frequência de reprogramação durante o período definido. @frequency_subday é int e pode ser um dos valores a seguir.

Valor Descrição
1 (padrão) Uma vez
2 Second
4 Minuto
8 Hora

@frequency_subday_interval [ = ] frequency_subday_interval

O intervalo para @frequency_subday. @frequency_subday_interval é int, com um padrão de 1.

@active_start_time_of_day [ = ] active_start_time_of_day

A hora do dia em que o Distribution Agent é agendado pela primeira vez, formatado como HHmmss. @active_start_time_of_day é int, com um padrão de 0.

@active_end_time_of_day [ = ] active_end_time_of_day

A hora do dia em que o Distribution Agent deixa de ser agendado, formatado como HHmmss. @active_end_time_of_day é int, com um padrão de 0.

@active_start_date [ = ] active_start_date

A data em que o Distribution Agent é agendado pela primeira vez, formatado como yyyyMMdd. @active_start_date é int, com um padrão de 0.

@active_end_date [ = ] active_end_date

A data em que o Distribution Agent deixa de ser agendado, formatado como yyyyMMdd. @active_end_date é int, com um padrão de 0.

@distribution_jobid [ = ] distribution_jobid SAÍDA

A ID do Agente de Distribuição para este trabalho. @distribution_jobid é um parâmetro OUTPUT do tipo binary(16), com um padrão de NULL.

@encrypted_distributor_password [ = ] encrypted_distributor_password

@encrypted_distributor_password é bit, com um padrão de 0.

Observação

Não há mais suporte para a configuração @encrypted_distributor_password . A tentativa de definir esse parâmetro de bit como 1 resultará em um erro.

@enabled_for_syncmgr [ = ] N'enabled_for_syncmgr'

Especifica se a assinatura pode ser sincronizada por meio do Gerenciador de Sincronização da Microsoft. @enabled_for_syncmgr é nvarchar(5), com um padrão de false.

  • Se false, a assinatura não está registrada no Gerenciador de Sincronização.
  • Se true, a assinatura é registrada no Gerenciador de Sincronização e pode ser sincronizada sem iniciar o SQL Server Management Studio.

@ftp_address [ = ] N'ftp_address'

Esse parâmetro foi preterido e é mantido para compatibilidade com versões anteriores de scripts.

@ftp_port [ = ] ftp_port

Esse parâmetro foi preterido e é mantido para compatibilidade com versões anteriores de scripts.

@ftp_login [ = ] N'ftp_login'

Esse parâmetro foi preterido e é mantido para compatibilidade com versões anteriores de scripts.

@ftp_password [ = ] N'ftp_password'

Esse parâmetro foi preterido e é mantido para compatibilidade com versões anteriores de scripts.

@alt_snapshot_folder [ = ] N'alt_snapshot_folder'

Especifica o local da pasta alternativa para o instantâneo. @alt_snapshot_folder é nvarchar(255), com um padrão de NULL.

@working_directory [ = ] N'working_directory'

O nome do diretório de trabalho usado para armazenar dados e arquivos de esquema para a publicação. @working_directory é nvarchar(255), com um padrão de NULL. O nome deve ser especificado no formato UNC.

@use_ftp [ = ] N'use_ftp'

Especifica o uso do FTP em vez do protocolo regular para recuperar instantâneos. @use_ftp é nvarchar(5), com um padrão de false.

@publication_type [ = ] publication_type

Especifica o tipo de replicação da publicação. @publication_type é tinyint, com um padrão de 0.

  • Se 0, publicação é um tipo de transação.
  • Se 1, a publicação é um tipo de instantâneo.
  • Se 2, a publicação é um tipo de mesclagem.

@dts_package_name [ = ] N'dts_package_name'

Especifica o nome do pacote DTS. @dts_package_name é sysname, com um padrão de NULL. Por exemplo, para especificar um nome de pacote DTSPub_Package, o parâmetro seria @dts_package_name = N'DTSPub_Package'.

@dts_package_password [ = ] N'dts_package_password'

Especifica a senha no pacote, se houver um. @dts_package_password é sysname, com um padrão de NULL, o que significa que uma senha não está no pacote.

Observação

Você deve especificar uma senha se @dts_package_name for especificado.

@dts_package_location [ = ] N'dts_package_location'

Especifica o local do pacote. @dts_package_location é nvarchar(12), com um padrão de subscriber. A localização do pacote pode ser distributor ou subscriber.

@reserved [ = ] N'reservado'

Identificado apenas para fins informativos. Não há suporte. A compatibilidade futura não está garantida.

@offloadagent [ = ] N'offloadagent'

Esse parâmetro foi preterido e é mantido para compatibilidade com versões anteriores de scripts. Se um valor for especificado para esse parâmetro, uma mensagem de aviso será retornada, mas o valor será ignorado. Definir @offloadagent para um valor diferente de false gera um erro.

@offloadserver [ = ] N'offloadserver'

Esse parâmetro foi preterido e é mantido para compatibilidade com versões anteriores de scripts. Se um valor for especificado para esse parâmetro, uma mensagem de aviso será retornada, mas o valor será ignorado. Definir @offloadserver para um valor diferente de false gera um erro.

@job_name [ = ] N'job_name'

O nome de um trabalho de agente existente. @job_name é sysname, com um padrão de NULL. Esse parâmetro só é especificado quando a assinatura é sincronizada usando um trabalho existente em vez de um trabalho recém-criado (o padrão). Se você não for membro da função de servidor fixa sysadmin , deverá especificar @job_login e @job_password ao especificar @job_name.

@job_login [ = ] N'job_login'

O logon da conta do Windows sob a qual o agente é executado. @job_login é nvarchar(257), sem padrão. Essa conta do Windows sempre é usada para conexões doe agente com o Assinante.

@job_password [ = ] N'job_password'

A senha da conta do Windows sob a qual o agente é executado. @job_password é sysname, sem padrão.

Importante

Não use uma senha em branco. Use uma senha forte. Quando possível, solicite que os usuários insiram as credenciais de segurança em tempo de execução. Se for necessário armazenar credenciais em um arquivo de script, você deverá proteger o arquivo para impedir acesso não autorizado.

Valores do código de retorno

0 (sucesso) ou 1 (falha).

Comentários

sp_addpullsubscription_agent é usado na replicação de instantâneo e na replicação transacional.

Exemplos

-- This script uses sqlcmd scripting variables. They are in the form
-- $(MyVariable). For information about how to use scripting variables  
-- on the command line and in SQL Server Management Studio, see the 
-- "Executing Replication Scripts" section in the topic
-- "Programming Replication Using System Stored Procedures".

-- Execute this batch at the Subscriber.
DECLARE @publication AS sysname;
DECLARE @publisher AS sysname;
DECLARE @publicationDB AS sysname;
SET @publication = N'AdvWorksProductTran';
SET @publisher = $(PubServer);
SET @publicationDB = N'AdventureWorks2022';

-- At the subscription database, create a pull subscription 
-- to a transactional publication.
USE [AdventureWorks2022Replica]
EXEC sp_addpullsubscription 
  @publisher = @publisher, 
  @publication = @publication, 
  @publisher_db = @publicationDB;

-- Add an agent job to synchronize the pull subscription.
EXEC sp_addpullsubscription_agent 
  @publisher = @publisher, 
  @publisher_db = @publicationDB, 
  @publication = @publication, 
  @distributor = @publisher, 
  @job_login = $(Login), 
  @job_password = $(Password);
GO

Permissões

Somente membros da função de servidor fixa sysadmin ou db_owner função de banco de dados fixa podem executar sp_addpullsubscription_agent.