Help Center/ EventGrid/ API Reference/ APIs/ Event Subscription Management/ Creating an Event Subscription

Updated on 2023-05-24 GMT+08:00

View PDF

Creating an Event Subscription

Function

This API is used to create an event subscription.

URI

POST /v1/{project_id}/subscriptions

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Tenant project ID.

Request Parameters

**Table 2** Request header parameters
Parameter	Mandatory	Type	Description
X-Auth-Token	Yes	String	User token. The token can be obtained by calling the IAM API used to obtain a user token. The value of X-Subject-Token in the response header is the user token. Minimum: 1 Maximum: 16384

**Table 3** Request body parameters
Parameter	Mandatory	Type	Description
name	Yes	String	Name of the event subscription. The value must be unique under a tenant. Only letters, digits, periods (.), underscores (_), and hyphens (-) are allowed. It must start with a letter or digit. Minimum: 1 Maximum: 128
description	No	String	Description of the event subscription. Maximum: 255
channel_id	Yes	String	ID of the event channel to which the event subscription belongs.
sources	Yes	Array of SubscriptionSource objects	List of event subscription sources. Currently, only one event source can be subscribed to.
targets	Yes	Array of SubscriptionTarget objects	List of event subscription targets. At least one event target must be subscribed to.

**Table 4** SubscriptionSource
Parameter	Mandatory	Type	Description
id	No	String	ID of the subscription source, which must be globally unique. If the subscription source with the specified ID exists, the subscription source is updated. Otherwise, the subscription source is created. If no ID is specified, the system automatically generates an ID when creating the subscription source. Only lowercase letters, digits, and hyphens (-) are allowed. It must start with a letter or digit. Minimum: 32 Maximum: 64
name	Yes	String	Name of the event subscription source. Maximum: 128
provider_type	Yes	String	Provider type of the event subscription source. Enumeration values: CUSTOM OFFICIAL
detail	No	Object	List of event subscription source parameters. The total length of this field after serialization cannot exceed 1024 bytes.
filter	Yes	Object	Filtering rule of the event subscription source. The total length of this field after serialization cannot exceed 2048 bytes.

**Table 5** SubscriptionTarget
Parameter	Mandatory	Type	Description
id	No	String	Subscription target ID. The value must be globally unique. Only lowercase letters, digits, and hyphens (-) are allowed. It must start with a letter or digit. In the subscription update scenario, if the subscription target with the specified ID exists, the subscription target is updated. Otherwise, the subscription target is created. If no ID is specified, the system automatically generates an ID when creating the subscription target. If an ID is specified, the ID is used as the subscription target ID. This field is ignored when the subscription target is updated. Minimum: 32 Maximum: 64
name	Yes	String	Name of the event subscription target. Maximum: 128
provider_type	Yes	String	Provider type of the event subscription target. Enumeration values: CUSTOM OFFICIAL
connection_id	No	String	Connection ID used by the event subscription target. Maximum: 64
detail	Yes	Object	List of event subscription target parameters. The total length of this field after serialization cannot exceed 1024 bytes.
transform	Yes	TransForm object	Transform rule of the event subscription target.

**Table 6** TransForm
Parameter	Mandatory	Type	Description
type	Yes	String	Type of the transform rule. Enumeration values: ORIGINAL CONSTANT VARIABLE
value	No	String	For a constant type rule, the field is the constant content definition. For a variable type rule, the field is a variable definition and the content must be a JSON object string. A maximum of 100 variables are supported, and nested structures are not supported. The variable name can contain a maximum of 64 characters. Only letters, digits, periods (.), underscores (_), and hyphens (-) are allowed. It must start with a letter or digit and cannot start with HC.. The variable value expression can be a constant or JSONPath expression. The string length cannot exceed 1024 characters. Maximum: 1024
template	No	String	Template definition of the rule content when the rule is of the variable type. Defined variables can be referenced. Maximum: 2048

Response Parameters

Status code: 200

**Table 7** Response header parameters
Parameter	Type	Description
X-Request-Id	String	This field is the request ID number for task tracking. Format is request_uuid-timestamp-hostname.

**Table 8** Response body parameters
Parameter	Type	Description
id	String	Subscription ID.
name	String	Subscription name.
description	String	Description of the subscription.
type	String	Subscription type. Enumeration values: EVENT SCHEDULED
status	String	Status. Enumeration values: CREATED ENABLED DISABLED FROZEN ERROR
channel_id	String	ID of the event channel.
channel_name	String	Name of the event channel.
used	Array of SubscriptionUsedInfo objects	Label information.
sources	Array of SubscriptionSourceInfo objects	List of subscription sources.
targets	Array of SubscriptionTargetInfo objects	List of subscription targets.
created_time	String	Time when the trigger is created.
updated_time	String	Time when the trigger is updated.

**Table 9** SubscriptionUsedInfo
Parameter	Type	Description
resource_id	String	Associated resource ID.
owner	String	Management tenant account.
description	String	Description.

**Table 10** SubscriptionSourceInfo
Parameter	Type	Description
id	String	ID of the event subscription source.
name	String	Name of the event subscription source.
provider_type	String	Provider type of the event subscription source.
detail	Object	List of event subscription source parameters.
filter	Object	Filtering rule of the event subscription source.
created_time	String	Time when the event subscription is created.
updated_time	String	Time when the event subscription is updated.

**Table 11** SubscriptionTargetInfo
Parameter	Type	Description
id	String	ID of the event subscription target.
name	String	Name of the event subscription target.
provider_type	String	Provider type of the event subscription target.
connection_id	String	Connection ID used by the event subscription target. Maximum: 64
detail	Object	List of event subscription target parameters.
transform	TransForm object	Transform rule of the event subscription target.
created_time	String	Time when the event subscription is created.
updated_time	String	Time when the event subscription is updated.

**Table 12** TransForm
Parameter	Type	Description
type	String	Type of the transform rule. Enumeration values: ORIGINAL CONSTANT VARIABLE
value	String	For a constant type rule, the field is the constant content definition. For a variable type rule, the field is a variable definition and the content must be a JSON object string. A maximum of 100 variables are supported, and nested structures are not supported. The variable name can contain a maximum of 64 characters. Only letters, digits, periods (.), underscores (_), and hyphens (-) are allowed. It must start with a letter or digit and cannot start with HC.. The variable value expression can be a constant or JSONPath expression. The string length cannot exceed 1024 characters. Maximum: 1024
template	String	Template definition of the rule content when the rule is of the variable type. Defined variables can be referenced. Maximum: 2048

Status code: 400

**Table 13** Response body parameters
Parameter	Type	Description
error_code	String	Error code. Minimum: 1 Maximum: 128
error_msg	String	Error message. Minimum: 1 Maximum: 512
error_details	String	Error details. Minimum: 1 Maximum: 1024
request_id	String	Request ID. Minimum: 1 Maximum: 128

Status code: 401

**Table 14** Response body parameters
Parameter	Type	Description
error_code	String	Error code. Minimum: 1 Maximum: 128
error_msg	String	Error message. Minimum: 1 Maximum: 512
error_details	String	Error details. Minimum: 1 Maximum: 1024
request_id	String	Request ID. Minimum: 1 Maximum: 128

Status code: 403

**Table 15** Response body parameters
Parameter	Type	Description
error_code	String	Error code. Minimum: 1 Maximum: 128
error_msg	String	Error message. Minimum: 1 Maximum: 512
error_details	String	Error details. Minimum: 1 Maximum: 1024
request_id	String	Request ID. Minimum: 1 Maximum: 128

Status code: 404

**Table 16** Response body parameters
Parameter	Type	Description
error_code	String	Error code. Minimum: 1 Maximum: 128
error_msg	String	Error message. Minimum: 1 Maximum: 512
error_details	String	Error details. Minimum: 1 Maximum: 1024
request_id	String	Request ID. Minimum: 1 Maximum: 128

Status code: 500

**Table 17** Response body parameters
Parameter	Type	Description
error_code	String	Error code. Minimum: 1 Maximum: 128
error_msg	String	Error message. Minimum: 1 Maximum: 512
error_details	String	Error details. Minimum: 1 Maximum: 1024
request_id	String	Request ID. Minimum: 1 Maximum: 128

Example Requests

Create an event subscription with a specified channel.

/v1/{project_id}/subscriptions

{
  "channel_id" : "{{channel-id}}",
  "description" : "",
  "name" : "name",
  "sources" : [ {
    "id" : null,
    "name" : "{{source-name}}",
    "detail" : { },
    "filter" : {
      "source" : [ {
        "op" : "StringIn",
        "values" : [ "{{source-name}}" ]
      } ]
    },
    "provider_type" : "CUSTOM"
  } ],
  "targets" : [ {
    "id" : null,
    "detail" : {
      "url" : "https://aaa.com"
    },
    "name" : "HTTPS",
    "provider_type" : "CUSTOM",
    "transform" : {
      "type" : "ORIGINAL",
      "value" : ""
    }
  } ]
}

Example Responses

Status code: 400

{
  "error_code" : "EG.00014000",
  "error_msg" : "Bad request"
}

Status code: 401

{
  "error_code" : "EG.00014010",
  "error_msg" : "Incorrect token or token resolution failed"
}

Status code: 403

{
  "error_code" : "EG.00014030",
  "error_msg" : "No permissions to request this method"
}

Status code: 404

{
  "error_code" : "EG.00014040",
  "error_msg" : "Not request resource found"
}

Status code: 500

{
  "error_code" : "EG.00015000",
  "error_msg" : "Internal Server Error"
}

Status Codes

Status Code	Description
200	Demo Information
400	Invalid request.
401	Unauthorized.
403	Access denied.
404	Resource not found.
500	Internal service error.

Error Codes

See Error Codes.

Parent topic: Event Subscription Management

Previous topic: Event Subscription Management

Next topic: Obtaining the Event Subscription List

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.

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