sp_addpushsubscription_agent (Transact-SQL)

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

添加新的预定代理作业，以使推送订阅与事务发布同步。 此存储过程在发布服务器上对发布数据库执行。

重要

使用远程分发服务器配置发布服务器时，为所有参数（包括 @job_login 和 @job_password）提供的值将作为纯文本发送到分发服务器。 在执行此存储过程之前，应该对发布服务器及其远程分发服务器之间的连接进行加密。 有关详细信息，请参阅将 SQL Server 数据库引擎配置为使用加密连接。

Transact-SQL 语法约定

语法

sp_addpushsubscription_agent
    [ @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' ]
    [ , [ @job_login = ] N'job_login' ]
    [ , [ @job_password = ] N'job_password' ]
    [ , [ @job_name = ] N'job_name' ]
    [ , [ @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 ]
    [ , [ @dts_package_name = ] N'dts_package_name' ]
    [ , [ @dts_package_password = ] N'dts_package_password' ]
    [ , [ @dts_package_location = ] N'dts_package_location' ]
    [ , [ @enabled_for_syncmgr = ] N'enabled_for_syncmgr' ]
    [ , [ @distribution_job_name = ] N'distribution_job_name' ]
    [ , [ @publisher = ] N'publisher' ]
    [ , [ @subscriber_provider = ] N'subscriber_provider' ]
    [ , [ @subscriber_datasrc = ] N'subscriber_datasrc' ]
    [ , [ @subscriber_location = ] N'subscriber_location' ]
    [ , [ @subscriber_provider_string = ] N'subscriber_provider_string' ]
    [ , [ @subscriber_catalog = ] N'subscriber_catalog' ]
[ ; ]

参数

[ @publication = ] N'publication'

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

[ @subscriber = ] N'subscriber'

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

注意

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

[ @subscriber_db = ] N'subscriber_db'

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

对于非 SQL Server 订阅服务器，请为subscriber_db指定值（默认目标）。

[ @subscriber_security_mode = ] subscriber_security_mode

同步时连接到订阅服务器时要使用的安全模式。 @subscriber_security_mode为 smallint，默认值为 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 令牌身份验证。

重要

对于排队更新订阅，请使用 SQL Server 身份验证连接到订阅服务器，并为每个订阅服务器的连接指定不同的帐户。 对于所有其他订阅，则使用 Windows 身份验证。

[ @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. 如果使用订阅者密码，则会自动加密。

重要

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

[ @job_login = ] N'job_login'

运行代理的帐户的登录名。 在Azure SQL 托管实例，使用 SQL Server 帐户。 @job_login 为 nvarchar（257），默认值为 NULL. 使用 Windows 集成身份验证时，此 Windows 帐户始终用于代理与分发服务器的连接，以及与订阅服务器的连接。

[ @job_password = ] N'job_password'

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

重要

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

[ @job_name = ] N'job_name'

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

[ @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，默认值为 0.

[ @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，默认值为 5.

[ @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，默认值为 235959.

[ @active_start_date = ] active_start_date

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

[ @active_end_date = ] active_end_date

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

[ @dts_package_name = ] N'dts_package_name'

指定 Data Transformation Services (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），默认值为 distributor. 包的位置可以是 distributor 或 subscriber。

[ @enabled_for_syncmgr = ] N'enabled_for_syncmgr'

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

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

[ @distribution_job_name = ] N'distribution_job_name'

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

[ @publisher = ] N'publisher'

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

[ @subscriber_provider = ] N'subscriber_provider'

注册非 SQL Server 数据源的 OLE DB 访问接口的唯一编程标识符（PROGID）。 @subscriber_provider为 sysname，默认值为 NULL. 对于在分发服务器上安装的 OLE DB 提供程序，@subscriber_provider 必须是唯一的。 非 SQL Server 订阅服务器仅支持@subscriber_provider 。

[ @subscriber_datasrc = ] N'subscriber_datasrc'

OLE DB 访问接口所理解的数据源的名称。@subscriber_datasrc为 nvarchar（4000），默认值为 NULL. @subscriber_datasrc作为DBPROP_INIT_DATASOURCE属性传递来初始化 OLE DB 访问接口。 @subscriber_datasrc仅支持非 SQL Server 订阅服务器。

[ @subscriber_location = ] N'subscriber_location'

OLE DB 访问接口所理解的数据库的位置。 @subscriber_location 为 nvarchar（4000），默认值为 NULL. @subscriber_location 作为 DBPROP_INIT_LOCATION 属性传递来初始化 OLE DB 访问接口。 @subscriber_location仅支持非 SQL Server 订阅服务器。

[ @subscriber_provider_string = ] N'subscriber_provider_string'

标识数据源的特定于 OLE DB 提供程序的连接字符串。 @subscriber_provider_string为 nvarchar（4000），默认值为 NULL. @subscriber_provider_string 传递给 IDataInitialize 或设置为 DBPROP_INIT_PROVIDERSTRING 初始化 OLE DB 访问接口的属性。 @subscriber_provider_string仅支持非 SQL Server 订阅服务器。

[ @subscriber_catalog = ] N'subscriber_catalog'

与 OLE DB 访问接口建立连接时要使用的目录。 @subscriber_catalog为 sysname，默认值为 NULL. @subscriber_catalog 作为 DBPROP_INIT_CATALOG 属性传递来初始化 OLE DB 访问接口。 非 SQL Server 订阅服务器仅支持@subscriber_catalog。

返回代码值

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

注解

sp_addpushsubscription_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".

DECLARE @publication AS sysname;
DECLARE @subscriber AS sysname;
DECLARE @subscriptionDB AS sysname;
SET @publication = N'AdvWorksProductTran';
SET @subscriber = $(SubServer);
SET @subscriptionDB = N'AdventureWorks2022Replica';

--Add a push subscription to a transactional publication.
USE [AdventureWorks2022]
EXEC sp_addsubscription 
  @publication = @publication, 
  @subscriber = @subscriber, 
  @destination_db = @subscriptionDB, 
  @subscription_type = N'push';

--Add an agent job to synchronize the push subscription.
EXEC sp_addpushsubscription_agent 
  @publication = @publication, 
  @subscriber = @subscriber, 
  @subscriber_db = @subscriptionDB, 
  @job_login = $(Login), 
  @job_password = $(Password);
GO

权限

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

相关内容

• 创建推送订阅
• 为非 SQL Server 订阅服务器创建订阅
• Subscribe to Publications
• 复制存储过程 (Transact-SQL)
• sp_addsubscription （Transact-SQL）
• sp_changesubscription （Transact-SQL）
• sp_dropsubscription （Transact-SQL）
• sp_helpsubscription （Transact-SQL）