[[["容易理解","easyToUnderstand","thumb-up"],["確實解決了我的問題","solvedMyProblem","thumb-up"],["其他","otherUp","thumb-up"]],[["難以理解","hardToUnderstand","thumb-down"],["資訊或程式碼範例有誤","incorrectInformationOrSampleCode","thumb-down"],["缺少我需要的資訊/範例","missingTheInformationSamplesINeed","thumb-down"],["翻譯問題","translationIssue","thumb-down"],["其他","otherDown","thumb-down"]],["上次更新時間：2025-09-03 (世界標準時間)。"],[[["\u003cp\u003eAPI Gateway uses path templating to route incoming requests, with three main components: exact match, single wildcard match, and double wildcard match.\u003c/p\u003e\n"],["\u003cp\u003eExact match path templates only accept requests that precisely match the defined path, with URL-encoded forward slashes not being treated as actual forward slashes.\u003c/p\u003e\n"],["\u003cp\u003eSingle wildcard matches accept requests with at least one character in the specified variable, no additional forward slashes within the variable, and an optional trailing slash.\u003c/p\u003e\n"],["\u003cp\u003eDouble wildcard matches accept requests with zero or more characters, including forward slashes, but the variable must be the last segment of the path and URL-encoded characters are handled appropriately.\u003c/p\u003e\n"],["\u003cp\u003eAPI Gateway does not normalize URL-encoded forward slashes (\u003ccode\u003e%2F\u003c/code\u003e) or multiple adjacent forward slashes, potentially leading to unexpected routing or security vulnerabilities if the backend handles them differently.\u003c/p\u003e\n"]]],[],null,["# Understanding Path Templating\n=============================\n\nWithin API Gateway, it is possible to route incoming requests based on [path templating](https://cloud.google.com/endpoints/docs/grpc-service-config/reference/rpc/google.api#path-template-syntax).\nPath templating has three main components:\n\n- Exact match\n- Single wildcard match\n- Double wildcard match\n\nThe following sections describe each of these components and how they work within the context of API Gateway.\n\nExact Match\n-----------\n\nA templated path *without* any single or double wildcard segments (`*` or `**`) is converted to an exact path match.\nFor example, the OpenAPI spec for your gateway API config may contain a section like the following: \n\n ...\n paths:\n /shelves:\n get:\n summary: List shelves\n ...\n\nIn this example, the gateway will *only* accept requests to `/shelves` and no other paths.\n| **Note:** URL-encoded forward slashes (`%2F`) will not be treated as actual forward slashes, meaning `%2Fshelves` will *not* match the above OpenAPI operation.\n\nSingle Wildcard Matching\n------------------------\n\nIf a templated path contains a variable, a singular wildcard segment (e.g `{var}` or `{var=*}`), or both, the gateway will allow incoming requests that comply with the following:\n\n- The requests do not contain an additional forward slash (`/`), meaning the variable will only match a single path segment.\n- The requests contain at least one character.\n- The requests may contain an additional trailing slash if present at the end of the path.\n\n| **Note:** For variable expansion, all characters except `[-_.~/0-9a-zA-Z]` are percent-encoded.\n\nFor example, the OpenAPI spec for your gateway API config may contain a section like the following: \n\n ...\n paths:\n /shelves/{shelf}/books/{book}: # Equivalent to /shelves/{shelf=*}/books/{book=*}\n get:\n summary: Retrieve a book\n ...\n\nIn this example, the gateway will accept requests that match the following regex: \n\n ^/shelves/[^/]+/books/[^/]+/?$\n\nDouble Wildcard Matching\n------------------------\n\nIf a templated path contains a variable denoted by a double wildcard segment (e.g `{var=**}`),\nthe gateway will allow incoming requests that comply with the following:\n\n- The requests can contain *all* characters, including forward slashes (/).\n- The requests can contain 0 or more characters.\n- The requests may contain an additional trailing slash if present at the end of the path.\n\n| **Note:** Double wildcard variables can only be used in the *last* segment of the provided path. This means that `/shelves/{shelf=**}/books/{book=**}` is not allowed, because `{shelf=**}` is not declared in the last segment of the path. For variable expansion, all characters except `[-_.~/0-9a-zA-Z]` are percent-encoded.\n\nFor example, the OpenAPI spec for your gateway API config may contain a section like the following: \n\n ...\n paths:\n /shelves/{shelf=*}/books/{book=**}:\n get:\n summary: Retrieve a book\n ...\n\nIn this example, the gateway will accept requests that match the following regex: \n\n ^/shelves/[^/]+/books/.*/?$\n\nURL Encoded Forward Slashes\n---------------------------\n\nAPI Gateway follows [RFC 3986](https://tools.ietf.org/html/rfc3986), which does not treat URL encoded forward slashes (`%2F`) as actual slashes when matching URL paths for routing or security decisions. If URL encoded slashes are expected, your backend should handle these requests accordingly.\n| **Warning:** If your backend expects URL encoded forward slashes (%2F) to be treated as actual slashes when matching API Gateway path templates, then requests containing URL encoded forward slashes may match unexpected operations and result in over-privileged access to backend resources.\n\nFor example, consider the following OpenAPI spec: \n\n securityDefinitions:\n api_key:\n type: \"apiKey\"\n name: \"key\"\n in: \"query\"\n paths:\n /shelves/{shelf}:\n get:\n parameters:\n - in: path\n name: shelf\n type: string\n required: true\n description: Shelf ID.\n summary: List shelves\n operationId: GetShelf\n responses:\n '200':\n description: A successful response\n schema:\n type: string\n /shelves/{shelf}/books/{book}:\n get:\n parameters:\n - in: path\n name: shelf\n type: string\n required: true\n description: Shelf ID.\n - in: path\n name: book\n type: string\n required: true\n description: Book ID\n summary: Retrieve a book\n operationId: GetBook\n responses:\n '200':\n description: A successful response\n schema:\n type: string\n security:\n - api_key: []\n\nIn this example, the `/shelves/{shelf}/books/{book}` operation requires an API key, but the `/shelves/{shelf}` operation is unrestricted.\n\nIn the event that a user sends a request to `/shelves/shelf_1%2Fbooks%2Fbook_2`:\n\n- The gateway will process the request as a `GetShelf` operation for the shelf ID `shelf_1%2Fbooks%2Fbook_2`. In this case, an API key check is **not enforced**.\n- If the `%2F` is normalized before any request handling by the backend, the request may instead be processed as the `GetBook` operation for the book ID `book_2`. In other words, the backend processes `/shelves/shelf_1%2Fbooks%2Fbook_2` as `/shelves/shelf_1/books/book_2`.\n\nIn this example, the backend expects the `GetBook` operation to perform an API key check at the gateway. However, because the gateway read the request as a `GetShelf` operation, **no API key check was performed**.\n\nNormalization of Multiple Adjacent Forward Slashes\n--------------------------------------------------\n\nAPI Gateway follows [RFC 3986](https://tools.ietf.org/html/rfc3986), which states that paths with multiple adjacent forward slashes will be treated as a different path than those with singular forward slashes.\nFor instance, a request containing `/shelves///` will **not be normalized by the gateway** to the request path `/shelves/` prior to matching a URI path template *nor* upon forwarding to the specified backend.\n| **Warning:** If your backend normalizes URL paths by merging multiple forward slashes to a single slash, then requests containing multiple adjacent forward slashes may match unexpected gateway operations and may result in over-privileged access to your backend resources."]]
