sys.sp_addpushsubscription_agent(Transact-SQL)

适用于:SQL ServerAzureSQL Managed Instance

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

重要

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

Transact-SQL 语法约定

语法

sys.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' ]
    [ , [ @job_security_mode = ] job_security_mode ]
[ ; ]

参数

[ @publication = ] N'publication'

发布的名称。 @publication 是 系统名,没有默认值。

[ @subscriber = ] N'subscriber'

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

注意

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

[ @subscriber_db = ] N'subscriber_db'

订阅数据库的名称。 @subscriber_db 是 系统名,默认为 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 令牌身份验证。
  • 5指定使用分发商默认托管身份进行 Microsoft Entra 托管身份认证。 仅适用于事务复制中,当分发器为 Azure SQL 托管实例 且订阅者为 Azure SQL 托管实例 或 Azure SQL 数据库 资源时。

重要

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

[ @subscriber_login = ] N'subscriber_login'

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

[ @subscriber_password = ] N'subscriber_password'

订阅服务器密码。 如果@subscriber_security_mode设置为0,则需要@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 是 系统名,默认为 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 分发代理。

[ @frequency_interval = ] frequency_interval

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

[ @frequency_relative_interval = ] frequency_relative_interval

分发代理的日期。 当@frequency_type,将使用此参数。 @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 第二个
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 是 系统名,默认为 NULL。

[ @subscriber_provider = ] N'subscriber_provider'

注册非 SQL Server 数据源的 OLE DB 访问接口的唯一编程标识符(PROGID)。 @subscriber_provider 是 系统名,默认为 NULL。 @subscriber_provider 必须是分发器上安装的 OLE DB 提供程序唯一的。 @subscriber_provider仅支持非SQL Server订阅者。

[ @subscriber_datasrc = ] N'subscriber_datasrc'

OLE DB提供商理解的数据源名称。 @subscriber_datasrc 为 nvarchar(4000),默认值为 NULL。 @subscriber_datasrc 作为初始化 OLE DB 提供程序的属性传入 DBPROP_INIT_DATASOURCE 。 @subscriber_datasrc仅支持非SQL Server订阅者。

[ @subscriber_location = ] N'subscriber_location'

OLE DB 访问接口所理解的数据库的位置。 @subscriber_location 为 nvarchar(4000),默认值为 NULL。 @subscriber_location 作为初始化 OLE DB 提供程序的属性传递 DBPROP_INIT_LOCATION 。 @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 是 系统名,默认为 NULL。 @subscriber_catalog 作为初始化 OLE DB 提供程序的属性传入 DBPROP_INIT_CATALOG 。 @subscriber_catalog仅支持非SQL Server订阅者。

[ @job_security_mode = ] job_security_mode

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

返回代码值

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 固定服务器角色的成员