sp_addsubscription (Transact-SQL)

發行項
05/07/2013

將訂閱加入發行集中，以及設定訂閱者狀態。這個預存程序執行於發行集資料庫的發行者端。

語法

sp_addsubscription [ @publication = ] 'publication'
    [ , [ @article = ] 'article']
    [ , [ @subscriber = ] 'subscriber' ]
    [ , [ @destination_db = ] 'destination_db' ]
        [ , [ @sync_type = ] 'sync_type' ]
    [ , [ @status = ] 'status'
        [ , [ @subscription_type = ] 'subscription_type' ]
    [ , [ @update_mode = ] 'update_mode' ]
    [ , [ @loopback_detection = ] 'loopback_detection' ]
    [ , [ @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 = ] 'optional_command_line' ]
    [ , [ @reserved = ] 'reserved' ]
    [ , [ @enabled_for_syncmgr= ] 'enabled_for_syncmgr' ]
    [ , [ @offloadagent= ] remote_agent_activation]
    [ , [ @offloadserver= ] 'remote_agent_server_name' ]
    [ , [ @dts_package_name= ] 'dts_package_name' ]
    [ , [ @dts_package_password= ] 'dts_package_password' ]
    [ , [ @dts_package_location= ] 'dts_package_location' ]
    [ , [ @distribution_job_name= ] 'distribution_job_name' ]
    [ , [ @publisher = ] 'publisher' ]
    [ , [ @backupdevicetype = ] 'backupdevicetype' ]
    [ , [ @backupdevicename = ] 'backupdevicename' ]
    [ , [ @mediapassword = ] 'mediapassword' ]
    [ , [ @password = ] 'password' ]
    [ , [ @fileidhint = ] fileidhint ]
    [ , [ @unload = ] unload ]
    [ , [ @subscriptionlsn = ] subscriptionlsn ]
    [ , [ @subscriptionstreams = ] subscriptionstreams ]
    [ , [ @subscriber_type = ] subscriber_type ]

引數

[ @publication=\] 'publication'
這是發行集的名稱。 publication 是 sysname，沒有預設值。
[ @article=\] 'article'
這是發行集訂閱的發行項。 article 是 sysname，預設值是 all。如果是 all，就會將訂閱加入該發行集的所有發行項中。只有 all 或 NULL 值支援在 Oracle 發行者中使用。
[ @subscriber=\] 'subscriber'
這是訂閱者的名稱。 subscriber 是 sysname，預設值是 NULL。
[ @destination\_db=\] 'destination_db'
這是放置複寫資料之目的地資料庫的名稱。 destination_db 是 sysname，預設值是 NULL。當它是 NULL 時，destination_db 會設定為發行集資料庫的名稱。如果是 Oracle 發行者，您必須指定 destination_db。如果是非 SQL Server 訂閱者，請為 destination_db 指定 (預設目的地) 的值。

[ @sync\_type=\] 'sync_type'
這是訂閱同步處理類型。 sync_type 是 nvarchar(255)，而且可以是下列其中一個值：

值	說明
none	訂閱者已有發行資料表的結構描述和初始資料。 [!附註] 這個選項已被取代。請改用 replication support only。
automatic (預設值)	先將發行資料表的結構描述和初始資料傳送給訂閱者。
replication support only	提供在訂閱者自動產生支援更新訂閱之發行項自訂預存程序和觸發程序的功能 (如果適用的話)。假設訂閱者已有發行資料表的結構描述和初始資料。當設定點對點異動複寫拓撲時，請確定拓撲中所有節點的資料都相同。如需詳細資訊，請參閱＜點對點異動複寫＞。不支援非 SQL Server 發行集的訂閱使用這個值。
initialize with backup	從發行集資料庫的備份中，取得發行資料表的結構描述和初始資料。假設訂閱者有權存取發行集資料庫的備份。備份位置和備份媒體類型由 backupdevicename 和 backupdevicetype 來指定。當使用這個選項時，不需要在設定組態期間，默認點對點異動複寫拓撲。不支援非 SQL Server 發行集的訂閱使用這個值。
initialize from lsn	當您要將節點加入至點對點異動複寫拓撲時使用。搭配 @subscriptionlsn 使用可確保所有相關的交易都會複寫至新的節點。假設訂閱者已有發行資料表的結構描述和初始資料。如需詳細資訊，請參閱＜點對點異動複寫＞。

[!附註]

一律會傳送系統資料表和資料。

[ @status=\] 'status'
這是訂閱狀態。 status 是 sysname，預設值是 NULL。如果未明確設定這個參數，複寫會自動將它設定為這些值之一。

值	說明
active	訂閱已初始化且已做好接受變更的準備。當 sync_type 的值是 none、initialize with backup 或 replication support only 時，便會設定這個選項。
subscribed	訂閱需要初始化。當 sync_type 的值是 automatic 時，便會設定這個選項。

[ @subscription\_type=\] 'subscription_type'
這是訂閱的類型。 subscription_type 是 nvarchar(4)，預設值是 push。它可以是 push 或 pull。 push 訂閱的散發代理程式位於散發者端，而 pull 訂閱的散發代理程式位於訂閱者端。 subscription_type 可以是 pull，以便建立發行者已知的具名提取訂閱。如需詳細資訊，請參閱＜訂閱發行集＞。

[!附註]

匿名訂閱不需要使用這個預存程序。

[ @update\_mode=\] 'update_mode'
這是更新的類型。update_mode 是 nvarchar(30)，而且可以是下列其中一個值。

值	說明
read-only (預設值)	訂閱是唯讀的。在訂閱者端的變更不會傳給發行者。
sync tran	啟用立即更新訂閱的支援。不支援 Oracle 發行者使用這個值。
queued tran	啟用佇列更新的訂閱。資料修改可以在訂閱者端進行、儲存在佇列中，再傳播給發行者。不支援 Oracle 發行者使用這個值。
failover	啟用立即更新的訂閱，且利用佇列更新來做為容錯移轉。資料修改可以在訂閱者端進行，再立即傳播給發行者。如果發行者和訂閱者並未連接，便可以變更更新模式，以便將在訂閱者端進行的資料修改儲存在佇列中，直到發行者和訂閱者重新連接為止。不支援 Oracle 發行者使用這個值。
queued failover	將訂閱啟用成能夠改成立即更新模式的佇列更新訂閱。資料修改可以在訂閱者端進行，儲存在佇列中，直到重建訂閱者和發行者之間的連接為止。當建立連續連接時，更新模式可以改成立即更新。不支援 Oracle 發行者使用這個值。

請注意，如果訂閱的發行集允許 DTS，便不接受 sync tran 和 queued tran 值。

[ @loopback\_detection=\] 'loopback_detection'
指定散發代理程式是否會將起源於訂閱者端的交易傳回給訂閱者。 loopback_detection 是 nvarchar(5)，而且可以是下列其中一個值。

值	說明
true	散發代理程式不將起源於訂閱者端的交易傳回給訂閱者。搭配雙向異動複寫來使用。如需詳細資訊，請參閱＜雙向異動複寫＞。
false	散發代理程式將起源於訂閱者端的交易傳回給訂閱者。
NULL (預設值)	針對 SQL Server 訂閱者會自動設定為 true，而針對非 SQL Server 訂閱者，則會自動設定為 false。

[ @frequency\_type=\] frequency_type
這是散發工作的排程頻率。 frequency_type 是 int，而且可以是下列其中一個值。

值

說明

1

一次

2

視需要

4

每日

8

每週

16

每月

32

每月相對

64 (預設值)

自動啟動

128

重複執行
[ @frequency\_interval=\] frequency_interval
這是要套用至 frequency_type 所設定之頻率的值。 frequency_interval 是 int，預設值是 NULL。
[ @frequency\_relative\_interval=\] frequency_relative_interval
這是散發代理程式的日期。當 frequency_type 設定為 32 (每月相對) 時，使用此參數。 frequency_relative_interval 是 int，而且可以是下列其中一個值。

值

說明

1

第一個

2

第二個

4

第三個

8

第四個

16

最後一個

NULL (預設值)
[ @frequency\_recurrence\_factor=\] frequency_recurrence_factor
這是 frequency_type 所使用的循環因數。 frequency_recurrence_factor 是 int，預設值是 NULL。
[ @frequency\_subday=\] frequency_subday
這是在定義的期間內，重新排程的頻率 (以分鐘為單位)。 frequency_subday 是 int，而且可以是下列其中一個值。

值

說明

1

一次

2

秒

4

分鐘

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=\] 'optional_command_line'
這是要執行的選擇性命令提示字元。 optional_command_line 是 nvarchar(4000)，預設值是 NULL。
[ @reserved=\] 'reserved'
僅供參考之用。不支援。我們無法保證未來的相容性。
[ @enabled\_for\_syncmgr=\] 'enabled_for_syncmgr'
這是指是否能夠利用 Microsoft Windows Synchronization Manager 同步處理訂閱。enabled_for_syncmgr 是 nvarchar(5)，預設值是 FALSE。如果是 false，則不使用 Windows Synchronization Manager 註冊訂閱。如果是 true，則使用 Windows Synchronization Manager 來註冊訂閱，而且不需要啟動 SQL Server Management Studio，就可以同步處理。不支援 Oracle 發行者使用這個值。
[ @offloadagent= ] 'remote_agent_activation'
指定是否能從遠端啟動代理程式。 remote_agent_activation 是 bit，預設值是 0。

[!附註]

這個參數已被取代，維護它的目的，只是為了與舊版的指令碼相容。
[ @offloadserver= ] 'remote_agent_server_name'
指定將用來遠端啟用之伺服器的網路名稱。 remote_agent_server_name是 sysname，預設值是 NULL。
[ @dts\_package\_name= ] 'dts_package_name'
指定 Data Transformation Services (DTS) 封裝的名稱。 dts_package_name 是 sysname，預設值是 NULL。例如，若要指定 DTSPub_Package 封裝，這個參數便是 @dts\_package\_name = N'DTSPub_Package'。發送訂閱可以使用這個參數。若要將 DTS 封裝資訊加入提取訂閱中，請使用 sp_addpullsubscription_agent。
[ @dts\_package\_password= ] 'dts_package_password'
指定封裝的密碼 (如果有的話)。 dts_package_password 是 sysname，預設值是 NULL。

[!附註]

如果指定了 dts_package_name，則必須指定密碼。
[ @dts\_package\_location= ] 'dts_package_location'
指定封裝的位置。 dts_package_location 是 nvarchar(12)，預設值是 DISTRIBUTOR。封裝位置可以是散發者或訂閱者。
[ @distribution\_job\_name= ] 'distribution_job_name'
僅供參考之用。不支援。我們無法保證未來的相容性。
[ @publisher= ] 'publisher'
指定非 Microsoft SQL Server 發行者。 publisher 是 sysname，預設值是 NULL。

[!附註]

SQL Server 發行者不應指定 publisher。
[ @backupdevicetype= ] 'backupdevicetype'
指定從備份中初始化訂閱者時所用的備份裝置類型。 backupdevicetype 是 nvarchar(20)，而且可以是下列其中一個值。

值

說明

logical (預設值)

備份裝置是邏輯裝置。

disk

備份裝置是硬碟。

tape

備份裝置是磁帶機。

只有在 sync_method 設定為 initialize_with_backup 時，才使用 backupdevicetype。
[ @backupdevicename= ] 'backupdevicename'
指定從備份中初始化訂閱者時所用的裝置名稱。 backupdevicename 是 nvarchar(1000)，預設值是 NULL。
[ @mediapassword= ] 'mediapassword'
如果媒體格式化時設定了密碼，便指定媒體集的密碼。 mediapassword 是 sysname，預設值是 NULL。

[!附註]

未來的 Microsoft SQL Server 版本將移除這項功能。請避免在新的開發工作中使用這項功能，並規劃修改目前使用這項功能的應用程式。
[ @password= ] 'password'
如果建立備份時設定了密碼，便指定備份的密碼。 password 是 sysname，預設值是 NULL。
[ @fileidhint= ] fileidhint
識別要還原之備份組的序數值。 fileidhint 是 int，預設值是 NULL。
[ @unload= ] unload
指定在從備份初始化完成之後，是否應該卸載磁帶備份裝置。 unload 是 bit，預設值是 1。 1 表示應該卸載磁帶。只有在 backupdevicetype 是 tape 時，才使用 unload。
[ @subscriptionlsn= ] subscriptionlsn
指定記錄序號 (LSN)，而且訂閱應該從這個序號開始傳遞變更至點對點異動複寫拓撲中的節點。與 initialize from lsn 的 @sync\_type 值搭配使用，可確保所有相關的交易都會複寫到新的節點。如需詳細資訊，請參閱＜點對點異動複寫＞。
[ @subscriptionstreams= ] subscriptionstreams
這是在維護許多使用單一執行緒時所提供的交易式特性時，每個散發代理程式可用來將變更批次並行套用在訂閱者上的連接數目。 subscriptionstreams 是 tinyint，預設值是 NULL。支援的值範圍是 1-64。不支援非 SQL Server 訂閱者、Oracle 發行者或點對點訂閱使用這個參數。每當使用訂閱資料流時，msreplication_subscriptions 資料表就會加入其他資料列 (每個資料流 1 個資料列) 並將 agent_id 設定為 NULL。

[!附註]

Subscriptionstreams 不適用於設定為傳遞 Transact-SQL 的發行項。若要使用 subscriptionstreams，請改將發行項設定為傳遞預存程序呼叫。
[ @subscriber\_type=\] subscriber_type
這是訂閱者的類型。 subscriber_type 是 tinyint，而且可以是下列其中一個值。

值

說明

0 (預設值)

SQL Server 訂閱者

1

ODBC 資料來源伺服器

2

Microsoft Jet 資料庫

3

OLE DB 提供者

值	說明
1	一次
2	視需要
4	每日
8	每週
16	每月
32	每月相對
64 (預設值)	自動啟動
128	重複執行

值	說明
1	第一個
2	第二個
4	第三個
8	第四個
16	最後一個
NULL (預設值)

值	說明
1	一次
2	秒
4	分鐘
8	小時
NULL

值	說明
logical (預設值)	備份裝置是邏輯裝置。
disk	備份裝置是硬碟。
tape	備份裝置是磁帶機。

值	說明
0 (預設值)	SQL Server 訂閱者
1	ODBC 資料來源伺服器
2	Microsoft Jet 資料庫
3	OLE DB 提供者

傳回碼值

0 (成功) 或 1 (失敗)

備註

sp_addsubscription 用於快照式複寫和異動複寫中。

當 sysadmin (系統管理員) 固定伺服器角色的成員執行 sp_addsubscription 來建立發送訂閱時，系統會隱含地建立散發代理程式作業，而且會利用 SQL Server Agent 服務帳戶來執行這項作業。我們建議您執行 sp_addpushsubscription_agent，以及在 @job\_login 和 @job\_password 中指定特定代理程式專用的不同 Windows 帳戶的認證。如需詳細資訊，請參閱＜複寫代理程式安全性模型＞。

sp_addsubscription 可防止 ODBC 和 OLE DB 訂閱者存取符合下列狀況的發行集：

在呼叫 sp_addpublication 時，利用原生 sync_method 來建立。
包含利用 pre_creation_cmd 參數值是 3 (截斷) 的 sp_addarticle 預存程序加入發行集的發行項。
嘗試將 update_mode 設為 sync tran。
有設定成使用參數化陳述式的發行項。

另外，如果發行集將 allow_queued_tran 選項設為 true (啟用訂閱者端的變更佇列，直到能夠在發行者套用變更為止)，發行項中的時間戳記資料行便會編寫成 timestamp，而且該資料行的變更會傳給訂閱者。訂閱者會產生和更新時間戳記資料行值。對於 ODBC 或 OLE DB 訂閱者而言，如果嘗試訂閱 allow_queued_tran 設為 true 的發行集及含有時間戳記資料行的發行項，sp_addsubscription 便會失敗。

如果訂閱並未使用 DTS 封裝，它便不能訂閱設為 allow_transformable_subscriptions 的發行集。如果發行集的資料表必須複寫到 DTS 訂閱和非 DTS 訂閱，則必須建立兩個個別的發行集，每個訂閱類型各一個發行集。

選取 sync_type 選項 replication support only、initialize with backup 或 initialize from lsn 時，記錄讀取器代理程式必須在執行 sp_addsubscription 之後執行，讓設定指令碼寫入至散發資料庫。記錄讀取器代理程式必須在屬於系統管理員 (sysadmin) 固定伺服器角色成員的 Windows 帳戶底下執行。當 sync_type 選項設為 Automatic 時，不需要任何特殊的記錄讀取器代理程式動作。

權限

只有 sysadmin (系統管理員) 固定伺服器角色或 db_owner 固定資料庫角色的成員，才能夠執行 sp_addsubscription。如果是提取訂閱，使用者只要有發行集存取清單中的登入，便能夠執行 sp_addsubscription。

範例

-- 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'AdventureWorks2012Replica';

--Add a push subscription to a transactional publication.
USE [AdventureWorks2012]
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