백엔드 서비스 간에 데이터 전달

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

이 예시에서는 다음과 같은 설정이 적용됩니다.

  1. GCP_REGION은 배포된 백엔드의 리전을 지정합니다. Google Cloud
  2. PROJECT_ID는 Google Cloud 프로젝트 ID를 지정합니다.
  3. 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 경로: /hello/{name}
      • API 클라이언트 요청 리소스 경로: /hello/Dave
      • 백엔드 서비스 요청 URL: https://PROJECT_ID.appspot.com/hello/Dave
  • 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 경로: /hello/{name}
      • API 클라이언트 요청 리소스 경로: /hello/Dave
      • 백엔드 서비스 요청 URL: https://GCP_REGION-PROJECT_ID.cloudfunctions.net/hello?name=Dave

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로 설정됩니다.