sp_addpullsubscription_agent (Transact-SQL)

适用于： SQL Server Azure SQL 托管实例

向事务发布添加用于同步请求订阅的新计划的代理作业。 此存储过程在订阅服务器的订阅数据库中执行。

Transact-SQL 语法约定

语法

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' ]
[ ; ]

参数

[ @publisher = ] N'publisher'

发布服务器的名称。 @publisher为 sysname，无默认值。

注意

可以将服务器名称指定为 <Hostname>,<PortNumber> 默认实例或 <Hostname>\<InstanceName>,<PortNumber> 命名实例。 使用自定义端口在 Linux 或 Windows 上部署 SQL Server 时指定连接的端口号，并禁用浏览器服务。 远程分发服务器的自定义端口号的使用适用于 SQL Server 2019 （15.x） 及更高版本。

[ @publisher_db = ] N'publisher_db'

发布服务器数据库的名称。 @publisher_db为 sysname，默认值为 NULL. Oracle 发布服务器将忽略@publisher_db 。

[ @publication = ] N'publication'

发布的名称。 @publication 为 sysname，无默认值。

[ @subscriber = ] N'subscriber'

如果订阅服务器数据库位于可用性组中，则订阅服务器实例的名称或 AG 侦听器的名称。 @subscriber为 sysname，默认值为 NULL.

注意

此参数已弃用，并维护脚本的向后兼容性。

为属于 AG 的订阅服务器运行时sp_addpullsubscription_agent，请将@subscriber设置为 AG 侦听器名称。 如果在 CU 16 之前运行 SQL Server 2016（13.x）和早期版本或 SQL Server 2017 （14.x），则存储过程执行而不返回错误，但复制分发代理上的 @subscriber 参数不引用 AG 侦听器名称;该参数是使用执行命令的订阅服务器名称创建的。 若要修改此问题，请使用 AG 侦听器名称值手动更新分发代理作业@subscriber参数。

[ @subscriber_db = ] N'subscriber_db'

订阅数据库的名称。 @subscriber_db为 sysname，默认值为 NULL.

注意

此参数已弃用，并维护脚本的向后兼容性。

[ @subscriber_security_mode = ] subscriber_security_mode

同步时连接到订阅服务器时要使用的安全模式。 @subscriber_security_mode为 int，默认值为 NULL.

• 0 指定 SQL Server 身份验证
• 1指定Windows 身份验证

注意

此参数已弃用，并维护脚本的向后兼容性。 分发代理始终使用 Windows 身份验证连接到本地订阅服务器。 如果此参数以外的值或1指定了值NULL，则返回警告消息。

[ @subscriber_login = ] N'subscriber_login'

同步时连接到订阅服务器的订阅服务器时要使用的订阅服务器登录名。 @subscriber_login为 sysname，默认值为 NULL.

注意

此参数已弃用，并维护脚本的向后兼容性。 如果为此参数指定了值，则返回警告消息，但忽略该值。

[ @subscriber_password = ] N'subscriber_password'

订阅服务器密码。 如果subscriber_security_mode设置为0subscriber_password，则需要subscriber_password。 @subscriber_password为 sysname，默认值为 NULL. 如果使用订阅者密码，则会自动加密。

注意

此参数已弃用，并维护脚本的向后兼容性。 如果为此参数指定了值，则返回警告消息，但忽略该值。

[ @distributor = ] N'distributor'

分发服务器的名称。 @distributor为 sysname，默认值为 @publisher 指定的值。

[ @distribution_db = ] N'distribution_db'

分发数据库的名称。 @distribution_db为 sysname，默认值为 NULL.

[ @distributor_security_mode = ] distributor_security_mode

注意

Microsoft Entra ID 以前称为 Azure Active Directory (Azure AD)。

同步时连接到分发服务器时要使用的安全模式。 @distributor_security_mode为 int，默认值为 1. 以下值定义安全模式：

• 0 指定 SQL Server 身份验证。
• 1指定Windows 身份验证。
• 2 指定从 SQL Server 2022 （16.x） CU 6 开始Microsoft Entra 密码身份验证。
• 3 指定从 SQL Server 2022 （16.x） CU 6 开始的 Microsoft Entra 集成身份验证。
• 4 指定从 SQL Server 2022 （16.x） CU 6 开始Microsoft Entra 令牌身份验证。

重要

请尽可能使用 Windows 身份验证。

[ @distributor_login = ] N'distributor_login'

同步时连接到分发服务器的分发服务器时要使用的分发服务器登录名。 @distributor_login为 sysname，默认值为 NULL. 如果@distributor_security_mode设置为0@distributor_login，则需要@distributor_login。

[ @distributor_password = ] N'distributor_password'

分发服务器密码。 如果distributor_security_mode设置为0distributor_password，则需要distributor_password。 @distributor_password为 sysname，默认值为 NULL.

重要

不要使用空密码。 请使用强密码。 如果可能，请在运行时提示用户输入安全凭据。 如果必须在脚本文件中存储凭据，则必须保护文件以防止未经授权的访问。

[ @optional_command_line = ] N'optional_command_line'

提供给分发代理的可选命令提示符。 例如，-DefinitionFile C:\Distdef.txt 或 -CommitBatchSize 10。 @optional_command_line为 nvarchar（4000），默认值为空字符串。

[ @frequency_type = ] frequency_type

计划分发代理的频率。 @frequency_type 为 int，可以是以下值之一。

值	说明
1	一次
2（默认值）	按需
4	每日
8	每周
16	每月
32	与“每月”选项相关
64	自动启动
128	定期

注意

指定一个值，64使分发代理在连续模式下运行。 这对应于设置 -Continuous 代理的参数。 有关详细信息，请参阅 Replication Distribution Agent。

[ @frequency_interval = ] frequency_interval

要应用于@frequency_type设置的频率的值。 @frequency_interval为 int，默认值为 1.

[ @frequency_relative_interval = ] frequency_relative_interval

分发代理的日期。 当@frequency_type设置为32（每月相对）时，将使用此参数。 @frequency_relative_interval 为 int，可以是以下值之一。

值	说明
1（默认值）	第一个
2	第二个
4	第三个
8	第四
16	Last

[ @frequency_recurrence_factor = ] frequency_recurrence_factor

@frequency_type使用的重复因子。 @frequency_recurrence_factor为 int，默认值为 1.

[ @frequency_subday = ] frequency_subday

指定在定义的时间段内重新计划的频率。 @frequency_subday为 int，可以是以下值之一。

值	说明
1（默认值）	一次
2	Second
4	Minute
8	小时

[ @frequency_subday_interval = ] frequency_subday_interval

@frequency_subday的间隔。 @frequency_subday_interval为 int，默认值为 1.

[ @active_start_time_of_day = ] active_start_time_of_day

第一次计划分发代理的时间，格式为 HHmmss。 @active_start_time_of_day为 int，默认值为 0.

[ @active_end_time_of_day = ] active_end_time_of_day

分发代理停止计划的时间，格式为 HHmmss。 @active_end_time_of_day为 int，默认值为 0.

[ @active_start_date = ] active_start_date

第一次计划分发代理的日期，格式为 yyyyMMdd。 @active_start_date为 int，默认值为 0.

[ @active_end_date = ] active_end_date

分发代理停止计划的日期，格式为 yyyyMMdd。 @active_end_date为 int，默认值为 0.

[ @distribution_jobid = ] distribution_jobid OUTPUT

此作业的分发代理 ID。 @distribution_jobid是二进制类型的 OUTPUT 参数（16），默认值为 NULL.

[ @encrypted_distributor_password = ] encrypted_distributor_password

@encrypted_distributor_password为位，默认值为 0.

注意

不再支持设置 @encrypted_distributor_password 。 尝试将此位参数1设置为将导致错误。

[ @enabled_for_syncmgr = ] N'enabled_for_syncmgr'

指定是否可以通过Microsoft同步管理器同步订阅。 @enabled_for_syncmgr 为 nvarchar（5），默认值为 false.

• 如果 false订阅未注册到 Synchronization Manager。
• 如果 true订阅已注册到同步管理器，并且可以在不启动 SQL Server Management Studio 的情况下进行同步。

[ @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'

指定快照的备用文件夹的位置。 @alt_snapshot_folder为 nvarchar（255），默认值为 NULL.

[ @working_directory = ] N'working_directory'

用于存储发布数据和架构文件的工作目录的名称。 @working_directory为 nvarchar（255），默认值为 NULL. 名称应按 UNC 格式指定。

[ @use_ftp = ] N'use_ftp'

指定使用 FTP 而非常规协议检索快照。 @use_ftp为 nvarchar（5），默认值为 false.

[ @publication_type = ] publication_type

指定发布的复制类型。 @publication_type为 tinyint，默认值为 0.

• 如果 0为发布，则为事务类型。
• 如果 1为发布，则为快照类型。
• 如果 2为发布，则为合并类型。

[ @dts_package_name = ] N'dts_package_name'

指定 DTS 包的名称。 @dts_package_name为 sysname，默认值为 NULL. 例如，若要将包名称指定为 DTSPub_Package，则该参数应为 @dts_package_name = N'DTSPub_Package'。

[ @dts_package_password = ] N'dts_package_password'

指定用于包的密码（如果有）。 @dts_package_password是 sysname，默认值NULL为，这意味着密码不在包上。

注意

如果 指定了@dts_package_name ，则必须指定密码。

[ @dts_package_location = ] N'dts_package_location'

指定包位置。 @dts_package_location为 nvarchar（12），默认值为 subscriber. 包的位置可以是 distributor 或 subscriber。

[ @reserved = ] N'reserved'

标识为仅供参考。 不支持。 不保证以后的兼容性。

[ @offloadagent = ] N'offloadagent'

此参数已弃用，并维护脚本的向后兼容性。 如果为此参数指定了值，则返回警告消息，但忽略该值。 将 @offloadagent 设置为非 false 生成错误的值。

[ @offloadserver = ] N'offloadserver'

此参数已弃用，并维护脚本的向后兼容性。 如果为此参数指定了值，则返回警告消息，但忽略该值。 将 @offloadserver 设置为非 false 生成错误的值。

[ @job_name = ] N'job_name'

现有代理作业的名称。 @job_name为 sysname，默认值为 NULL. 仅当使用现有作业而不是（默认的）新创建的作业同步订阅时，才指定此参数。 如果你不是 sysadmin 固定服务器角色的成员，则必须在指定@job_name时指定@job_login和@job_password。

[ @job_login = ] N'job_login'

运行代理的 Windows 帐户的登录名。 @job_login为 nvarchar（257），没有默认值。 代理始终可以使用此 Windows 帐户连接到订阅服务器。

[ @job_password = ] N'job_password'

运行代理的 Windows 帐户的密码。 @job_password为 sysname，无默认值。

重要

不要使用空密码。 请使用强密码。 如果可能，请在运行时提示用户输入安全凭据。 如果必须在脚本文件中存储凭据，则必须保护文件以防止未经授权的访问。

返回代码值

0（成功）或 1（失败）。

注解

sp_addpullsubscription_agent 用于快照复制和事务复制。

示例

-- 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

权限

只有 sysadmin 固定服务器角色的成员或db_owner固定数据库角色的成员才能执行sp_addpullsubscription_agent。

相关内容

• Create a Pull Subscription
• Subscribe to Publications
• sp_addpullsubscription （Transact-SQL）
• sp_change_subscription_properties （Transact-SQL）
• sp_droppullsubscription （Transact-SQL）
• sp_helppullsubscription （Transact-SQL）
• sp_helpsubscription_properties (Transact-SQL)