Create or Update alias API supports must_exist parameter (#6245)

* Create or Update alias API supports must_exist parameter

Signed-off-by: gaobinlong <[email protected]>

* Update _im-plugin/index-alias.md

Co-authored-by: Melissa Vagi <[email protected]>
Signed-off-by: gaobinlong <[email protected]>

* Update _im-plugin/index-alias.md

Co-authored-by: Melissa Vagi <[email protected]>
Signed-off-by: gaobinlong <[email protected]>

* Update index-alias.md

Add copy tags

* Update _im-plugin/index-alias.md

Co-authored-by: Nathan Bower <[email protected]>
Signed-off-by: Melissa Vagi <[email protected]>

* Update _im-plugin/index-alias.md

Co-authored-by: Nathan Bower <[email protected]>
Signed-off-by: Melissa Vagi <[email protected]>

* Update _im-plugin/index-alias.md

Co-authored-by: Nathan Bower <[email protected]>
Signed-off-by: Melissa Vagi <[email protected]>

* Update _im-plugin/index-alias.md

Co-authored-by: Nathan Bower <[email protected]>
Signed-off-by: Melissa Vagi <[email protected]>

* Update _im-plugin/index-alias.md

Co-authored-by: Nathan Bower <[email protected]>
Signed-off-by: Melissa Vagi <[email protected]>

---------

Signed-off-by: gaobinlong <[email protected]>
Signed-off-by: Melissa Vagi <[email protected]>
Co-authored-by: Melissa Vagi <[email protected]>
Co-authored-by: Nathan Bower <[email protected]>

_im-plugin/index-alias.md

@@ -16,22 +16,14 @@ For example, if you’re storing logs into indexes based on the month and you fr
 
 Because you can change the indexes an alias points to at any time, referring to indexes using aliases in your applications allows you to reindex your data without any downtime.
 
----
-
-#### Table of contents
-1. TOC
-{:toc}
-
-
----
-
 ## Create aliases
 
 To create an alias, use a POST request:
 
 ```json
 POST _aliases
 ```
+{% include copy-curl.html %}
 
 Use the `actions` method to specify the list of actions that you want to perform. This command creates an alias named `alias1` and adds `index-1` to this alias:
 
@@ -48,16 +40,18 @@ POST _aliases
   ]
 }
 ```
+{% include copy-curl.html %}
 
-You should see the following response:
+The following response is returned:
 
 ```json
 {
    "acknowledged": true
 }
 ```
+{% include copy-curl.html %}
 
-If this request fails, make sure the index that you're adding to the alias already exists.
+If the request fails, make sure the index that you're adding to the alias already exists.
 
 You can also create an alias using one of the following requests:
 
@@ -67,6 +61,7 @@ POST <index>/_aliases/<alias name>
 PUT <index>/_alias/<alias name>
 POST <index>/_alias/<alias name>
 ```
+{% include copy-curl.html %}
 
 The `<index>` in the above requests can be an index name, a comma-separated list of index names, or a wildcard expression. Use `_all` to refer to all indexes.
 
@@ -76,17 +71,18 @@ To check if `alias1` refers to `index-1`, run one of the following commands:
 GET /_alias/alias1
 GET /index-1/_alias/alias1
 ```
+{% include copy-curl.html %}
 
-To get the mappings and settings information of the indexes that the alias references, run the following command:
+To get the indexes' mappings and settings information referenced by the alias, run the following command:
 
 ```json
 GET alias1
 ```
+{% include copy-curl.html %}
 
 ## Add or remove indexes
 
-You can perform multiple actions in the same `_aliases` operation.
-For example, the following command removes `index-1` and adds `index-2` to `alias1`:
+You can perform multiple actions using the same `_aliases` operation. For example, the following command removes `index-1` and adds `index-2` to `alias1`:
 
 ```json
 POST _aliases
@@ -107,10 +103,9 @@ POST _aliases
   ]
 }
 ```
+{% include copy-curl.html %}
 
-The `add` and `remove` actions occur atomically, which means that at no point will `alias1` point to both `index-1` and `index-2`.
-
-You can also add indexes based on an index pattern:
+The `add` and `remove` actions occur atomically, which means that at no point will `alias1` point to both `index-1` and `index-2`. You can also add indexes based on an index pattern, as shown in the following POST request:
 
 ```json
 POST _aliases
@@ -125,6 +120,27 @@ POST _aliases
   ]
 }
 ```
+{% include copy-curl.html %}
+
+The `remove` action also supports the `must_exist` parameter. If the parameter is set to `true` and the specified alias does not exist, an exception is thrown. If the parameter is set to `false`, then no action is taken if the specified alias does not exist. The default value for `must_exist` is `null`. An exception will be thrown only if none of the specified aliases exist. 
+
+The following POST request uses the `remove` action with the `must_exist` parameter set to `true`:
+
+```json
+POST _aliases
+{
+  "actions": [
+    {
+      "remove": {
+        "index": "index-1",
+        "alias": "alias1",
+        "must_exist": true
+      }
+    }
+  ]
+}
+```
+{% include copy-curl.html %}
 
 ## Manage aliases
 
@@ -133,19 +149,22 @@ To list the mapping of aliases to indexes, run the following command:
 ```json
 GET _cat/aliases?v
 ```
+{% include copy-curl.html %}
 
 #### Example response
 
 ```json
 alias     index   filter    routing.index   routing.search
 alias1    index-1   *             -                 -
 ```
+{% include copy-curl.html %}
 
 To check which indexes an alias points to, run the following command:
 
 ```json
 GET _alias/alias1
 ```
+{% include copy-curl.html %}
 
 #### Example response
 
@@ -158,18 +177,21 @@ GET _alias/alias1
   }
 }
 ```
+{% include copy-curl.html %}
 
 Conversely, to find which alias points to a specific index, run the following command:
 
 ```json
 GET /index-2/_alias/*
 ```
+{% include copy-curl.html %}
 
 To get all index names and their aliases, run the following command:
 
 ```json
 GET /_alias
 ```
+{% include copy-curl.html %}
 
 To check if an alias exists, run one of the following commands:
 
@@ -178,10 +200,11 @@ HEAD /alias1/_alias/
 HEAD /_alias/alias1/
 HEAD index-1/_alias/alias1/
 ```
+{% include copy-curl.html %}
 
 ## Add aliases at index creation
 
-You can add an index to an alias as you create the index:
+You can add an index to an alias as you create the index, as shown in the following PUT request:
 
 ```json
 PUT index-1
@@ -191,12 +214,11 @@ PUT index-1
   }
 }
 ```
+{% include copy-curl.html %}
 
 ## Create filtered aliases
 
-You can create a filtered alias to access a subset of documents or fields from the underlying indexes.
-
-This command adds only a specific timestamp field to `alias1`:
+You can create a filtered alias to access a subset of documents or fields in the underlying indexes. This command adds only a specific timestamp field to `alias1`. The following shows an example POST request:
 
 ```json
 POST _aliases
@@ -216,6 +238,7 @@ POST _aliases
   ]
 }
 ```
+{% include copy-curl.html %}
 
 ## Index alias options
 
@@ -229,7 +252,6 @@ Option | Valid values | Description | Required
 `routing` | String | Limit search to an associated shard value. You can specify `search_routing` and `index_routing` independently. | No
 `is_write_index` | String | Specify the index that accepts any write operations to the alias. If this value is not specified, then no write operations are allowed. | No
 
-
 ## Delete aliases
 
 To delete one or more aliases from an index, use the following request:
@@ -238,6 +260,7 @@ To delete one or more aliases from an index, use the following request:
 DELETE <index>/_alias/<alias>
 DELETE <index>/_aliases/<alias>
 ```
+{% include copy-curl.html %}
 
 Both `<index>` and `<alias>` in the above request support comma-separated lists and wildcard expressions. Use `_all` in place of `<alias>` to delete all aliases for the indexes listed in `<index>`.
 
@@ -246,5 +269,6 @@ For example, if `alias1` refers to `index-1` and `index-2`, you can run the foll
 ```json
 DELETE index-1/_alias/alias1
 ```
+{% include copy-curl.html %}
 
-After you run the request above, `alias1` no longer refers to `index-1`, but still refers to `index-2`.
+After running the request, `alias1` no longer refers to `index-1` but still refers to `index-2`.