Help Center> API Gateway> API Reference> Dedicated Gateway APIs (V2)> Orchestration Rule Management> Creating an Orchestration Rule

Updated on 2024-06-27 GMT+08:00

Online Debugging

CLI Examples

View PDF

Creating an Orchestration Rule

Function

This API is used to create an orchestration rule.

Calling Method

For details, see Calling APIs.

URI

POST /v2/{project_id}/apigw/instances/{instance_id}/orchestrations

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Project ID. For details about how to obtain it, see Obtaining a Project ID.
instance_id	Yes	String	Gateway ID, which can be obtained from the gateway information on the APIG console.

Request Parameters

**Table 2** Request header parameters
Parameter	Mandatory	Type	Description
X-Auth-Token	Yes	String	User token. It 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 a token.

**Table 3** Request body parameters
Parameter	Mandatory	Type	Description
orchestration_name	Yes	String	Orchestration mapping rule name. The name must be 3 to 64 characters long, start with a letter and use only letters, digits, and underscores (_). It must be unique in the same gateway. Minimum: 3 Maximum: 64
orchestration_strategy	Yes	String	Orchestration policy. Options: list hash range hash_range none_value default head_n tail_n. If the orchestration policy is list, the number of objects in orchestration_map multiplied by that in map_param_list cannot exceed 3,000. Enumeration values: list hash range hash_range none_value default head_n tail_n
orchestration_mapped_param	No	OrchestrationMappedParam object	Parameter configuration after orchestration. This parameter is mandatory when isPreprocessing is set to false.
is_preprocessing	No	Boolean	Indicates whether the policy is a preprocessing policy. A preprocessing policy generates only temporary parameters as the input of the subsequent parameter orchestration rule. And it cannot be used as the last orchestration rule except the default orchestration rule.
orchestration_map	No	Array of OrchestrationMap objects	List of orchestration mapping rules. The list contains 1 to 300 characters. Orchestration mapping rules are prioritized in the same sequence as the the list. Mapping rules must be unique. If orchestration_strategy is list, map_param_list cannot contain same elements. Array Length: 1 - 300

**Table 4** OrchestrationMappedParam
Parameter	Mandatory	Type	Description
mapped_param_name	Yes	String	Name of the request parameter after orchestration. The value can contain 1 to 128 characters, including letters, digits, and hyphens (-). It must start with a letter and cannot be the same as an existing parameter name. By default, the parameter name is transparently transmitted to the backend. Minimum: 1 Maximum: 128
mapped_param_type	Yes	String	Type of the parameter after orchestration. The value can be string or number. Enumeration values: string number
mapped_param_location	Yes	String	Position of the orchestrated parameter. The value can be query or header. Enumeration values: query header

**Table 5** OrchestrationMap
Parameter	Mandatory	Type	Description
map_param_list	No	Array of strings	List of parameters after mapping orchestration. This parameter is mandatory when orchestration_strategy is set to list. The list length ranges from 0 to 3000. The value can contain 1 to 128 characters, including letters, digits, hyphens (-), and underscores (_). Minimum: 1 Maximum: 128 Array Length: 0 - 3000
map_param_range	No	OrchestrationMapParamRange object	This parameter is for mapping range configurations of parameters after orchestration and is mandatory if orchestration_strategy is range or hash_range.
mapped_param_value	No	String	The parameter value after orchestration can contain 1 to 128 characters, including only letters and digits. This parameter is optional only when orchestration_strategy is set to hash, head_n, or tail_n, or is_preprocessing is set to false. Minimum: 0 Maximum: 128
intercept_length	No	Integer	Truncation length. The value ranges from 1 to 100. This parameter is mandatory when the policy type is head_n or tail_n. If the truncation length is greater than the parameter length, the parameter truncation result is a complete parameter. Minimum: 1 Maximum: 100

**Table 6** OrchestrationMapParamRange
Parameter	Mandatory	Type	Description
range_start	No	String	Range start value. The value is a string that can be converted to an integer. After the conversion, the value of range_start ranges from 0 to 9223372036854775807. And the value of range_start cannot be greater than that of range_end.
range_end	No	String	Range end value. The value is a string that can be converted to an integer. After the conversion, the value of range_end ranges from 0 to 9223372036854775807. And the value of range_start cannot be greater than that of range_end.

Response Parameters

Status code: 201

**Table 7** Response body parameters
Parameter	Type	Description
orchestration_name	String	Orchestration mapping rule name. The name must be 3 to 64 characters long, start with a letter and use only letters, digits, and underscores (_). It must be unique in the same gateway. Minimum: 3 Maximum: 64
orchestration_strategy	String	Orchestration policy. Options: list hash range hash_range none_value default head_n tail_n. If the orchestration policy is list, the number of objects in orchestration_map multiplied by that in map_param_list cannot exceed 3,000. Enumeration values: list hash range hash_range none_value default head_n tail_n
orchestration_mapped_param	OrchestrationMappedParam object	Parameter configuration after orchestration. This parameter is mandatory when isPreprocessing is set to false.
is_preprocessing	Boolean	Indicates whether the policy is a preprocessing policy. A preprocessing policy generates only temporary parameters as the input of the subsequent parameter orchestration rule. And it cannot be used as the last orchestration rule except the default orchestration rule.
orchestration_map	Array of OrchestrationMap objects	List of orchestration mapping rules. The list contains 1 to 300 characters. Orchestration mapping rules are prioritized in the same sequence as the the list. Mapping rules must be unique. If orchestration_strategy is list, map_param_list cannot contain same elements. Array Length: 1 - 300
orchestration_id	String	Orchestration rule ID.
orchestration_create_time	String	Time when an orchestration rule was created.
orchestration_update_time	String	Time when an orchestration rule was updated.

**Table 8** OrchestrationMappedParam
Parameter	Type	Description
mapped_param_name	String	Name of the request parameter after orchestration. The value can contain 1 to 128 characters, including letters, digits, and hyphens (-). It must start with a letter and cannot be the same as an existing parameter name. By default, the parameter name is transparently transmitted to the backend. Minimum: 1 Maximum: 128
mapped_param_type	String	Type of the parameter after orchestration. The value can be string or number. Enumeration values: string number
mapped_param_location	String	Position of the orchestrated parameter. The value can be query or header. Enumeration values: query header

**Table 9** OrchestrationMap
Parameter	Type	Description
map_param_list	Array of strings	List of parameters after mapping orchestration. This parameter is mandatory when orchestration_strategy is set to list. The list length ranges from 0 to 3000. The value can contain 1 to 128 characters, including letters, digits, hyphens (-), and underscores (_). Minimum: 1 Maximum: 128 Array Length: 0 - 3000
map_param_range	OrchestrationMapParamRange object	This parameter is for mapping range configurations of parameters after orchestration and is mandatory if orchestration_strategy is range or hash_range.
mapped_param_value	String	The parameter value after orchestration can contain 1 to 128 characters, including only letters and digits. This parameter is optional only when orchestration_strategy is set to hash, head_n, or tail_n, or is_preprocessing is set to false. Minimum: 0 Maximum: 128
intercept_length	Integer	Truncation length. The value ranges from 1 to 100. This parameter is mandatory when the policy type is head_n or tail_n. If the truncation length is greater than the parameter length, the parameter truncation result is a complete parameter. Minimum: 1 Maximum: 100

**Table 10** OrchestrationMapParamRange
Parameter	Type	Description
range_start	String	Range start value. The value is a string that can be converted to an integer. After the conversion, the value of range_start ranges from 0 to 9223372036854775807. And the value of range_start cannot be greater than that of range_end.
range_end	String	Range end value. The value is a string that can be converted to an integer. After the conversion, the value of range_end ranges from 0 to 9223372036854775807. And the value of range_start cannot be greater than that of range_end.

Status code: 400

**Table 11** Response body parameters
Parameter	Type	Description
error_code	String	Error code.
error_msg	String	Error description.

Status code: 401

**Table 12** Response body parameters
Parameter	Type	Description
error_code	String	Error code.
error_msg	String	Error description.

Status code: 403

**Table 13** Response body parameters
Parameter	Type	Description
error_code	String	Error code.
error_msg	String	Error description.

Status code: 404

**Table 14** Response body parameters
Parameter	Type	Description
error_code	String	Error code.
error_msg	String	Error description.

Status code: 500

**Table 15** Response body parameters
Parameter	Type	Description
error_code	String	Error code.
error_msg	String	Error description.

Example Requests

Creating a list orchestration rule

{
  "orchestration_name" : "orchestration_demo_1",
  "orchestration_strategy" : "list",
  "orchestration_mapped_param" : {
    "mapped_param_name" : "shared-tag",
    "mapped_param_type" : "number",
    "mapped_param_location" : "header"
  },
  "orchestration_map" : [ {
    "map_param_list" : [ "10001", "10002" ],
    "mapped_param_value" : "1"
  }, {
    "map_param_list" : [ "10003", "10004" ],
    "mapped_param_value" : "2"
  } ],
  "is_preprocessing" : false
}

Creating a range orchestration rule

{
  "orchestration_name" : "orchestration_demo_2",
  "orchestration_strategy" : "range",
  "orchestration_mapped_param" : {
    "mapped_param_name" : "shared-tag",
    "mapped_param_type" : "number",
    "mapped_param_location" : "header"
  },
  "orchestration_map" : [ {
    "map_param_range" : {
      "range_start" : "1",
      "range_end" : "1000"
    },
    "mapped_param_value" : "1"
  } ]
}

Creating a hash orchestration rule

{
  "orchestration_name" : "orchestration_demo_3",
  "orchestration_strategy" : "hash",
  "orchestration_mapped_param" : {
    "mapped_param_name" : "shared-tag",
    "mapped_param_type" : "number",
    "mapped_param_location" : "header"
  }
}

Creating a hash_range orchestration rule

{
  "orchestration_name" : "orchestration_demo_4",
  "orchestration_strategy" : "hash_range",
  "orchestration_mapped_param" : {
    "mapped_param_name" : "shared-tag",
    "mapped_param_type" : "number",
    "mapped_param_location" : "header"
  },
  "orchestration_map" : [ {
    "map_param_range" : {
      "range_start" : "1",
      "range_end" : "1000"
    },
    "mapped_param_value" : "1"
  } ]
}

Creating a none_value orchestration rule

{
  "orchestration_name" : "orchestration_demo_5",
  "orchestration_strategy" : "none_value",
  "orchestration_mapped_param" : {
    "mapped_param_name" : "shared-tag",
    "mapped_param_type" : "number",
    "mapped_param_location" : "header"
  },
  "orchestration_map" : [ {
    "mapped_param_value" : "1"
  } ]
}

Creating a default orchestration rule

{
  "orchestration_name" : "orchestration_demo_6",
  "orchestration_strategy" : "default",
  "orchestration_mapped_param" : {
    "mapped_param_name" : "shared-tag",
    "mapped_param_type" : "number",
    "mapped_param_location" : "header"
  },
  "orchestration_map" : [ {
    "mapped_param_value" : "1"
  } ]
}

Creating a head_n orchestration rule

{
  "orchestration_name" : "orchestration_demo_7",
  "orchestration_strategy" : "head_n",
  "orchestration_mapped_param" : {
    "mapped_param_name" : "shared-tag",
    "mapped_param_type" : "number",
    "mapped_param_location" : "header"
  },
  "orchestration_map" : [ {
    "intercept_length" : 10,
    "mapped_param_value" : "1"
  } ]
}

Creating a tail_n orchestration rule

{
  "orchestration_name" : "orchestration_demo_8",
  "orchestration_strategy" : "tail_n",
  "orchestration_mapped_param" : {
    "mapped_param_name" : "shared-tag",
    "mapped_param_type" : "number",
    "mapped_param_location" : "header"
  },
  "orchestration_map" : [ {
    "intercept_length" : 10,
    "mapped_param_value" : "1"
  } ]
}

Creating a tail_n preprocessing orchestration rule

{
  "orchestration_name" : "orchestration_demo_8",
  "orchestration_strategy" : "tail_n",
  "orchestration_mapped_param" : {
    "mapped_param_name" : "shared-tag",
    "mapped_param_type" : "number",
    "mapped_param_location" : "header"
  },
  "orchestration_map" : [ {
    "intercept_length" : 10
  } ],
  "is_preprocessing" : true
}

Example Responses

Status code: 201

Created

Example 1

{
  "orchestration_id" : "76545e81d9cb4424bf704ef2b0ac7600",
  "orchestration_name" : "orchestration_demo_1",
  "orchestration_create_time" : "2023-07-02T12:31:23.353Z",
  "orchestration_update_time" : "2023-07-02T13:31:23.353Z",
  "orchestration_strategy" : "list",
  "orchestration_mapped_param" : {
    "mapped_param_name" : "shared-tag",
    "mapped_param_type" : "number",
    "mapped_param_location" : "header"
  },
  "orchestration_map" : [ {
    "map_param_list" : [ "10001", "10002" ],
    "mapped_param_value" : "1"
  }, {
    "map_param_list" : [ "10003", "10004" ],
    "mapped_param_value" : "2"
  } ]
}

Example 2

{
  "orchestration_id" : "yt655e81d9cb4424bf704ef2b0ac7600",
  "orchestration_name" : "orchestration_demo_2",
  "orchestration_create_time" : "2023-07-02T12:31:23.353Z",
  "orchestration_update_time" : "2023-07-02T13:31:23.353Z",
  "orchestration_strategy" : "range",
  "orchestration_mapped_param" : {
    "mapped_param_name" : "shared-tag",
    "mapped_param_type" : "number",
    "mapped_param_location" : "header"
  },
  "orchestration_map" : [ {
    "map_param_range" : {
      "range_start" : "1",
      "range_end" : "1000"
    },
    "mapped_param_value" : "1"
  } ]
}

Example 3

{
  "orchestration_id" : "a7655e81d9cb4424bf704ef2b0ac7600",
  "orchestration_name" : "orchestration_demo_3",
  "orchestration_create_time" : "2023-07-02T12:31:23.353Z",
  "orchestration_update_time" : "2023-07-02T13:31:23.353Z",
  "orchestration_strategy" : "hash",
  "orchestration_mapped_param" : {
    "mapped_param_name" : "shared-tag",
    "mapped_param_type" : "number",
    "mapped_param_location" : "header"
  }
}

Status code: 400

Bad Request

{
  "error_code" : "APIG.2012",
  "error_msg" : "Invalid parameter value,parameterName:instance_id. Please refer to the support documentation"
}

Status code: 401

Unauthorized

{
  "error_code" : "APIG.1002",
  "error_msg" : "Incorrect token or token resolution failed"
}

Status code: 403

Forbidden

{
  "error_code" : "APIG.1005",
  "error_msg" : "No permissions to request this method"
}

Status code: 404

Not Found

{
  "error_code" : "APIG.3030",
  "error_msg" : "The instance does not exist;id:f0fa1789-3b76-433b-a787-9892951c620ec"
}

Status code: 500

Internal Server Error

{
  "error_code" : "APIG.9999",
  "error_msg" : "System error"
}

Status Codes

Status Code	Description
201	Created
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
500	Internal Server Error

Error Codes

See Error Codes.

Parent topic: Orchestration Rule Management

Previous topic: Orchestration Rule Management

Next topic: Viewing Orchestration Rules

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