Application Load Balancer API, REST: VirtualHost.updateRoute

Written by

Updated at August 30, 2023

HTTP request
Path parameters
Body parameters
Response

Updates the specified route of the specified virtual host.

HTTP request

POST https://alb.api.cloud.yandex.net/apploadbalancer/v1/httpRouters/{httpRouterId}/virtualHosts/{virtualHostName}:updateRoute

Path parameters

Parameter	Description
httpRouterId	Required. ID of the HTTP router to update a route in. To get the HTTP router ID, make a list request.
virtualHostName	Required. Name of the virtual host to update a route in. To get the virtual host name, make a list request.

Parameter

Description

httpRouterId

Required. ID of the HTTP router to update a route in.

To get the HTTP router ID, make a list request.

virtualHostName

Required. Name of the virtual host to update a route in.

To get the virtual host name, make a list request.

Body parameters

{
  "routeName": "string",
  "updateMask": "string",
  "routeOptions": {
    "modifyRequestHeaders": [
      {
        "name": "string",

        // `routeOptions.modifyRequestHeaders[]` includes only one of the fields `append`, `replace`, `remove`, `rename`
        "append": "string",
        "replace": "string",
        "remove": true,
        "rename": "string",
        // end of the list of possible fields`routeOptions.modifyRequestHeaders[]`

      }
    ],
    "modifyResponseHeaders": [
      {
        "name": "string",

        // `routeOptions.modifyResponseHeaders[]` includes only one of the fields `append`, `replace`, `remove`, `rename`
        "append": "string",
        "replace": "string",
        "remove": true,
        "rename": "string",
        // end of the list of possible fields`routeOptions.modifyResponseHeaders[]`

      }
    ],
    "rbac": {
      "action": "string",
      "principals": [
        {
          "andPrincipals": [
            {

              // `routeOptions.rbac.principals[].andPrincipals[]` includes only one of the fields `header`, `remoteIp`, `any`
              "header": {
                "name": "string",
                "value": {

                  // `routeOptions.rbac.principals[].andPrincipals[].header.value` includes only one of the fields `exactMatch`, `prefixMatch`, `regexMatch`
                  "exactMatch": "string",
                  "prefixMatch": "string",
                  "regexMatch": "string",
                  // end of the list of possible fields`routeOptions.rbac.principals[].andPrincipals[].header.value`

                }
              },
              "remoteIp": "string",
              "any": true,
              // end of the list of possible fields`routeOptions.rbac.principals[].andPrincipals[]`

            }
          ]
        }
      ]
    },
    "securityProfileId": "string"
  },

  //  includes only one of the fields `http`, `grpc`
  "http": {
    "match": {
      "httpMethod": [
        "string"
      ],
      "path": {

        // `http.match.path` includes only one of the fields `exactMatch`, `prefixMatch`, `regexMatch`
        "exactMatch": "string",
        "prefixMatch": "string",
        "regexMatch": "string",
        // end of the list of possible fields`http.match.path`

      }
    },

    // `http` includes only one of the fields `route`, `redirect`, `directResponse`
    "route": {
      "backendGroupId": "string",
      "timeout": "string",
      "idleTimeout": "string",
      "prefixRewrite": "string",
      "upgradeTypes": [
        "string"
      ],

      // `http.route` includes only one of the fields `hostRewrite`, `autoHostRewrite`
      "hostRewrite": "string",
      "autoHostRewrite": true,
      // end of the list of possible fields`http.route`

    },
    "redirect": {
      "replaceScheme": "string",
      "replaceHost": "string",
      "replacePort": "string",
      "removeQuery": true,
      "responseCode": "string",

      // `http.redirect` includes only one of the fields `replacePath`, `replacePrefix`
      "replacePath": "string",
      "replacePrefix": "string",
      // end of the list of possible fields`http.redirect`

    },
    "directResponse": {
      "status": "string",
      "body": {
        "text": "string"
      }
    },
    // end of the list of possible fields`http`

  },
  "grpc": {
    "match": {
      "fqmn": {

        // `grpc.match.fqmn` includes only one of the fields `exactMatch`, `prefixMatch`, `regexMatch`
        "exactMatch": "string",
        "prefixMatch": "string",
        "regexMatch": "string",
        // end of the list of possible fields`grpc.match.fqmn`

      }
    },

    // `grpc` includes only one of the fields `route`, `statusResponse`
    "route": {
      "backendGroupId": "string",
      "maxTimeout": "string",
      "idleTimeout": "string",

      // `grpc.route` includes only one of the fields `hostRewrite`, `autoHostRewrite`
      "hostRewrite": "string",
      "autoHostRewrite": true,
      // end of the list of possible fields`grpc.route`

    },
    "statusResponse": {
      "status": "string"
    },
    // end of the list of possible fields`grpc`

  },
  // end of the list of possible fields

}

Field	Description
routeName	string Required. Name of the route to update. To get the route name, make a get request.
updateMask	string Field mask that specifies which attributes of the route should be updated.
routeOptions	object New route options for the route.
routeOptions. modifyRequestHeaders[]	object Apply the following modifications to the request headers.
routeOptions. modifyRequestHeaders[]. name	string Name of the header.
routeOptions. modifyRequestHeaders[]. append	string `routeOptions.modifyRequestHeaders[]` includes only one of the fields `append`, `replace`, `remove`, `rename` Appends the specified string to the header value. Variables defined for Envoy proxy are supported.
routeOptions. modifyRequestHeaders[]. replace	string `routeOptions.modifyRequestHeaders[]` includes only one of the fields `append`, `replace`, `remove`, `rename` Replaces the value of the header with the specified string. Variables defined for Envoy proxy are supported.
routeOptions. modifyRequestHeaders[]. remove	boolean (boolean) `routeOptions.modifyRequestHeaders[]` includes only one of the fields `append`, `replace`, `remove`, `rename` Removes the header.
routeOptions. modifyRequestHeaders[]. rename	string `routeOptions.modifyRequestHeaders[]` includes only one of the fields `append`, `replace`, `remove`, `rename` Replaces the name of the header with the specified string. This operation is only supported for ALB Virtual Hosts.
routeOptions. modifyResponseHeaders[]	object Apply the following modifications to the response headers.
routeOptions. modifyResponseHeaders[]. name	string Name of the header.
routeOptions. modifyResponseHeaders[]. append	string `routeOptions.modifyResponseHeaders[]` includes only one of the fields `append`, `replace`, `remove`, `rename` Appends the specified string to the header value. Variables defined for Envoy proxy are supported.
routeOptions. modifyResponseHeaders[]. replace	string `routeOptions.modifyResponseHeaders[]` includes only one of the fields `append`, `replace`, `remove`, `rename` Replaces the value of the header with the specified string. Variables defined for Envoy proxy are supported.
routeOptions. modifyResponseHeaders[]. remove	boolean (boolean) `routeOptions.modifyResponseHeaders[]` includes only one of the fields `append`, `replace`, `remove`, `rename` Removes the header.
routeOptions. modifyResponseHeaders[]. rename	string `routeOptions.modifyResponseHeaders[]` includes only one of the fields `append`, `replace`, `remove`, `rename` Replaces the name of the header with the specified string. This operation is only supported for ALB Virtual Hosts.
routeOptions. rbac	object Role Based Access Control (RBAC) provides router, virtual host, and route access control for the ALB service. Requests are allowed or denied based on the `action` and whether a matching principal is found. For instance, if the action is ALLOW and a matching principal is found the request should be allowed.
routeOptions. rbac. action	string Required. The action to take if a principal matches. Every action either allows or denies a request. ALLOW: Allows the request if and only if there is a principal that matches the request. DENY: Allows the request if and only if there are no principal that match the request.
routeOptions. rbac. principals[]	object Required. Required. A match occurs when at least one matches the request. The minimum number of elements is 1.
routeOptions. rbac. principals[]. andPrincipals[]	object Required. Required. A match occurs when all principals match the request. The minimum number of elements is 1.
routeOptions. rbac. principals[]. andPrincipals[]. header	object A header (or pseudo-header such as :path or :method) of the incoming HTTP request. `routeOptions.rbac.principals[].andPrincipals[]` includes only one of the fields `header`, `remoteIp`, `any`
routeOptions. rbac. principals[]. andPrincipals[]. header. name	string Required. Specifies the name of the header in the request.
routeOptions. rbac. principals[]. andPrincipals[]. header. value	object Specifies how the header match will be performed to route the request. In the absence of value a request that has specified header name will match, regardless of the header's value. A string matcher resource.
routeOptions. rbac. principals[]. andPrincipals[]. header. value. exactMatch	string `routeOptions.rbac.principals[].andPrincipals[].header.value` includes only one of the fields `exactMatch`, `prefixMatch`, `regexMatch` Exact match string.
routeOptions. rbac. principals[]. andPrincipals[]. header. value. prefixMatch	string `routeOptions.rbac.principals[].andPrincipals[].header.value` includes only one of the fields `exactMatch`, `prefixMatch`, `regexMatch` Prefix match string.
routeOptions. rbac. principals[]. andPrincipals[]. header. value. regexMatch	string `routeOptions.rbac.principals[].andPrincipals[].header.value` includes only one of the fields `exactMatch`, `prefixMatch`, `regexMatch` Regular expression match string.
routeOptions. rbac. principals[]. andPrincipals[]. remoteIp	string `routeOptions.rbac.principals[].andPrincipals[]` includes only one of the fields `header`, `remoteIp`, `any` A CIDR block or IP that describes the request remote/origin address, e.g. `192.0.0.0/24` or`192.0.0.4` .
routeOptions. rbac. principals[]. andPrincipals[]. any	boolean (boolean) `routeOptions.rbac.principals[].andPrincipals[]` includes only one of the fields `header`, `remoteIp`, `any` When any is set, it matches any request.
routeOptions. securityProfileId	string Security profile that will take effect to all requests routed via particular virtual host.
http	object New settings of the HTTP route. includes only one of the fields `http`, `grpc`
http. match	object Condition (predicate) used to select the route.
http. match. httpMethod[]	string HTTP method specified in the request.
http. match. path	object Match settings for the path specified in the request. If not specified, the route matches all paths. A string matcher resource.
http. match. path. exactMatch	string `http.match.path` includes only one of the fields `exactMatch`, `prefixMatch`, `regexMatch` Exact match string.
http. match. path. prefixMatch	string `http.match.path` includes only one of the fields `exactMatch`, `prefixMatch`, `regexMatch` Prefix match string.
http. match. path. regexMatch	string `http.match.path` includes only one of the fields `exactMatch`, `prefixMatch`, `regexMatch` Regular expression match string.
http. route	object Forwards the request to a backend group for processing as configured. `http` includes only one of the fields `route`, `redirect`, `directResponse`
http. route. backendGroupId	string Required. Backend group to forward requests to. Stream (TCP) backend groups are not supported.
http. route. timeout	string Overall timeout for an HTTP connection between a load balancer node an a backend from the backend group: the maximum time the connection is kept alive for, regardless of whether data is transferred over it. If a connection times out, the load balancer responds to the client with a `504 Gateway Timeout` status code. Default value: `60`.
http. route. idleTimeout	string Idle timeout for an HTTP connection between a load balancer node an a backend from the backend group: the maximum time the connection is allowed to be idle, i.e. without any data transferred over it. Specifying meaningful values for both `timeout` and `idle_timeout` is useful for implementing server-push mechanisms such as long polling, server-sent events (`EventSource` interface) etc. If a connection times out, the load balancer responds to the client with a `504 Gateway Timeout` status code. If not specified, no idle timeout is used, and an alive connection may be idle for any duration (see `timeout`).
http. route. prefixRewrite	string Replacement for the path prefix matched by `StringMatch`. For instance, if `prefixMatch` value is `/foo` and `prefix_rewrite` value is `/bar`, a request with `/foobaz` path is forwarded with `/barbaz` path. For `exactMatch`, the whole path is replaced. If not specified, the path is not changed.
http. route. upgradeTypes[]	string Supported values for HTTP `Upgrade` header. E.g. `websocket`.
http. route. hostRewrite	string `http.route` includes only one of the fields `hostRewrite`, `autoHostRewrite` Host replacement.
http. route. autoHostRewrite	boolean (boolean) `http.route` includes only one of the fields `hostRewrite`, `autoHostRewrite` Automatically replaces the host with that of the target.
http. redirect	object Redirects the request as configured. `http` includes only one of the fields `route`, `redirect`, `directResponse`
http. redirect. replaceScheme	string URI scheme replacement. If `http` or `https` scheme is to be replaced and `80` or `443` port is specified in the original URI, the port is also removed. If not specified, the original scheme and port are used.
http. redirect. replaceHost	string URI host replacement. If not specified, the original host is used.
http. redirect. replacePort	string (int64) URI host replacement. If not specified, the original host is used.
http. redirect. removeQuery	boolean (boolean) Removes URI query.
http. redirect. responseCode	string HTTP status code to use in redirect responses. MOVED_PERMANENTLY: `301 Moved Permanently` status code. FOUND: `302 Found` status code. SEE_OTHER: `303 See Other` status code. TEMPORARY_REDIRECT: `307 Temporary Redirect` status code. PERMANENT_REDIRECT: `308 Permanent Redirect` status code.
http. redirect. replacePath	string `http.redirect` includes only one of the fields `replacePath`, `replacePrefix` Replacement for the whole path.
http. redirect. replacePrefix	string `http.redirect` includes only one of the fields `replacePath`, `replacePrefix` Replacement for the path prefix matched by `StringMatch`. For instance, if `prefixMatch` value is `/foo` and `replace_prefix` value is `/bar`, a request with `https://example.com/foobaz` URI is redirected to `https://example.com/barbaz`. For `exactMatch`, the whole path is replaced.
http. directResponse	object Instructs the load balancer to respond directly as configured. `http` includes only one of the fields `route`, `redirect`, `directResponse`
http. directResponse. status	string (int64) HTTP status code to use in responses. Acceptable values are 100 to 599, inclusive.
http. directResponse. body	object Response body. A health check payload resource.
http. directResponse. body. text	string Payload text. The string length in characters must be greater than 0.
grpc	object New settings of the gRPC route. includes only one of the fields `http`, `grpc`
grpc. match	object Condition (predicate) used to select the route.
grpc. match. fqmn	object Match settings for gRPC service method called in the request. A match string must be a fully qualified method name, e.g. `foo.bar.v1.BazService/Get`, or a prefix of such. If not specified, the route matches all methods. A string matcher resource.
grpc. match. fqmn. exactMatch	string `grpc.match.fqmn` includes only one of the fields `exactMatch`, `prefixMatch`, `regexMatch` Exact match string.
grpc. match. fqmn. prefixMatch	string `grpc.match.fqmn` includes only one of the fields `exactMatch`, `prefixMatch`, `regexMatch` Prefix match string.
grpc. match. fqmn. regexMatch	string `grpc.match.fqmn` includes only one of the fields `exactMatch`, `prefixMatch`, `regexMatch` Regular expression match string.
grpc. route	object Forwards the request to a backend group for processing as configured. `grpc` includes only one of the fields `route`, `statusResponse`
grpc. route. backendGroupId	string Required. Backend group to forward requests to.
grpc. route. maxTimeout	string Overall timeout for an underlying HTTP connection between a load balancer node an a backend from the backend group: the maximum time the connection is kept alive for, regardless of whether data is transferred over it. If a client specifies a lower timeout in HTTP `grpc-timeout` header, the `max_timeout` value is ignored. If a connection times out, the load balancer responds to the client with an `UNAVAILABLE` status code. Default value: `60`.
grpc. route. idleTimeout	string Idle timeout for an underlying HTTP connection between a load balancer node an a backend from the backend group: the maximum time the connection is allowed to be idle, i.e. without any data transferred over it. Specifying meaningful values for both `maxTimeout` and `idle_timeout` is useful for implementing server-push mechanisms such as long polling, server-sent events etc. If a connection times out, the load balancer responds to the client with an `UNAVAILABLE` status code. If not specified, no idle timeout is used, and an alive connection may be idle for any duration (see `maxTimeout`).
grpc. route. hostRewrite	string `grpc.route` includes only one of the fields `hostRewrite`, `autoHostRewrite` Host replacement.
grpc. route. autoHostRewrite	boolean (boolean) `grpc.route` includes only one of the fields `hostRewrite`, `autoHostRewrite` Automatically replaces the host with that of the target.
grpc. statusResponse	object Instructs the load balancer to respond directly with a specified status. `grpc` includes only one of the fields `route`, `statusResponse`
grpc. statusResponse. status	string gRPC status code to use in responses. gRPC status code supported for use in responses. OK: `OK` (0) status code. INVALID_ARGUMENT: `INVALID_ARGUMENT` (3) status code. NOT_FOUND: `NOT_FOUND` (5) status code. PERMISSION_DENIED: `PERMISSION_DENIED` (7) status code. UNAUTHENTICATED: `UNAUTHENTICATED` (16) status code. UNIMPLEMENTED: `UNIMPLEMENTED` (12) status code. INTERNAL: `INTERNAL` (13) status code. UNAVAILABLE: `UNAVAILABLE` (14) status code.

Response

HTTP Code: 200 - OK

{
  "id": "string",
  "description": "string",
  "createdAt": "string",
  "createdBy": "string",
  "modifiedAt": "string",
  "done": true,
  "metadata": "object",

  //  includes only one of the fields `error`, `response`
  "error": {
    "code": "integer",
    "message": "string",
    "details": [
      "object"
    ]
  },
  "response": "object",
  // end of the list of possible fields

}

An Operation resource. For more information, see Operation.

Field	Description
id	string ID of the operation.
description	string Description of the operation. 0-256 characters long.
createdAt	string (date-time) Creation timestamp. String in RFC3339 text format. The range of possible values is from `0001-01-01T00:00:00Z` to `9999-12-31T23:59:59.999999999Z`, i.e. from 0 to 9 digits for fractions of a second. To work with values in this field, use the APIs described in the Protocol Buffers reference. In some languages, built-in datetime utilities do not support nanosecond precision (9 digits).
createdBy	string ID of the user or service account who initiated the operation.
modifiedAt	string (date-time) The time when the Operation resource was last modified. String in RFC3339 text format. The range of possible values is from `0001-01-01T00:00:00Z` to `9999-12-31T23:59:59.999999999Z`, i.e. from 0 to 9 digits for fractions of a second. To work with values in this field, use the APIs described in the Protocol Buffers reference. In some languages, built-in datetime utilities do not support nanosecond precision (9 digits).
done	boolean (boolean) If the value is `false`, it means the operation is still in progress. If `true`, the operation is completed, and either `error` or `response` is available.
metadata	object Service-specific metadata associated with the operation. It typically contains the ID of the target resource that the operation is performed on. Any method that returns a long-running operation should document the metadata type, if any.
error	object The error result of the operation in case of failure or cancellation. includes only one of the fields `error`, `response`
error. code	integer (int32) Error code. An enum value of google.rpc.Code.
error. message	string An error message.
error. details[]	object A list of messages that carry the error details.
response	object includes only one of the fields `error`, `response` The normal response of the operation in case of success. If the original method returns no data on success, such as Delete, the response is google.protobuf.Empty. If the original method is the standard Create/Update, the response should be the target resource of the operation. Any method that returns a long-running operation should document the response type, if any.

Application Load Balancer API, REST: VirtualHost.updateRoute

HTTP requestHTTP request

Path parametersPath parameters

Body parametersBody parameters

ResponseResponse

Was the article helpful?

HTTP request

Path parameters

Body parameters

Response