Help Center/ Relational Database Service/ API Reference/ API v3 (Recommended)/ Publications and Subscriptions (RDS for SQL Server)/ Creating a Publication

Updated on 2025-12-09 GMT+08:00

View PDF

Creating a Publication

Function

This API is used to create a publication for a DB instance.

Before calling this API, learn how to authenticate it.
Before calling this API, learn about request header parameters.

Authorization Information

Each account has all the permissions required to call all APIs, but IAM users must be assigned the required permissions.

If you are using role/policy-based authorization, see Permissions and Supported Actions for details on the required permissions.
If you are using identity policy-based authorization, the following identity policy-based permissions are required.

Action	Access Level	Resource Type (*: required)	Condition Key	Alias	Dependencies
rds:instance:update	write	-	-	rds:instance:modify	-

URI

URI format
POST /v3/{project_id}/instances/{instance_id}/replication/publications

Parameter description

**Table 1** Parameters
Parameter	Mandatory	Description
project_id	Yes	Definition Project ID of a tenant in a region. To obtain the value, see Obtaining a Project ID. Constraints The value cannot be empty. Range N/A Default Value N/A
instance_id	Yes	Definition Instance ID. Constraints The value cannot be empty. Range N/A Default Value N/A

Request Parameters

**Table 2** Parameters
Parameter	Mandatory	Type	Description
publication_name	Yes	String	Definition Publication name. Constraints N/A Range The publication name must consist of 5 to 64 characters. Only letters, digits, and underscores (_) are allowed. Default Value N/A
publication_database	Yes	String	Definition Publication database name. Constraints The database must exist in the instance. Range N/A Default Value N/A
is_create_snapshot_immediately	Yes	boolean	Definition Whether a snapshot is created immediately. Constraints N/A Range true: A snapshot is created immediately. false: A snapshot is not created immediately. Default Value N/A
subscription_options	No	Object	Definition Subscription options. For details, see Table 3 subscription_options parameters. Constraints N/A
job_schedule	Yes	Object	Definition Schedule details. For details, see Table 4 job_schedule parameters. Constraints N/A
is_select_all_table	No	boolean	Definition Whether all data tables are selected. Constraints N/A Range true: All tables are selected. false: Not all tables are selected. Default Value N/A
extend_tables	No	Array of string	Definition Tables to be removed after all tables are selected. Constraints N/A Range N/A Default Value N/A
tables	Yes	Array of Objects	Definition Published tables. Constraints N/A Range N/A Default Value N/A

**Table 3** subscription_options parameters
Parameter	Mandatory	Type	Description
independent_agent	No	Boolean	Definition Whether an independent distribution agent is used. Constraints N/A Range true: An agent is used. false: No agent is used. Default Value true
snapshot_always_available	No	Boolean	Definition Whether snapshots are always available. Constraints Independent Distribution Agent must be enabled. Range true: Snapshots are always available. false: Snapshots are not always available. Default Value true
replicate_ddl	No	Boolean	Definition Whether schema changes can be replicated. Constraints N/A Range true: Schema changes can be replicated. false: Schema changes cannot be replicated. Default Value true
allow_initialize_from_backup	No	Boolean	Definition Whether backup files can be used for initialization. Constraints N/A Range true: Backup files can be used for initialization. false: Backup files cannot be used for initialization. Default Value false

**Table 4** job_schedule parameters
Parameter	Mandatory	Type	Description
id	Yes	String	Definition Schedule ID. Constraints N/A Range N/A Default Value N/A
job_schedule_type	No	String	Definition Agent schedule type. Constraints N/A Range automatically: The task starts when the SQL Server Agent is started. cpu_idle: The task starts when the CPU is idle. recurring: The task is executed repeatedly. one_time: The task is executed only once. Default Value recurring
one_time_occurrence	No	Object	Definition Execution time when the task is executed only once. For details, see Table 5 one_time_occurrence parameters. Constraints N/A
frequency	No	Object	Definition Interval of the schedule. For details, see Table 6 frequency parameters. Constraints This parameter is mandatory only when the schedule ID is empty.
daily_frequency	No	Object	Definition Daily frequency of the schedule. For details, see Table 7 daily_frequency parameters. Constraints This parameter is mandatory only when the schedule ID is empty.
duration	No	Object	Definition Validity period of the schedule. For details, see Table 8 duration parameters. Constraints This parameter is mandatory only when the schedule ID is empty.

**Table 5** one_time_occurrence parameters
Parameter	Mandatory	Type	Description
active_start_date	No	Boolean	Definition Execution date, in the format of yyyy-MM-dd. Constraints N/A Range 1990-01-01 to 2099-12-31 Default Value N/A
active_start_time	No	Boolean	Definition Execution time, in the format of HH:mm:ss. Constraints N/A Range N/A Default Value N/A

**Table 6** frequency parameters
Parameter	Mandatory	Type	Description
freq_type	No	String	Definition Frequency type of the schedule. Constraints N/A Range daily: by day weekly: by week monthly_day: by month and by day in each month monthly_week: by month and by week in each month Default Value N/A
freq_interval	No	String	Definition Execution interval. Constraints N/A Range 1–99 Default Value N/A
freq_interval_weekly	No	Array of String	Definition Days in a week when the task is executed. Constraints This parameter is mandatory when freq_type is set to weekly. If freq_type is not set to weekly, this parameter does not take effect. Range Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday Default Value N/A
freq_interval_day_monthly	No	Integer	Definition Monthly execution dates. Constraints This parameter is mandatory when freq_type is set to monthly_day. If freq_type is not set to monthly_day, this parameter does not take effect. Range 1 to the total number of days in the month, for example, 1 to 31 Default Value N/A
freq_interval_monthly	No	String	Definition Days in a week when the task is executed in the current month. Constraints This parameter is mandatory when freq_type is set to monthly_week. If freq_type is not set to monthly_week, this parameter does not take effect. Range Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, day, weekday, weekend Default Value N/A
freq_relative_interval_monthly	No	String	Definition Week in a month when the task is executed. Constraints This parameter is mandatory when freq_type is set to monthly_week. If freq_type is not set to monthly_week, this parameter does not take effect. Range first, second, third, fourth, last Default Value N/A

**Table 7** daily_frequency parameters
Parameter	Mandatory	Type	Description
freq_subday_type	No	String	Definition Daily frequency type. Constraints N/A Range once: once a day multiple: multiple times a day Default Value N/A
active_start_time	No	String	Definition Time of the first execution on each day. If freq_subday_type is set to once, the task is executed only once a day. The value is in HH:mm:ss format. Constraints N/A Range N/A Default Value N/A
active_end_time	No	String	Definition Last execution time, in the format of HH:mm:ss. Constraints This parameter is mandatory when the task is executed multiple times a day. It does not take effect when the task is executed only once a day. Range N/A Default Value N/A
freq_subday_interval	No	Integer	Definition Execution interval. Constraints This parameter is mandatory when the task is executed multiple times a day. It does not take effect when the task is executed only once a day. Range 1–99 Default Value N/A
freq_interval_unit	No	String	Definition Execution interval unit. Constraints This parameter is mandatory when the task is executed multiple times a day. It does not take effect when the task is executed only once a day. Range second minute hour Default Value N/A

**Table 8** duration parameters
Parameter	Mandatory	Type	Description
active_start_date	No	String	Definition First execution date, in the format of yyyy-MM-dd. Constraints N/A Range 1990-01-01 to 2099-12-31 Default Value N/A
active_end_date	No	String	Definition Last execution date, in the format of yyyy-MM-dd. If this parameter is not specified, the execution does not end. Constraints N/A Range N/A Default Value N/A

**Table 9** tables parameters
Parameter	Mandatory	Type	Description
table_name	Yes	String	Definition Table name. Constraints N/A Range The table name must consist of 1 to 64 characters. Only letters, digits, and underscores (_) are allowed. Default Value N/A
schema	No	String	Definition Schema name. Constraints N/A Range N/A Default Value dbo
columns	No	Array of String	Definition Published fields. Constraints If this parameter is null or is left empty, all fields are selected. Range The field name must consist of 1 to 64 characters. Only letters, digits, and underscores (_) are allowed. Default Value N/A
primary_key	No	Array of String	Definition Primary key. Constraints N/A Range N/A Default Value N/A
filter_statement	No	String	Definition Filter statement. Constraints The value cannot contain single quotation marks ('). Range N/A Default Value N/A
filter	No	Object	Definition Filter. For details, see Table 10 filter parameters. Constraints This parameter is valid only when the filter statement is empty. If the filter statement and filter are both empty, no filter condition is available.
article_properties	No	Object	Definition Project properties. For details, see Table 11 article_properties parameters. Constraints N/A

**Table 10** filter parameters
Parameter	Mandatory	Type	Description
relation	No	String	Definition Filter relationship. If the value is empty, the current filter is the lowest-level filter. If the value is not empty, there are lower-level filters. Constraints N/A Range If this parameter is not left empty, its value can be AND or OR. Default Value N/A
column	No	String	Definition Filter field. Constraints This parameter is valid only when the filter relationship is empty. If the filter relationship is empty, this parameter is mandatory. Range N/A Default Value N/A
condition	No	String	Definition Filter condition. Constraints This parameter is valid only when the filter relationship is empty. If the filter relationship is empty, this parameter is mandatory. Range =, !=, >, <, >=, <=, LIKE, NOT LIKE, IN Default Value N/A
value	No	String	Definition Filter value. Constraints This parameter is valid only when the filter relationship is empty. If the filter relationship is empty, this parameter is mandatory. Range N/A Default Value N/A
filters	No	Array of Object	Definition Lower-level filter. For details, see Table 10 filter parameters. Constraints This parameter is valid only when the filter relationship is not empty. If the filter relationship is not empty, this parameter is mandatory.

**Table 11** article_properties parameters
Parameter	Mandatory	Type	Description
destination_object_name	No	String	Definition Name of the target object. Constraints N/A Range N/A Default Value N/A
destination_object_owner	No	String	Definition Namespace of the target object. Constraints N/A Range N/A Default Value N/A
insert_delivery_format	No	String	Definition INSERT delivery format. Constraints N/A Range do_not_insert: Do not execute the INSERT statement. insert: Execute the INSERT statement. insert_without_column_list: The fields of the INSERT statement remain in the original order. call_procedure: Execute the stored procedure to pass all values for all columns. Default Value N/A
insert_stored_procedure	No	String	Definition INSERT stored procedure. Constraints This parameter is mandatory when insert_delivery_format is set to call_procedure. Range N/A Default Value N/A
update_delivery_format	No	String	Definition UPDATE delivery format. Constraints N/A Range do_not_update: Do not execute the UPDATE statement. update: Execute the UPDATE statement. call_procedure: Execute the stored procedure to pass all values for all columns. mcall_procedure: Execute the stored procedure to only pass values for affected columns. It also includes a bitmask representing the changed columns. xcall_procedure: Execute the stored procedure to pass all columns (whether affected or not) and the old data values for each column. scall_procedure: Execute the stored procedure to pass values only for the columns that were actually affected by the update. Default Value N/A
update_stored_procedure	No	String	Definition UPDATE stored procedure. Constraints This parameter is mandatory when update_delivery_format is set to call_procedure, mcall_procedure, xcall_procedure, or scall_procedure. Range N/A Default Value N/A
delete_delivery_format	No	String	Definition DELETE delivery format. Constraints N/A Range do_not_delete: Do not execute the DELETE statement. delete: Execute the DELETE statement. call_procedure: Execute the stored procedure to pass all values for all columns. xcall_procedure: Execute the stored procedure to pass all columns (whether affected or not) and the old data values for each column. Default Value N/A
delete_stored_procedure	No	String	Definition DELETE stored procedure. Constraints This parameter is mandatory when delete_delivery_format is set to call_procedure or xcall_procedure. Range N/A Default Value N/A

Example Request

Create a publication for a DB instance.

PUT https://{Endpoint}/v3/0483b6b16e954cb88930a360d2c4e663/instances/72ee4cc4607347049df9ad50f615bbd8in04/replication/publications
{
"job_schedule": {
        "job_schedule_type": "one_time",
        "one_time_occurrence": {
          "active_start_date": "2025-11-26",
          "active_start_time": "05:00:00"
        }
      },
      "tables": [
        {
          "table_name": "tab01",
          "schema": "dbo",
          "columns": [
            "id"
          ],
          "filter_statement": "",
          "primary_key": [
            "id"
          ]
        }
      ],
      "is_select_all_table": false,
      "extend_tables": [],
      "subscription_options": {
        "independent_agent": true,
        "snapshot_always_available": true,
        "replicate_ddl": true,
        "allow_initialize_from_backup": true
      },
      "publication_name": "testccc",
      "publication_database": "tab01"
}

Response

Normal response

**Table 12** Parameters
Parameter	Type	Description
job_id	String	Definition Task flow ID. Range N/A

Example normal response

{
    "job_id":"12323-sdsf-sewewe-wewewewex1tg"
}

Abnormal response
For details, see Abnormal Request Results.

Status Code

Normal
200
Abnormal
For details, see Status Codes.

Error Code

For details, see Error Codes.

Parent topic: Publications and Subscriptions (RDS for SQL Server)

Previous topic: Creating a Distributor

Next topic: Batch Modifying Publications

Feedback

Was this page helpful?

Helpful Not helpful

Provide feedback

Thank you very much for your feedback. We will continue working to improve the documentation.See the reply and handling status in My Cloud VOC.

The system is busy. Please try again later.

Which of the following issues have you encountered?

Content is inconsistent with the product UI

Unclear descriptions

Lack of examples or code

Incorrect steps

Can't find what I need

Lack of best practices

Feedback (optional)

0/500

Select at least one type of issue, and enter your comments or suggestions.

Enter a maximum of 500 characters.

Submit Cancel

For any further questions, feel free to contact us through the chatbot.

Chatbot