sp_addmergepullsubscription_agent (Transact-SQL)

S’applique à :SQL ServerAzure SQL Managed Instance

Ajoute un nouveau travail d'Agent permettant de planifier la synchronisation d'un abonnement par extraction de données (pull) à une publication de fusion. Cette procédure stockée est exécutée sur la base de données d'abonnement de l'Abonné.

Conventions de la syntaxe Transact-SQL

Syntaxe

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

Arguments

[ @name = ] N’name'

Nom de l’agent. @name est sysname, avec la valeur par défaut NULL.

[ @publisher = ] N’publisher'

Nom du serveur de publication. @publisher est sysname, sans valeur par défaut.

[ @publisher_db = ] N’publisher_db'

Nom de la base de données du serveur de publication. @publisher_db est sysname, sans valeur par défaut.

[ @publication = ] N’publication'

Nom de la publication. @publication est sysname, sans valeur par défaut.

[ @publisher_security_mode = ] publisher_security_mode

Mode de sécurité à utiliser lors de la connexion à un serveur de publication lors de la synchronisation. @publisher_security_mode est int, avec une valeur par défaut de 1. Les valeurs suivantes définissent le mode de sécurité :

  • 0 spécifie l’authentification SQL Server.
  • 1spécifie Authentification Windows.
  • 2 spécifie l’authentification par mot de passe Microsoft Entra, à partir de SQL Server 2022 (16.x) CU 6.
  • 3 spécifie l’authentification intégrée Microsoft Entra, à compter de SQL Server 2022 (16.x) CU 6.

Important

Lorsque c'est possible, utilisez l'authentification Windows.

[ @publisher_login = ] N’publisher_login'

Connexion à utiliser lors de la connexion à un serveur de publication lors de la synchronisation. @publisher_login est sysname, avec la valeur par défaut NULL.

[ @publisher_password = ] N’publisher_password'

Mot de passe utilisé lors de la connexion au serveur de publication. @publisher_password est sysname, avec la valeur par défaut NULL.

Important

N'utilisez pas de mot de passe vide. Utilisez un mot de passe fort. Lorsque c'est possible, demande aux utilisateurs de fournir les informations d'identification au moment de l'exécution. Si vous devez enregistrer les informations d'identification dans un fichier de script, vous devez sécuriser le fichier pour empêcher un accès non autorisé.

[ @publisher_encrypted_password = ] publisher_encrypted_password

La définition @publisher_encrypted_password n’est plus prise en charge. Toute tentative de définition de ce paramètre 1 de bit entraîne une erreur.

[ @subscriber = ] N’subscriber'

Nom de l'Abonné. @subscriber est sysname, avec la valeur par défaut NULL.

[ @subscriber_db = ] N’subscriber_db'

Nom de la base de données d’abonnement. @subscriber_db est sysname, avec la valeur par défaut NULL.

[ @subscriber_security_mode = ] subscriber_security_mode

Mode de sécurité à utiliser lors de la connexion à un Abonné lors de la synchronisation. @subscriber_security_mode est int, avec la valeur par défaut 1. Si 0, spécifie l’authentification SQL Server. Si 1, spécifie l’authentification Windows.

Remarque

Ce paramètre est déconseillé et est maintenu pour la compatibilité descendante des scripts. Si une valeur est précisée pour ce paramètre, un message d'avertissement est retourné mais la valeur reste ignorée.

[ @subscriber_login = ] N’subscriber_login'

Connexion de l’Abonné à utiliser lors de la connexion à un Abonné lors de la synchronisation. @subscriber_login est sysname, avec la valeur par défaut NULL. @subscriber_login est obligatoire si subscriber_security_mode a la valeur 0.

Remarque

Ce paramètre est déconseillé et est maintenu pour la compatibilité descendante des scripts. Si une valeur est précisée pour ce paramètre, un message d'avertissement est retourné mais la valeur reste ignorée.

[ @subscriber_password = ] N’subscriber_password'

Mot de passe de l’Abonné pour l’authentification SQL Server. @subscriber_password est sysname, avec la valeur par défaut NULL. @subscriber_password est nécessaire si @subscriber_security_mode a la valeur 0.

Remarque

Ce paramètre est déconseillé et est maintenu pour la compatibilité descendante des scripts. Si une valeur est précisée pour ce paramètre, un message d'avertissement est retourné mais la valeur reste ignorée.

[ @distributor = ] N’distributor'

Nom du serveur de distribution. @distributor est sysname, avec une valeur par défaut de @publisher ; autrement dit, le serveur de publication est également le serveur de distribution.

[ @distributor_security_mode = ] distributor_security_mode

Mode de sécurité à utiliser lors de la connexion à un serveur de distribution lors de la synchronisation. @distributor_security_mode est int, avec la valeur par défaut 1. Les valeurs suivantes définissent le mode de sécurité :

  • 0 spécifie l’authentification SQL Server.
  • 1spécifie Authentification Windows.
  • 2 spécifie l’authentification par mot de passe Microsoft Entra, à partir de SQL Server 2022 (16.x) CU 6.
  • 3 spécifie l’authentification intégrée Microsoft Entra, à compter de SQL Server 2022 (16.x) CU 6.
  • 4 spécifie l’authentification par jeton Microsoft Entra, à partir de SQL Server 2022 (16.x) CU 6.

Important

Lorsque c'est possible, utilisez l'authentification Windows.

[ @distributor_login = ] N’distributor_login'

Connexion du serveur de distribution à utiliser lors de la connexion à un serveur de distribution lors de la synchronisation. @distributor_login est sysname, avec la valeur par défaut NULL. @distributor_login est obligatoire si @distributor_security_mode a la valeur 0.

[ @distributor_password = ] N’distributor_password'

Mot de passe du serveur de distribution. @distributor_password est sysname, avec la valeur par défaut NULL. @distributor_password est nécessaire si @distributor_security_mode a la valeur 0.

Important

N'utilisez pas de mot de passe vide. Utilisez un mot de passe fort. Lorsque c'est possible, demande aux utilisateurs de fournir les informations d'identification au moment de l'exécution. Si vous devez enregistrer les informations d'identification dans un fichier de script, vous devez sécuriser le fichier pour empêcher un accès non autorisé.

[ @encrypted_password = ] encrypted_password

La définition @encrypted_password n’est plus prise en charge. Toute tentative de définition de ce paramètre 1 de bit entraîne une erreur.

[ @frequency_type = ] frequency_type

Valeur indiquant quand le Agent de fusion s’exécute. @frequency_type est int et peut être l’une de ces valeurs.

Valeur Description
1 Ponctuelle
2 À la demande
4 Quotidiennement
8 Hebdomadaire
16 Mensuelle
32 Mensuelle relative
64 Autostart
128 Récurrent
NULL (valeur par défaut)

Remarque

La spécification d’une valeur des causes de l’exécution du 64 Agent de fusion en mode continu. Cela correspond à la définition du -Continuous paramètre de l’agent. Pour plus d’informations, voir Replication Merge Agent.

[ @frequency_interval = ] frequency_interval

Jour(s) où l'Agent de fusion s'exécute. @frequency_interval est int, avec une valeur par défaut NULL, et peut être l’une de ces valeurs.

Valeur Description
1 Dimanche
2 Lundi
3 Mardi
4 Mercredi
5 Jeudi
6 Vendredi
7 Samedi
8 Jour
9 Jours de la semaine
10 Jours de week-end
NULL (valeur par défaut)

[ @frequency_relative_interval = ] frequency_relative_interval

Date du Agent de fusion. Ce paramètre est utilisé lorsque @frequency_type est défini 32 sur (relatif mensuel). @frequency_relative_interval est int et peut être l’une de ces valeurs.

Valeur Description
1 Première
2 Second
4 Third
8 Quatrième
16 Dernier
NULL (valeur par défaut)

[ @frequency_recurrence_factor = ] frequency_recurrence_factor

Facteur de périodicité utilisé par @frequency_type. @frequency_recurrence_factor est int, avec la valeur par défaut NULL.

[ @frequency_subday = ] frequency_subday

Fréquence à replanifier pendant la période définie. @frequency_subday est int et peut être l’une de ces valeurs.

Valeur Description
1 Une fois
2 Second
4 Minute
8 Hour
NULL (valeur par défaut)

[ @frequency_subday_interval = ] frequency_subday_interval

Intervalle de @frequency_subday. @frequency_subday_interval est int, avec la valeur par défaut NULL.

[ @active_start_time_of_day = ] active_start_time_of_day

Heure du jour où la Agent de fusion est planifiée pour la première fois, mise en forme comme HHmmss. @active_start_time_of_day est int, avec la valeur par défaut NULL.

[ @active_end_time_of_day = ] active_end_time_of_day

Heure du jour où la Agent de fusion cesse d’être planifiée, mise en forme comme HHmmss. @active_end_time_of_day est int, avec la valeur par défaut NULL.

[ @active_start_date = ] active_start_date

Date à laquelle la Agent de fusion est planifiée pour la première fois, mise en forme en tant que yyyyMMdd. @active_start_date est int, avec une valeur par défaut de NULL.

[ @active_end_date = ] active_end_date

Date à laquelle la Agent de fusion cesse d’être planifiée, mise en forme comme yyyyMMddsuit : @active_end_date est int, avec une valeur par défaut de NULL.

[ @optional_command_line = ] N’optional_command_line'

Invite de commandes facultative fournie au Agent de fusion. @optional_command_line est nvarchar(255), avec une valeur par défaut d’une chaîne vide.

Permet de fournir des paramètres supplémentaires à l'Agent de fusion, comme dans l'exemple suivant où le délai d'expiration par défaut de la requête est augmenté jusqu'à 600 secondes :

@optional_command_line = N'-QueryTimeOut 600'

[ @merge_jobid = ] sortie de merge_jobid

Paramètre de sortie de l’ID de travail. @merge_jobid est un paramètre OUTPUT de type binary(16), avec une valeur par défaut NULL.

[ @enabled_for_syncmgr = ] N’enabled_for_syncmgr'

Spécifie si l'abonnement peut être synchronisé à l'aide du Gestionnaire de synchronisation Windows. @enabled_for_syncmgr est nvarchar(5), avec la valeur par défaut false. Si false, l’abonnement n’est pas inscrit auprès du Gestionnaire de synchronisation. Si true, l’abonnement est inscrit auprès du Gestionnaire de synchronisation et peut être synchronisé sans démarrer SQL Server Management Studio.

[ @ftp_address = ] N’ftp_address'

Pour compatibilité descendante uniquement.

[ @ftp_port = ] ftp_port

Pour compatibilité descendante uniquement.

[ @ftp_login = ] N’ftp_login'

Pour compatibilité descendante uniquement.

[ @ftp_password = ] N’ftp_password'

Pour compatibilité descendante uniquement.

[ @alt_snapshot_folder = ] N’alt_instantané_folder'

Spécifie l'emplacement à partir duquel récupérer les fichiers d'instantané. @alt_instantané_folder est nvarchar(255), avec la valeur par défaut NULL. Si NULL, les fichiers instantané sont récupérés à partir de l’emplacement par défaut spécifié par le serveur de publication.

[ @working_directory = ] N’working_directory'

Nom du répertoire de travail utilisé pour stocker temporairement les données et les fichiers de schéma de la publication lorsque FTP est utilisé pour transférer des fichiers instantané. @working_directory est nvarchar(255), avec la valeur par défaut NULL.

[ @use_ftp = ] N’use_ftp'

Spécifie que le protocole FTP est utilisé à la place du protocole normal pour l'extraction des instantanés. @use_ftp est nvarchar(5), avec la valeur par défaut false.

[ @reserved = ] N’reserved'

Identifié à titre d'information uniquement. Non pris en charge. La compatibilité future n'est pas garantie.

[ @use_interactive_resolver = ] N’use_interactive_resolver'

Utilise la résolution interactive des conflits pour tous les articles autorisant la résolution interactive. @use_interactive_resolver est nvarchar(5), avec la valeur par défaut false.

[ @offloadagent = ] N’offloadagent'

Remarque

Ce paramètre est déconseillé et est maintenu pour la compatibilité descendante des scripts. Définir remote_agent_activation sur une valeur autre que false la génération d’une erreur.

[ @offloadserver = ] N’offloadserver'

Remarque

Ce paramètre est déconseillé et est maintenu pour la compatibilité descendante des scripts. La définition de remote_agent_server_name sur n’importe quelle valeur non NULL génère une erreur.

[ @job_name = ] N’job_name'

Nom d’un travail d’agent existant. @job_name est sysname, avec la valeur par défaut NULL. Ce paramètre n'est indiqué que lorsque l'abonnement est synchronisé grâce à un travail existant plutôt qu'un nouveau travail (étant le comportement par défaut). Si vous n’êtes pas membre du rôle serveur fixe sysadmin , vous devez spécifier @job_login et @job_password lorsque vous spécifiez @job_name.

[ @dynamic_snapshot_location = ] N’dynamic_instantané_location'

Chemin d’accès au dossier dans lequel les fichiers instantané seront lus si une instantané de données filtrées doit être utilisée. @dynamic_instantané_location est nvarchar(260), avec la valeur par défaut NULL. Pour plus d’informations, consultez Filtres paramétrables - Filtres de lignes paramétrables.

[ @use_web_sync = ] use_web_sync

Indique que la synchronisation Web est activée. @use_web_sync est bit, avec la valeur par défaut 0. 1 spécifie que l’abonnement par extraction peut être synchronisé sur Internet à l’aide de HTTP.

[ @internet_url = ] N’internet_url'

Emplacement de l’écouteur de réplication (REPLISAPI.DLL) pour la synchronisation Web. @internet_url est nvarchar(260), avec la valeur par défaut NULL. @internet_url est une URL complète, au format http://server.domain.com/directory/replisapi.dll. Si le serveur est configuré de manière à être à l'écoute sur un port autre que le port 80, le numéro de port doit également être fourni sous la forme http://server.domain.com:<portnumber>/directory/replisapi.dll, où <portnumber> représente le port.

[ @internet_login = ] N’internet_login'

Connexion utilisée par l’Agent de fusion lors de la connexion au serveur Web qui héberge la synchronisation web à l’aide de l’authentification http de base. @internet_login est sysname, avec la valeur par défaut NULL.

[ @internet_password = ] N’internet_password'

Mot de passe utilisé par l’Agent de fusion lors de la connexion au serveur Web qui héberge la synchronisation web à l’aide de l’authentification http de base. @internet_password est nvarchar(524), avec la valeur par défaut NULL.

Important

N'utilisez pas de mot de passe vide. Utilisez un mot de passe fort.

[ @internet_security_mode = ] internet_security_mode

Méthode d’authentification utilisée par l’Agent de fusion lors de la connexion au serveur Web lors de la synchronisation web à l’aide du protocole HTTPS. @internet_security_mode est int et peut être l’une de ces valeurs.

Valeur Description
0 L'authentification de base est utilisée.
1 (valeur par défaut) L'authentification intégrée de Windows est utilisée.

Remarque

Il est recommandé d'utiliser l'authentification de base pour la synchronisation Web. Pour utiliser la synchronisation web, vous devez établir une connexion TLS au serveur Web. Pour plus d’informations, consultez Configurer la synchronisation Web.

[ @internet_timeout = ] internet_timeout

Durée (en secondes) avant l'expiration d'une demande de synchronisation Web. @internet_timeout est int, avec une valeur par défaut de 300 secondes.

[ @hostname = ] N’hostname'

Remplace la valeur du moment où HOST_NAME() cette fonction est utilisée dans la WHERE clause d’un filtre paramétrable. @hostname est sysname, avec la valeur par défaut NULL.

[ @job_login = ] N’job_login'

Connexion pour le compte Windows sous lequel l’agent s’exécute. @job_login est nvarchar(257), avec la valeur par défaut NULL. Ce compte Windows est toujours utilisé pour les connexions d'Agent à l'Abonné et pour les connexions au serveur de distribution et au serveur de publication lors de l'utilisation de l'authentification intégrée de Windows.

[ @job_password = ] N’job_password'

Mot de passe du compte Windows sous lequel l’agent s’exécute. @job_password est sysname, avec la valeur par défaut NULL.

Attention

Ne stockez pas les informations d’authentification dans les fichiers de script. Pour une sécurité optimale, les noms de connexion et les mots de passe doivent être fournis au moment de l'exécution.

Valeurs des codes de retour

0 (réussite) ou 1 (échec).

Notes

sp_addmergepullsubscription_agent est utilisé dans la réplication de fusion et utilise des fonctionnalités similaires à sp_addpullsubscription_agent.

Pour obtenir un exemple de spécification correcte des paramètres de sécurité lors de l’exécution sp_addmergepullsubscription_agent, consultez Créer un abonnement par extraction.

Exemples


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

Autorisations

Seuls les membres du rôle serveur fixe sysadmin ou db_owner rôle de base de données fixe peuvent s’exécuter sp_addmergepullsubscription_agent.