Method: urlMaps.patch

Patches the specified UrlMap resource with the data included in the request. This method supports PATCH semantics and uses the JSON merge patch format and processing rules.

HTTP request

PATCH https://compute.googleapis.com/compute/v1/projects/{project}/global/urlMaps/{resourceId}

The URL uses gRPC Transcoding syntax.

Path parameters

Parameters
project

string

Project ID for this request.

resourceId

string

Name of the UrlMap resource to patch.

Query parameters

Parameters
requestId

string

An optional request ID to identify requests. Specify a unique request ID so that if you must retry your request, the server will know to ignore the request if it has already been completed.

For example, consider a situation where you make an initial request and the request times out. If you make the request again with the same request ID, the server can check if original operation with the same request ID was received, and if so, will ignore the second request. This prevents clients from accidentally creating duplicate commitments.

The request ID must be a valid UUID with the exception that zero UUID is not supported (00000000-0000-0000-0000-000000000000).

Request body

The request body contains data with the following structure:

JSON representation
{
  "id": string,
  "creationTimestamp": string,
  "name": string,
  "description": string,
  "selfLink": string,
  "hostRules": [
    {
      "description": string,
      "hosts": [
        string
      ],
      "pathMatcher": string
    }
  ],
  "pathMatchers": [
    {
      "name": string,
      "description": string,
      "defaultService": string,
      "defaultRouteAction": {
        "weightedBackendServices": [
          {
            "backendService": string,
            "weight": integer,
            "headerAction": {
              "requestHeadersToRemove": [
                string
              ],
              "requestHeadersToAdd": [
                {
                  "headerName": string,
                  "headerValue": string,
                  "replace": boolean
                }
              ],
              "responseHeadersToRemove": [
                string
              ],
              "responseHeadersToAdd": [
                {
                  "headerName": string,
                  "headerValue": string,
                  "replace": boolean
                }
              ]
            }
          }
        ],
        "urlRewrite": {
          "pathPrefixRewrite": string,
          "hostRewrite": string
        },
        "timeout": {
          "seconds": string,
          "nanos": integer
        },
        "retryPolicy": {
          "retryConditions": [
            string
          ],
          "numRetries": integer,
          "perTryTimeout": {
            "seconds": string,
            "nanos": integer
          }
        },
        "requestMirrorPolicy": {
          "backendService": string
        },
        "corsPolicy": {
          "allowOrigins": [
            string
          ],
          "allowOriginRegexes": [
            string
          ],
          "allowMethods": [
            string
          ],
          "allowHeaders": [
            string
          ],
          "exposeHeaders": [
            string
          ],
          "maxAge": integer,
          "allowCredentials": boolean,
          "disabled": boolean
        },
        "faultInjectionPolicy": {
          "delay": {
            "fixedDelay": {
              "seconds": string,
              "nanos": integer
            },
            "percentage": number
          },
          "abort": {
            "httpStatus": integer,
            "percentage": number
          }
        },
        "maxStreamDuration": {
          "seconds": string,
          "nanos": integer
        }
      },
      "defaultUrlRedirect": {
        "hostRedirect": string,
        "pathRedirect": string,
        "prefixRedirect": string,
        "redirectResponseCode": enum,
        "httpsRedirect": boolean,
        "stripQuery": boolean
      },
      "pathRules": [
        {
          "service": string,
          "routeAction": {
            "weightedBackendServices": [
              {
                "backendService": string,
                "weight": integer,
                "headerAction": {
                  "requestHeadersToRemove": [
                    string
                  ],
                  "requestHeadersToAdd": [
                    {
                      "headerName": string,
                      "headerValue": string,
                      "replace": boolean
                    }
                  ],
                  "responseHeadersToRemove": [
                    string
                  ],
                  "responseHeadersToAdd": [
                    {
                      "headerName": string,
                      "headerValue": string,
                      "replace": boolean
                    }
                  ]
                }
              }
            ],
            "urlRewrite": {
              "pathPrefixRewrite": string,
              "hostRewrite": string
            },
            "timeout": {
              "seconds": string,
              "nanos": integer
            },
            "retryPolicy": {
              "retryConditions": [
                string
              ],
              "numRetries": integer,
              "perTryTimeout": {
                "seconds": string,
                "nanos": integer
              }
            },
            "requestMirrorPolicy": {
              "backendService": string
            },
            "corsPolicy": {
              "allowOrigins": [
                string
              ],
              "allowOriginRegexes": [
                string
              ],
              "allowMethods": [
                string
              ],
              "allowHeaders": [
                string
              ],
              "exposeHeaders": [
                string
              ],
              "maxAge": integer,
              "allowCredentials": boolean,
              "disabled": boolean
            },
            "faultInjectionPolicy": {
              "delay": {
                "fixedDelay": {
                  "seconds": string,
                  "nanos": integer
                },
                "percentage": number
              },
              "abort": {
                "httpStatus": integer,
                "percentage": number
              }
            },
            "maxStreamDuration": {
              "seconds": string,
              "nanos": integer
            }
          },
          "urlRedirect": {
            "hostRedirect": string,
            "pathRedirect": string,
            "prefixRedirect": string,
            "redirectResponseCode": enum,
            "httpsRedirect": boolean,
            "stripQuery": boolean
          },
          "paths": [
            string
          ]
        }
      ],
      "routeRules": [
        {
          "priority": integer,
          "description": string,
          "matchRules": [
            {
              "prefixMatch": string,
              "fullPathMatch": string,
              "regexMatch": string,
              "ignoreCase": boolean,
              "headerMatches": [
                {
                  "headerName": string,
                  "exactMatch": string,
                  "regexMatch": string,
                  "rangeMatch": {
                    "rangeStart": string,
                    "rangeEnd": string
                  },
                  "presentMatch": boolean,
                  "prefixMatch": string,
                  "suffixMatch": string,
                  "invertMatch": boolean
                }
              ],
              "queryParameterMatches": [
                {
                  "name": string,
                  "presentMatch": boolean,
                  "exactMatch": string,
                  "regexMatch": string
                }
              ],
              "metadataFilters": [
                {
                  "filterMatchCriteria": enum,
                  "filterLabels": [
                    {
                      "name": string,
                      "value": string
                    }
                  ]
                }
              ]
            }
          ],
          "service": string,
          "routeAction": {
            "weightedBackendServices": [
              {
                "backendService": string,
                "weight": integer,
                "headerAction": {
                  "requestHeadersToRemove": [
                    string
                  ],
                  "requestHeadersToAdd": [
                    {
                      "headerName": string,
                      "headerValue": string,
                      "replace": boolean
                    }
                  ],
                  "responseHeadersToRemove": [
                    string
                  ],
                  "responseHeadersToAdd": [
                    {
                      "headerName": string,
                      "headerValue": string,
                      "replace": boolean
                    }
                  ]
                }
              }
            ],
            "urlRewrite": {
              "pathPrefixRewrite": string,
              "hostRewrite": string
            },
            "timeout": {
              "seconds": string,
              "nanos": integer
            },
            "retryPolicy": {
              "retryConditions": [
                string
              ],
              "numRetries": integer,
              "perTryTimeout": {
                "seconds": string,
                "nanos": integer
              }
            },
            "requestMirrorPolicy": {
              "backendService": string
            },
            "corsPolicy": {
              "allowOrigins": [
                string
              ],
              "allowOriginRegexes": [
                string
              ],
              "allowMethods": [
                string
              ],
              "allowHeaders": [
                string
              ],
              "exposeHeaders": [
                string
              ],
              "maxAge": integer,
              "allowCredentials": boolean,
              "disabled": boolean
            },
            "faultInjectionPolicy": {
              "delay": {
                "fixedDelay": {
                  "seconds": string,
                  "nanos": integer
                },
                "percentage": number
              },
              "abort": {
                "httpStatus": integer,
                "percentage": number
              }
            },
            "maxStreamDuration": {
              "seconds": string,
              "nanos": integer
            }
          },
          "urlRedirect": {
            "hostRedirect": string,
            "pathRedirect": string,
            "prefixRedirect": string,
            "redirectResponseCode": enum,
            "httpsRedirect": boolean,
            "stripQuery": boolean
          },
          "headerAction": {
            "requestHeadersToRemove": [
              string
            ],
            "requestHeadersToAdd": [
              {
                "headerName": string,
                "headerValue": string,
                "replace": boolean
              }
            ],
            "responseHeadersToRemove": [
              string
            ],
            "responseHeadersToAdd": [
              {
                "headerName": string,
                "headerValue": string,
                "replace": boolean
              }
            ]
          }
        }
      ],
      "headerAction": {
        "requestHeadersToRemove": [
          string
        ],
        "requestHeadersToAdd": [
          {
            "headerName": string,
            "headerValue": string,
            "replace": boolean
          }
        ],
        "responseHeadersToRemove": [
          string
        ],
        "responseHeadersToAdd": [
          {
            "headerName": string,
            "headerValue": string,
            "replace": boolean
          }
        ]
      }
    }
  ],
  "tests": [
    {
      "description": string,
      "host": string,
      "path": string,
      "headers": [
        {
          "name": string,
          "value": string
        }
      ],
      "service": string,
      "expectedOutputUrl": string,
      "expectedRedirectResponseCode": integer
    }
  ],
  "defaultService": string,
  "defaultRouteAction": {
    "weightedBackendServices": [
      {
        "backendService": string,
        "weight": integer,
        "headerAction": {
          "requestHeadersToRemove": [
            string
          ],
          "requestHeadersToAdd": [
            {
              "headerName": string,
              "headerValue": string,
              "replace": boolean
            }
          ],
          "responseHeadersToRemove": [
            string
          ],
          "responseHeadersToAdd": [
            {
              "headerName": string,
              "headerValue": string,
              "replace": boolean
            }
          ]
        }
      }
    ],
    "urlRewrite": {
      "pathPrefixRewrite": string,
      "hostRewrite": string
    },
    "timeout": {
      "seconds": string,
      "nanos": integer
    },
    "retryPolicy": {
      "retryConditions": [
        string
      ],
      "numRetries": integer,
      "perTryTimeout": {
        "seconds": string,
        "nanos": integer
      }
    },
    "requestMirrorPolicy": {
      "backendService": string
    },
    "corsPolicy": {
      "allowOrigins": [
        string
      ],
      "allowOriginRegexes": [
        string
      ],
      "allowMethods": [
        string
      ],
      "allowHeaders": [
        string
      ],
      "exposeHeaders": [
        string
      ],
      "maxAge": integer,
      "allowCredentials": boolean,
      "disabled": boolean
    },
    "faultInjectionPolicy": {
      "delay": {
        "fixedDelay": {
          "seconds": string,
          "nanos": integer
        },
        "percentage": number
      },
      "abort": {
        "httpStatus": integer,
        "percentage": number
      }
    },
    "maxStreamDuration": {
      "seconds": string,
      "nanos": integer
    }
  },
  "defaultUrlRedirect": {
    "hostRedirect": string,
    "pathRedirect": string,
    "prefixRedirect": string,
    "redirectResponseCode": enum,
    "httpsRedirect": boolean,
    "stripQuery": boolean
  },
  "headerAction": {
    "requestHeadersToRemove": [
      string
    ],
    "requestHeadersToAdd": [
      {
        "headerName": string,
        "headerValue": string,
        "replace": boolean
      }
    ],
    "responseHeadersToRemove": [
      string
    ],
    "responseHeadersToAdd": [
      {
        "headerName": string,
        "headerValue": string,
        "replace": boolean
      }
    ]
  },
  "fingerprint": string,
  "region": string,
  "kind": string
}
Fields
id

string (fixed64 format)

[Output Only] The unique identifier for the resource. This identifier is defined by the server.

creationTimestamp

string

[Output Only] Creation timestamp in RFC3339 text format.

name

string

Name of the resource. Provided by the client when the resource is created. The name must be 1-63 characters long, and comply with RFC1035. Specifically, the name must be 1-63 characters long and match the regular expression [a-z]([-a-z0-9]*[a-z0-9])? which means the first character must be a lowercase letter, and all following characters must be a dash, lowercase letter, or digit, except the last character, which cannot be a dash.

description

string

An optional description of this resource. Provide this property when you create the resource.

hostRules[]

object

The list of HostRules to use against the URL.

hostRules[].description

string

An optional description of this resource. Provide this property when you create the resource.

hostRules[].hosts[]

string

The list of host patterns to match. They must be valid hostnames with optional port numbers in the format host:port. * matches any string of ([a-z0-9-.]*). In that case, * must be the first character and must be followed in the pattern by either - or ..

* based matching is not supported when the URL map is bound to target gRPC proxy that has validateForProxyless field set to true.

hostRules[].pathMatcher

string

The name of the PathMatcher to use to match the path portion of the URL if the hostRule matches the URL's host portion.

pathMatchers[]

object

The list of named PathMatchers to use against the URL.

pathMatchers[].name

string

The name to which this PathMatcher is referred by the HostRule.

pathMatchers[].description

string

An optional description of this resource. Provide this property when you create the resource.

pathMatchers[].defaultService

string

The full or partial URL to the BackendService resource. This will be used if none of the pathRules or routeRules defined by this PathMatcher are matched. For example, the following are all valid URLs to a BackendService resource:

If defaultRouteAction is additionally specified, advanced routing actions like URL Rewrites, etc. take effect prior to sending the request to the backend. However, if defaultService is specified, defaultRouteAction cannot contain any weightedBackendServices. Conversely, if defaultRouteAction specifies any weightedBackendServices, defaultService must not be specified.

Only one of defaultService, defaultUrlRedirect or defaultRouteAction.weightedBackendService must be set.

Authorization requires one or more of the following Google IAM permissions on the specified resource defaultService:

  • compute.backendBuckets.use
  • compute.backendServices.use

Authorization requires one or more of the following IAM permissions on the specified resource defaultService:

  • compute.backendBuckets.use
  • compute.backendServices.use
pathMatchers[].defaultRouteAction

object

defaultRouteAction takes effect when none of the pathRules or routeRules match. The load balancer performs advanced routing actions like URL rewrites, header transformations, etc. prior to forwarding the request to the selected backend. If defaultRouteAction specifies any weightedBackendServices, defaultService must not be set. Conversely if defaultService is set, defaultRouteAction cannot contain any weightedBackendServices.

Only one of defaultRouteAction or defaultUrlRedirect must be set.

UrlMaps for external HTTP(S) load balancers support only the urlRewrite action within a pathMatcher's defaultRouteAction.

pathMatchers[].defaultRouteAction.weightedBackendServices[]

object

A list of weighted backend services to send traffic to when a route match occurs. The weights determine the fraction of traffic that flows to their corresponding backend service. If all traffic needs to go to a single backend service, there must be one weightedBackendService with weight set to a non-zero number.

Once a backendService is identified and before forwarding the request to the backend service, advanced routing actions such as URL rewrites and header transformations are applied depending on additional settings specified in this HttpRouteAction.

pathMatchers[].defaultRouteAction.weightedBackendServices[].backendService

string

The full or partial URL to the default BackendService resource. Before forwarding the request to backendService, the loadbalancer applies any relevant headerActions specified as part of this backendServiceWeight.

Authorization requires the following IAM permission on the specified resource backendService:

  • compute.backendServices.use
pathMatchers[].defaultRouteAction.weightedBackendServices[].weight

integer (uint32 format)

Specifies the fraction of traffic sent to backendService, computed as weight / (sum of all weightedBackendService weights in routeAction) .

The selection of a backend service is determined only for new traffic. Once a user's request has been directed to a backendService, subsequent requests will be sent to the same backendService as determined by the BackendService's session affinity policy.

The value must be between 0 and 1000

pathMatchers[].defaultRouteAction.weightedBackendServices[].headerAction

object

Specifies changes to request and response headers that need to take effect for the selected backendService.

headerAction specified here take effect before headerAction in the enclosing HttpRouteRule, PathMatcher and UrlMap.

Note that headerAction is not supported for Loadbalancers that have their loadBalancingScheme set to EXTERNAL.

Not supported when the URL map is bound to target gRPC proxy that has validateForProxyless field set to true.

pathMatchers[].defaultRouteAction.weightedBackendServices[].headerAction.requestHeadersToRemove[]

string

A list of header names for headers that need to be removed from the request prior to forwarding the request to the backendService.

pathMatchers[].defaultRouteAction.weightedBackendServices[].headerAction.requestHeadersToAdd[]

object

Headers to add to a matching request prior to forwarding the request to the backendService.

pathMatchers[].defaultRouteAction.weightedBackendServices[].headerAction.requestHeadersToAdd[].headerName

string

The name of the header.

pathMatchers[].defaultRouteAction.weightedBackendServices[].headerAction.requestHeadersToAdd[].headerValue

string

The value of the header to add.

pathMatchers[].defaultRouteAction.weightedBackendServices[].headerAction.requestHeadersToAdd[].replace

boolean

If false, headerValue is appended to any values that already exist for the header. If true, headerValue is set for the header, discarding any values that were set for that header.

The default value is false.

pathMatchers[].defaultRouteAction.weightedBackendServices[].headerAction.responseHeadersToRemove[]

string

A list of header names for headers that need to be removed from the response prior to sending the response back to the client.

pathMatchers[].defaultRouteAction.weightedBackendServices[].headerAction.responseHeadersToAdd[]

object

Headers to add the response prior to sending the response back to the client.

pathMatchers[].defaultRouteAction.weightedBackendServices[].headerAction.responseHeadersToAdd[].headerName

string

The name of the header.

pathMatchers[].defaultRouteAction.weightedBackendServices[].headerAction.responseHeadersToAdd[].headerValue

string

The value of the header to add.

pathMatchers[].defaultRouteAction.weightedBackendServices[].headerAction.responseHeadersToAdd[].replace

boolean

If false, headerValue is appended to any values that already exist for the header. If true, headerValue is set for the header, discarding any values that were set for that header.

The default value is false.

pathMatchers[].defaultRouteAction.urlRewrite

object

The spec to modify the URL of the request, prior to forwarding the request to the matched service.

urlRewrite is the only action supported in UrlMaps for external HTTP(S) load balancers.

Not supported when the URL map is bound to target gRPC proxy that has validateForProxyless field set to true.

pathMatchers[].defaultRouteAction.urlRewrite.pathPrefixRewrite

string

Prior to forwarding the request to the selected backend service, the matching portion of the request's path is replaced by pathPrefixRewrite.

The value must be between 1 and 1024 characters.

pathMatchers[].defaultRouteAction.urlRewrite.hostRewrite

string

Prior to forwarding the request to the selected service, the request's host header is replaced with contents of hostRewrite.

The value must be between 1 and 255 characters.

pathMatchers[].defaultRouteAction.timeout

object

Specifies the timeout for the selected route. Timeout is computed from the time the request has been fully processed (i.e. end-of-stream) up until the response has been completely processed. Timeout includes all retries.

If not specified, will use the largest timeout among all backend services associated with the route.

Not supported when the URL map is bound to target gRPC proxy that has validateForProxyless field set to true.

pathMatchers[].defaultRouteAction.timeout.seconds

string (int64 format)

Span of time at a resolution of a second. Must be from 0 to 315,576,000,000 inclusive. Note: these bounds are computed from: 60 sec/min * 60 min/hr * 24 hr/day * 365.25 days/year * 10000 years

pathMatchers[].defaultRouteAction.timeout.nanos

integer

Span of time that's a fraction of a second at nanosecond resolution. Durations less than one second are represented with a 0 seconds field and a positive nanos field. Must be from 0 to 999,999,999 inclusive.

pathMatchers[].defaultRouteAction.retryPolicy

object

Specifies the retry policy associated with this route.

Not supported when the URL map is bound to target gRPC proxy that has validateForProxyless field set to true.

pathMatchers[].defaultRouteAction.retryPolicy.retryConditions[]

string

Specifies one or more conditions when this retry rule applies. Valid values are:

  • 5xx: Loadbalancer will attempt a retry if the backend service responds with any 5xx response code, or if the backend service does not respond at all, example: disconnects, reset, read timeout, connection failure, and refused streams.
  • gateway-error: Similar to 5xx, but only applies to response codes 502, 503 or 504.
  • connect-failure: Loadbalancer will retry on failures connecting to backend services, for example due to connection timeouts.
  • retriable-4xx: Loadbalancer will retry for retriable 4xx response codes. Currently the only retriable error supported is 409.
  • refused-stream:Loadbalancer will retry if the backend service resets the stream with a REFUSED_STREAM error code. This reset type indicates that it is safe to retry.
  • cancelledLoadbalancer will retry if the gRPC status code in the response header is set to cancelled
  • deadline-exceeded: Loadbalancer will retry if the gRPC status code in the response header is set to deadline-exceeded
  • resource-exhausted: Loadbalancer will retry if the gRPC status code in the response header is set to resource-exhausted
  • unavailable: Loadbalancer will retry if the gRPC status code in the response header is set to unavailable

pathMatchers[].defaultRouteAction.retryPolicy.numRetries

integer (uint32 format)

Specifies the allowed number retries. This number must be > 0. If not specified, defaults to 1.

pathMatchers[].defaultRouteAction.retryPolicy.perTryTimeout

object

Specifies a non-zero timeout per retry attempt.

If not specified, will use the timeout set in HttpRouteAction. If timeout in HttpRouteAction is not set, will use the largest timeout among all backend services associated with the route.

pathMatchers[].defaultRouteAction.retryPolicy.perTryTimeout.seconds

string (int64 format)

Span of time at a resolution of a second. Must be from 0 to 315,576,000,000 inclusive. Note: these bounds are computed from: 60 sec/min * 60 min/hr * 24 hr/day * 365.25 days/year * 10000 years

pathMatchers[].defaultRouteAction.retryPolicy.perTryTimeout.nanos

integer

Span of time that's a fraction of a second at nanosecond resolution. Durations less than one second are represented with a 0 seconds field and a positive nanos field. Must be from 0 to 999,999,999 inclusive.

pathMatchers[].defaultRouteAction.requestMirrorPolicy

object

Specifies the policy on how requests intended for the route's backends are shadowed to a separate mirrored backend service. Loadbalancer does not wait for responses from the shadow service. Prior to sending traffic to the shadow service, the host / authority header is suffixed with -shadow.

Not supported when the URL map is bound to target gRPC proxy that has validateForProxyless field set to true.

pathMatchers[].defaultRouteAction.requestMirrorPolicy.backendService

string

The full or partial URL to the BackendService resource being mirrored to.

Authorization requires the following IAM permission on the specified resource backendService:

  • compute.backendServices.use
pathMatchers[].defaultRouteAction.corsPolicy

object

The specification for allowin