백엔드 서비스 간에 데이터 전달
API 클라이언트가 API 게이트웨이에 배포된 API를 요청할 때 클라이언트는 다음 정보 중 일부 또는 전체를 요청의 일부로 전달할 수 있습니다.
- 요청 헤더
- 쿼리 매개변수
- 양식 데이터
- XML 또는 JSON 페이로드
- 요청 경로
API 요청에 대한 응답을 빌드할 때 백엔드 서비스는 다음과 같은 데이터를 API 클라이언트에 반환할 수 있습니다.
- 응답 헤더
- XML 또는 JSON 페이로드
이 문서에서는 이러한 데이터가 백엔드 서비스에 대해 전달되는 방법을 설명합니다.
요청 데이터는 백엔드 서비스로 어떻게 전달되나요?
API 클라이언트의 모든 요청 데이터는 변경되지 않은 상태로 백엔드 서비스로 전달됩니다. 그런 후 요청을 처리하는 동안 백엔드 서비스가 요청 데이터를 파싱합니다.
응답 데이터는 API 클라이언트에 어떻게 반환되나요?
백엔드 서비스의 응답으로 수신되는 모든 데이터는 변경되지 않은 상태로 API 클라이언트에 전달됩니다. 그런 후 API 클라이언트가 응답에 있는 모든 반환된 데이터를 처리합니다.
요청 URL은 백엔드 서비스에 어떻게 전달되나요?
백엔드 서비스에 대한 요청에 사용되는 URL은 x-google-backend
확장 프로그램으로 제어됩니다.
이 섹션에서는 백엔드 서비스 URL 구성 옵션에 대해 설명합니다.
OpenAPI 사양에서 백엔드 서비스 주소 및 경로 설정
API 구성을 만드는 데 사용되는 OpenAPI 사양에서 x-google-backend
확장 프로그램을 사용하여 백엔드 서비스의 URL을 지정합니다.
예를 들어 다음 형식으로 백엔드 서비스를 지정합니다.
백엔드 | x-google-backend |
---|---|
Cloud Run 함수 | x-google-backend: address: https://GCP_REGION-PROJECT_ID.cloudfunctions.net/hello |
Cloud Run | x-google-backend: address: https://hello-HASH.a.run.app |
App Engine 표준 환경 | x-google-backend: address: https://PROJECT_ID.appspot.com |
이 예시에서는 다음을 수행합니다.
- GCP_REGION은 배포된 백엔드의 GCP 리전을 지정합니다.
- PROJECT_ID는 Google Cloud 프로젝트 ID를 지정합니다.
- HASH는 Cloud Run 서비스를 만들 때 생성되는 고유한 해시 코드를 지정합니다.
또한 OpenAPI 사양의 path
매개변수는 엔드포인트 또는 API에서 지원되는 리소스를 지정합니다. 절대 경로 또는 경로 매개변수가 사용된 경로를 지정할 수 있습니다.
경로 | 매개변수가 포함된 경로 |
---|---|
paths: /hello: |
paths: /hello/{name}: |
API 요청에서 백엔드 서비스 URL 생성
API 게이트웨이는 API 클라이언트의 요청을 처리할 때 API 클라이언트에서 전송된 요청 URL을 가져와서 백엔드 서비스에 대해 요청을 수행하기 위해 사용되는 URL로 변환합니다. 이 변환이 수행되는 정확한 방식은 사용하는 경로 변환 전략에 따라 다릅니다.
x-google-backend
확장 프로그램에 대한 path_translation
옵션은 두 가지 경로 변환 전략을 지원합니다.
APPEND_PATH_TO_ADDRESS
: 백엔드 서비스 URL은 클라이언트 요청의 리소스 경로를x-google-backend
확장 프로그램의address
URL에 추가하여 생성됩니다.API 클라이언트에서 지정된 것과 동일한 리소스 경로가 백엔드에 수신되기 때문에 대부분의 백엔드 서비스에는
APPEND_PATH_TO_ADDRESS
가 사용됩니다.CONSTANT_ADDRESS
: 백엔드 서비스 URL은x-google-backend
확장 프로그램의address
URL에 정의된 상수입니다. 클라이언트 요청에 리소스 경로가 포함된 경우 쿼리 매개변수를 사용해서 백엔드 서비스 URL에 리소스 경로가 추가됩니다.이 메서드는 일반적으로 Cloud Run 함수에서 사용됩니다.
예를 들면 다음과 같습니다.
APPEND_PATH_TO_ADDRESS
address
:https://PROJECT_ID.appspot.com
- OpenAPI 경로 매개변수가 없는 경우:
- OpenAPI 경로:
/hello
- API 클라이언트 요청 리소스 경로:
/hello
- 백엔드 서비스 요청 URL:
https://PROJECT_ID.appspot.com/hello
- OpenAPI 경로:
- OpenAPI 경로 매개변수가 있는 경우:
- OpenAPI 경로:
/hello/{name}
- API 클라이언트 요청 리소스 경로:
/hello/Dave
- 백엔드 서비스 요청 URL:
https://PROJECT_ID.appspot.com/hello/Dave
- OpenAPI 경로:
CONSTANT_ADDRESS
address
:https://GCP_REGION-PROJECT_ID.cloudfunctions.net/hello
- OpenAPI 경로 매개변수가 없는 경우
- OpenAPI 경로:
/hello
- API 클라이언트 요청 리소스 경로:
/hello
- 백엔드 서비스 요청 URL:
https://GCP_REGION-PROJECT_ID.cloudfunctions.net/hello
- OpenAPI 경로:
- OpenAPI 경로 매개변수가 있는 경우
- OpenAPI 경로:
/hello/{name}
- API 클라이언트 요청 리소스 경로:
/hello/Dave
- 백엔드 서비스 요청 URL:
https://GCP_REGION-PROJECT_ID.cloudfunctions.net/hello?name=Dave
- OpenAPI 경로:
path_translation
설정
x-google-backend
를 설정하면서 path_translation
을 설정합니다.
x-google-backend: address: https://GCP_REGION-PROJECT_ID.cloudfunctions.net/hello path_translation: [ APPEND_PATH_TO_ADDRESS | CONSTANT_ADDRESS ]`
path_translation
의 기본값은 OpenAPI에서 x-google-backend
를 설정한 위치에 따라 달라집니다.
x-google-backend
가 OpenAPI 사양의 최상위에 사용된 경우 기본적으로path_translation
이APPEND_PATH_TO_ADDRESS
로 설정됩니다.x-google-backend
가 OpenAPI 사양의 연산 수준에 사용된 경우 기본적으로path_translation
이CONSTANT_ADDRESS
로 설정됩니다.