sp_addmergepullsubscription_agent (Transact-SQL)
向合并发布添加一个用于计划请求订阅同步的新代理作业。 此存储过程在订阅服务器的订阅数据库中执行。
语法
sp_addmergepullsubscription_agent
[ [ @name = ] N'name' ]
, [ @publisher = ] N'publisher'
, [ @publisher_db = ] N'publisher_db'
, [ @publication = ] N'publication'
[ , [ @publisher_security_mode = ] publisher_security_mode ]
[ , [ @publisher_login = ] N'publisher_login' ]
[ , [ @publisher_password = ] N'publisher_password' ]
[ , [ @publisher_encrypted_password = ] publisher_encrypted_password ]
[ , [ @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' ]
[ , [ @distributor_security_mode = ] distributor_security_mode ]
[ , [ @distributor_login = ] N'distributor_login' ]
[ , [ @distributor_password = ] N'distributor_password' ]
[ , [ @encrypted_password = ] encrypted_password ]
[ , [ @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 ]
[ , [ @optional_command_line = ] N'optional_command_line' ]
[ , [ @merge_jobid = ] merge_jobid OUTPUT ]
[ , [ @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' ]
[ , [ @reserved = ] N'reserved' ]
[ , [ @use_interactive_resolver = ] N'use_interactive_resolver' ]
[ , [ @offloadagent = ] N'offloadagent' ]
[ , [ @offloadserver = ] N'offloadserver' ]
[ , [ @job_name = ] N'job_name' ]
[ , [ @dynamic_snapshot_location = ] N'dynamic_snapshot_location' ]
[ , [ @use_web_sync = ] use_web_sync ]
[ , [ @internet_url = ] N'internet_url' ]
[ , [ @internet_login = ] N'internet_login' ]
[ , [ @internet_password = ] N'internet_password' ]
[ , [ @internet_security_mode = ] internet_security_mode ]
[ , [ @internet_timeout = ] internet_timeout ]
[ , [ @hostname = ] N'hostname' ]
[ , [ @job_login = ] N'job_login' ]
[ , [ @job_password = ] N'job_password' ]
[ ; ]
参数
[ @name = ] N'name'
代理的名称。 @name为 sysname，默认值为 NULL.
[ @publisher = ] N'publisher'
发布服务器的名称。 @publisher为 sysname，无默认值。
[ @publisher_db = ] N'publisher_db'
发布服务器数据库的名称。 @publisher_db 为 sysname，无默认值。
[ @publication = ] N'publication'
发布的名称。 @publication 为 sysname，无默认值。
[ @publisher_security_mode = ] publisher_security_mode
同步时连接到发布服务器时要使用的安全模式。 @publisher_security_mode为 int，默认值为 1. 以下值定义安全模式：
0指定 SQL Server 身份验证。1指定Windows 身份验证。2指定 Microsoft Entra 密码身份验证，从 SQL Server 2022 （16.x） CU 6 开始。3指定 Microsoft Entra 集成身份验证，从 SQL Server 2022 （16.x） CU 6 开始。
重要
请尽可能使用 Windows 身份验证。
[ @publisher_login = ] N'publisher_login'
同步时连接到发布服务器时要使用的登录名。 @publisher_login为 sysname，默认值为 NULL.
[ @publisher_password = ] N'publisher_password'
连接到发布服务器时使用的密码。 @publisher_password为 sysname，默认值为 NULL.
重要
不要使用空密码。 请使用强密码。 如果可能，请在运行时提示用户输入安全凭据。 如果必须在脚本文件中存储凭据，则必须保护文件以防止未经授权的访问。
[ @publisher_encrypted_password = ] publisher_encrypted_password
不再支持设置 @publisher_encrypted_password 。 尝试设置此 位 参数以 1 导致错误。
[ @subscriber = ] N'subscriber'
订阅服务器的名称。 @subscriber为 sysname，默认值为 NULL.
[ @subscriber_db = ] N'subscriber_db'
订阅数据库的名称。 @subscriber_db为 sysname，默认值为 NULL.
[ @subscriber_security_mode = ] subscriber_security_mode
同步时连接到订阅服务器时要使用的安全模式。 @subscriber_security_mode为 int，默认值为 1. 如果 0指定 SQL Server 身份验证。 如果 1指定 Windows 身份验证。
注意
此参数已弃用，并维护脚本的向后兼容性。 如果为此参数指定了值，则返回警告消息，但忽略该值。
[ @subscriber_login = ] N'subscriber_login'
同步时连接到订阅服务器的订阅服务器时要使用的订阅服务器登录名。 @subscriber_login为 sysname，默认值为 NULL. 如果subscriber_security_mode设置为 0，则需要@subscriber_login。
注意
此参数已弃用，并维护脚本的向后兼容性。 如果为此参数指定了值，则返回警告消息，但忽略该值。
[ @subscriber_password = ] N'subscriber_password'
SQL Server 身份验证的订阅服务器密码。 @subscriber_password为 sysname，默认值为 NULL. 如果@subscriber_security_mode设置为 0，则需要@subscriber_password 。
注意
此参数已弃用，并维护脚本的向后兼容性。 如果为此参数指定了值，则返回警告消息，但忽略该值。
[ @distributor = ] N'distributor'
分发服务器的名称。 @distributor为 sysname，默认值为 @publisher;也就是说，发布服务器也是分发服务器。
[ @distributor_security_mode = ] distributor_security_mode
同步时连接到分发服务器时要使用的安全模式。 @distributor_security_mode为 int，默认值为 1. 以下值定义安全模式：
0指定 SQL Server 身份验证。1指定Windows 身份验证。2指定 Microsoft Entra 密码身份验证，从 SQL Server 2022 （16.x） CU 6 开始。3指定 Microsoft Entra 集成身份验证，从 SQL Server 2022 （16.x） CU 6 开始。4指定 Microsoft Entra 令牌身份验证，从 SQL Server 2022 （16.x） CU 6 开始。
重要
请尽可能使用 Windows 身份验证。
[ @distributor_login = ] N'distributor_login'
同步时连接到分发服务器的分发服务器时要使用的分发服务器登录名。 @distributor_login为 sysname，默认值为 NULL. 如果@distributor_security_mode设置为0@distributor_login，则需要@distributor_login。
[ @distributor_password = ] N'distributor_password'
分发服务器密码。 @distributor_password为 sysname，默认值为 NULL. 如果@distributor_security_mode设置为 0，则需要@distributor_password 。
重要
不要使用空密码。 请使用强密码。 如果可能，请在运行时提示用户输入安全凭据。 如果必须在脚本文件中存储凭据，则必须保护文件以防止未经授权的访问。
[ @encrypted_password = ] encrypted_password
不再支持设置 @encrypted_password 。 尝试设置此 位 参数以 1 导致错误。
[ @frequency_type = ] frequency_type
一个值，该值指示合并代理何时运行。 @frequency_type为 int，可以是这些值之一。
| 值 | 说明 |
|---|---|
1 |
一次 |
2 |
按需 |
4 |
每日 |
8 |
每周 |
16 |
每月 |
32 |
与“每月”选项相关 |
64 |
自动启动 |
128 |
定期 |
NULL（默认值） |
注意
指定一个值，64使合并代理在连续模式下运行。 这对应于设置 -Continuous 代理的参数。 有关详细信息，请参阅 Replication Merge Agent。
[ @frequency_interval = ] frequency_interval
合并代理在星期几运行。 @frequency_interval为 int，默认值NULL为 ，可以是这些值之一。
| 值 | 说明 |
|---|---|
1 |
星期日 |
2 |
星期一 |
3 |
星期二 |
4 |
星期三 |
5 |
星期四 |
6 |
星期五 |
7 |
星期六 |
8 |
日 |
9 |
工作日 |
10 |
周末 |
NULL（默认值） |
[ @frequency_relative_interval = ] frequency_relative_interval
合并代理的日期。 当@frequency_type设置为32（每月相对）时，将使用此参数。 @frequency_relative_interval为 int，可以是其中一个值。
| 值 | 说明 |
|---|---|
1 |
第一个 |
2 |
第二个 |
4 |
第三个 |
8 |
第四 |
16 |
Last |
NULL（默认值） |
[ @frequency_recurrence_factor = ] frequency_recurrence_factor
@frequency_type使用的重复因子。 @frequency_recurrence_factor为 int，默认值为 NULL.
[ @frequency_subday = ] frequency_subday
在定义的时间段内重新安排的频率。 @frequency_subday 为 int，可以是以下值之一。
| 值 | 说明 |
|---|---|
1 |
一次 |
2 |
Second |
4 |
Minute |
8 |
小时 |
NULL（默认值） |
[ @frequency_subday_interval = ] frequency_subday_interval
@frequency_subday的间隔。 @frequency_subday_interval为 int，默认值为 NULL.
[ @active_start_time_of_day = ] active_start_time_of_day
第一次计划合并代理的时间，格式为 HHmmss。 @active_start_time_of_day为 int，默认值为 NULL.
[ @active_end_time_of_day = ] active_end_time_of_day
合并代理停止计划的时间，格式为 HHmmss。 @active_end_time_of_day为 int，默认值为 NULL.
[ @active_start_date = ] active_start_date
第一次计划合并代理的日期，格式为 yyyyMMdd。 @active_start_date为 int，默认值为 NULL.
[ @active_end_date = ] active_end_date
合并代理停止计划的日期，格式为 yyyyMMdd。 @active_end_date为 int，默认值为 NULL.
[ @optional_command_line = ] N'optional_command_line'
提供给合并代理的可选命令提示符。 @optional_command_line 为 nvarchar（255），默认值为空字符串。
可用于向合并代理提供其他参数，例如在以下示例中，将默认的查询超时值增加到 600 秒：
@optional_command_line = N'-QueryTimeOut 600'
[ @merge_jobid = ] merge_jobid OUTPUT
作业 ID 的输出参数。 @merge_jobid是二进制类型的 OUTPUT 参数（16），默认值为 NULL.
[ @enabled_for_syncmgr = ] N'enabled_for_syncmgr'
指定是否可以通过 Windows 同步管理器同步订阅。 @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_快照_folder'
指定快照文件的选取位置。 @alt_快照_folder为 nvarchar（255），默认值为 NULL. 如果NULL，快照文件将从发布服务器指定的默认位置选取。
[ @working_directory = ] N'working_directory'
当 FTP 用于传输快照文件时，用于临时存储发布的数据和架构文件的工作目录的名称。 @working_directory为 nvarchar（255），默认值为 NULL.
[ @use_ftp = ] N'use_ftp'
指定使用 FTP 而不使用典型的协议检索快照。 @use_ftp为 nvarchar（5），默认值为 false.
[ @reserved = ] N'reserved'
标识为仅供参考。 不支持。 不保证以后的兼容性。
[ @use_interactive_resolver = ] N'use_interactive_resolver'
使用交互式冲突解决程序解决所有允许交互式解决方法的项目的冲突。 @use_interactive_resolver为 nvarchar（5），默认值为 false.
[ @offloadagent = ] N'offloadagent'
注意
此参数已弃用，并维护脚本的向后兼容性。 将 remote_agent_activation 设置为非 false 生成错误的值。
[ @offloadserver = ] N'offloadserver'
注意
此参数已弃用，并维护脚本的向后兼容性。 将 remote_agent_server_name 设置为任何非 NULL 值将生成错误。
[ @job_name = ] N'job_name'
现有代理作业的名称。 @job_name为 sysname，默认值为 NULL. 只有在使用现有作业而不是新创建的作业（此为默认设置）来同步订阅时，才需要指定此参数。 如果你不是 sysadmin 固定服务器角色的成员，则必须在指定@job_name时指定@job_login和@job_password。
[ @dynamic_snapshot_location = ] N'dynamic_快照_location'
在使用已筛选的数据快照时要读取的快照文件所在文件夹的路径。 @dynamic_快照_location为 nvarchar（260），默认值为 NULL. 有关详细信息，请参阅 参数化筛选器 - 参数化行筛选器。
[ @use_web_sync = ] use_web_sync
指示已启用 Web 同步。 @use_web_sync 为 位，默认值为 0. 1 指定可以使用 HTTP 通过 Internet 同步请求订阅。
[ @internet_url = ] N'internet_url'
用于 Web 同步的 副本 (replica)tion 侦听器 （REPLISAPI.DLL） 的位置。 @internet_url为 nvarchar（260），默认值为 NULL. @internet_url 格式为完全限定的 URL http://server.domain.com/directory/replisapi.dll。 如果将服务器配置为侦听端口 80 以外的端口，则提供的端口号的格式也必须为 http://server.domain.com:<portnumber>/directory/replisapi.dll，其中的 <portnumber> 表示端口。
[ @internet_login = ] N'internet_login'
连接到使用 HTTP 基本身份验证托管 Web 同步的 Web 服务器时，合并代理使用的登录名。 @internet_login为 sysname，默认值为 NULL.
[ @internet_password = ] N'internet_password'
合并代理使用 HTTP 基本身份验证连接到托管 Web 同步的 Web 服务器时使用的密码。 @internet_password为 nvarchar（524），默认值为 NULL.
重要
不要使用空密码。 请使用强密码。
[ @internet_security_mode = ] internet_security_mode
使用 HTTPS 在 Web 同步期间连接到 Web 服务器时合并代理使用的身份验证方法。 @internet_security_mode为 int，可以是其中一个值。
| 值 | 说明 |
|---|---|
0 |
使用基本身份验证。 |
1（默认值） |
使用 Windows 集成身份验证。 |
注意
建议您将基本身份验证与 Web 同步结合使用。 若要使用 Web 同步，必须建立与 Web 服务器的 TLS 连接。 有关详细信息，请参阅 Configure Web Synchronization。
[ @internet_timeout = ] internet_timeout
表示 Web 同步请求在多长时间之后过期的时间长度（秒）。 @internet_timeout为 int，默认值为300秒。
[ @hostname = ] N'hostname'
重写参数化筛选器子句中使用WHERE此函数时的值HOST_NAME()。 @hostname为 sysname，默认值为 NULL.
[ @job_login = ] N'job_login'
运行代理的 Windows 帐户的登录名。 @job_login 为 nvarchar（257），默认值为 NULL. 使用 Windows 集成身份验证时，该 Windows 帐户始终用于到订阅服务器的代理连接及到分发服务器和发布服务器的连接。
[ @job_password = ] N'job_password'
运行代理的 Windows 帐户的密码。 @job_password为 sysname，默认值为 NULL.
注意
不要将身份验证信息存储在脚本文件中。 为保证安全性，应当在运行时再提供登录名和密码。
返回代码值
0（成功）或 1（失败）。
备注
sp_addmergepullsubscription_agent用于合并副本 (replica)，并使用类似于sp_addpullsubscription_agent的功能。
有关如何在执行 sp_addmergepullsubscription_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;
DECLARE @hostname AS sysname;
SET @publication = N'AdvWorksSalesOrdersMerge';
SET @publisher = $(PubServer);
SET @publicationDB = N'AdventureWorks2022';
SET @hostname = N'adventure-works\david8';
-- At the subscription database, create a pull subscription
-- to a merge publication.
USE [AdventureWorks2022Replica]
EXEC sp_addmergepullsubscription
@publisher = @publisher,
@publication = @publication,
@publisher_db = @publicationDB;
-- Add an agent job to synchronize the pull subscription.
EXEC sp_addmergepullsubscription_agent
@publisher = @publisher,
@publisher_db = @publicationDB,
@publication = @publication,
@distributor = @publisher,
@job_login = $(Login),
@job_password = $(Password),
@hostname = @hostname;
GO
权限
只有 sysadmin 固定服务器角色的成员或db_owner固定数据库角色的成员才能执行sp_addmergepullsubscription_agent。
相关内容
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈