API 프록시 구성 참조

<ph type="x-smartling-placeholder"></ph> 현재 Apigee Edge 문서를 보고 있습니다.
Apigee X 문서.
정보

Apigee Edge 작업을 하는 개발자의 기본 개발 활동은 다음과 같습니다. API 또는 백엔드 서비스의 프록시로 작동하는 API 프록시를 구성합니다. 이 문서는 API 프록시를 빌드할 때 사용할 수 있는 모든 구성 요소에 대한 참고 자료입니다.

API 프록시를 빌드하는 방법을 알아보려면 간단한 API 프록시 빌드 주제로 시작하는 것을 추천합니다.

프록시 구성을 수정하는 가장 일반적인 방법은 다음과 같습니다.

프록시 구성 로컬 개발

프록시 구성을 다운로드하여 로컬 컴퓨터에서 수정할 수 있습니다. 날짜 완료되면 결과를 Edge에 업로드합니다. 이 방식을 사용하면 소스 제어, 버전 관리, 기타 공유 워크플로에 적용할 수 있습니다. 또한 프록시 구성을 로컬에서 작업하는 경우, 자체 XML 편집기 및 유효성 검사를 사용할 수 있습니다. 있습니다.

이 섹션에서는 UI를 사용하여 기존 프록시 구성을 다운로드하고 수정하는 방법을 설명합니다. 에지에 다시 업로드하여 배포할 수 있습니다 또한 apigeetool을 사용하여 새 프록시 구성을 다운로드하고 배포할 수 있습니다(각각 fetchproxydeployproxy 명령어 사용).

UI를 사용하여 로컬로 프록시 구성을 수정하려면 다음 절차를 따르세요.

  1. Edge UI에서 현재 프록시 구성을 다운로드합니다. (API 프록시에서 보기에서 프로젝트 > 버전 다운로드를 참조하세요.)
  2. 로컬 머신에서 새 디렉터리를 만들고 이 디렉터리에 다운로드한 ZIP 파일의 압축을 풉니다.

    ZIP 파일의 압축을 풀려면 다음 예시와 같이 unzip 등의 유틸리티를 사용할 수 있습니다.

    mkdir myappdir
    unzip ./my-app_app_rev3_2019_04_20.zip -d myappdir

    ZIP 파일의 압축을 푼 콘텐츠는 API 프록시 구조에 설명된 구조와 유사합니다.

  3. 필요에 따라 소스 파일을 수정합니다. 프록시 구성의 소스 파일에 대한 설명은 API 프록시의 구성 파일 및 디렉터리 구조를 참고하세요.

    예를 들어 건강 모니터링 사용하려면 /apiproxy/targets/ 디렉터리에 있습니다. 이 디렉터리의 기본 파일은 default.xml, 조건부 타겟입니다.

    이 경우 TargetEndpoint 구성 파일 및 디렉터리가 없으면 새로 만드세요.

  4. 프록시 구성 파일의 수정을 마친 후에는 변경사항을 저장해야 합니다.
  5. ZIP 파일의 압축을 풀 때 새로 만든 디렉터리로 변경합니다(압축이 풀린 구성 파일의 루트).

    예를 들어 파일의 압축을 /myappdir 디렉터리에 푼 경우 다음 예시와 같이 해당 디렉터리로 변경합니다.

    cd myappdir

    /myappdir 디렉터리는 ZIP 파일에 포함하지 않는 것이 좋으므로 프록시 구성 파일을 다시 보관처리하기 전에 이 디렉터리로 변경해야 합니다. ZIP 파일의 최상위 디렉터리는 /apiproxy이어야 합니다.

  6. 새 파일이나 변경된 파일을 포함하여 프록시 구성 파일을 다시 보관처리합니다. 다음 예시와 같이 zip과 같은 유틸리티를 사용할 수 있습니다.
    zip my-new-proxy.zip -r .

    ZIP 파일의 최상위 디렉터리는 /apiproxy이어야 합니다.

    ZIP 파일 이름에는 특별한 요구사항이 없습니다. 예를 들어 버전 번호를 늘리거나 파일 이름에 날짜를 지정할 필요는 없지만 이 작업을 수행하면 디버깅 또는 소스 제어에 유용할 수 있습니다.

    업로드할 때 Edge에서 새 프록시 구성의 버전 번호를 증분합니다. 있습니다.

  7. Edge UI를 사용하여 새 프록시 구성을 업로드합니다. (API 프록시 보기에서 프로젝트 > 새 버전을 업로드하세요.

    Bundle is invalid. Empty bundle. 같은 오류가 발생하면 ZIP 파일의 최상위 디렉터리가 /apiproxy인지 확인합니다. 그렇지 않은 경우 확장 디렉터리의 루트에서 프록시 구성 파일을 다시 보관처리합니다.

    새 프록시 구성을 업로드하면 Edge에서 버전 번호를 올리고 버전 요약 뷰에 표시됩니다.

    UI를 사용하여 새 버전을 업로드한 후에는 Edge에서 새 버전을 배포하지 않습니다.

  8. 새 버전을 배포합니다.

자세한 내용은 튜토리얼: UI 및 관리 API를 사용하여 프록시를 다운로드하는 방법 Apigee 커뮤니티.

API 프록시 구조

API 프록시는 다음 구성으로 이루어집니다.

기본 구성 API 프록시의 기본 구성 설정입니다. 기본 구성을 참고하세요.
프록시 엔드포인트 구성 앱 요청에서 Apigee Edge로의 인바운드 HTTP 연결 설정입니다. 및 응답 흐름, 정책 첨부 파일이 포함됩니다 ProxyEndpoint를 참고하세요.
TargetEndpoint 구성 Apigee Edge에서 백엔드 서비스로의 아웃바운드 HTTP 연결 설정입니다. 요청 및 응답 흐름, 정책 첨부 파일을 모니터링할 수 있습니다 TargetEndpoint를 참고하세요.
흐름 ProxyEndpoint 및 TargetEndpoint 요청과 응답 파이프라인을 정책에 연결할 수 있습니다. 흐름을 참조하세요.
정책 Apigee Edge 정책 스키마를 준수하는 XML 형식의 구성 파일입니다. 정책을 참조하세요.
리소스 커스텀 로직을 실행하기 위해 정책에서 참고하는 스크립트, JAR 파일 및 XSLT 파일입니다. 리소스를 참고하세요.

API 프록시 디렉터리 구조 및 콘텐츠

위 표의 구성요소는 다음과 같은 디렉터리 구조의 구성 파일에서 정의됩니다.

apiproxy가 루트인 디렉터리 구조를 보여줍니다. apiproxy 디렉터리 바로 아래에 정책, 프록시, 리소스, 대상 디렉터리와 weatherapi.xml 파일이 있습니다.

API 프록시의 구성 파일 및 디렉터리 구조

이 섹션에서는 API 프록시의 구성 파일 및 디렉터리 구조를 설명합니다.

기본 구성

/apiproxy/weatherapi.xml

API 프록시의 기본 구성으로, API 프록시의 이름을 정의합니다. 이름은 조직 내에서 고유해야 합니다.

샘플 구성:

<APIProxy name="weatherapi">
</APIProxy>

기본 구성 요소

이름 설명 기본값 필수 여부
APIProxy
name API 프록시의 이름으로, 조직 내에서 고유해야 합니다. 이름에 사용할 수 있는 문자는 A-Za-z0-9_-로 제한됩니다. 해당 사항 없음
revision API 프록시 구성의 버전 번호입니다. 따라서 포드를 명시적으로 설정할 필요가 버전 번호입니다. Apigee Edge는 API의 현재 버전을 자동으로 추적하기 때문입니다. 사용할 수 있습니다 해당 사항 없음 아니요
ConfigurationVersion 이 API 프록시가 준수하는 API 프록시 구성 스키마의 버전입니다. 현재 majorVersion 4 및 minorVersion 0만 지원됩니다. 이 설정은 향후에 API 프록시 형식에 만드는 데 사용될 수 있습니다. 4.0 아니요
Description API 프록시의 텍스트 설명입니다. 설명을 입력하면 Edge 관리 UI에 설명이 표시됩니다. 해당 없음 아니요
DisplayName 사용자 친화적인 이름으로, API 프록시 구성의 name 속성과 다를 수 있습니다. 해당 사항 없음 아니요
Policies API 프록시의 /policies 디렉터리에 있는 정책 목록입니다. 사용자는 다음 작업을 수행합니다. 일반적으로 Edge 관리 UI를 사용하여 API 프록시가 생성된 경우에만 이 요소가 표시됩니다. 이 설정은 그야말로 API 매니페스트의 콘텐츠를 볼 수 있도록 설계된 '매니페스트' 설정입니다. 해당 없음 아니요
ProxyEndpoints API 프록시의 /proxies 디렉터리에 있는 ProxyEndpoints 목록입니다. 나 일반적으로 Edge API를 사용하여 API 프록시가 생성된 경우에만 이 요소가 표시됩니다. 관리 UI를 제공합니다. 이 설정은 그야말로 API 프록시의 콘텐츠를 볼 수 있도록 설계된 '매니페스트' 설정입니다. 해당 없음 아니요
Resources 이 API 프록시의 /resources 디렉터리에 있는 리소스(자바스크립트, Python, 자바, XSLT) 목록입니다. 이 요소는 일반적으로 API 프록시가 만들 수 있습니다 이 설정은 그야말로 API 프록시의 콘텐츠를 볼 수 있도록 설계된 '매니페스트' 설정입니다. 해당 없음 아니요
Spec API 프록시와 연결된 OpenAPI 사양을 식별합니다. 값은 사양 저장소의 경로 또는 URL로 설정됩니다.

참고: 사양 저장소는 새 Edge 환경에서 사용할 수 있습니다. 전용입니다. 사양 저장소에 대한 자세한 내용은 관리 및 공유를 참조하세요. 사양을 참조하세요.
해당 사항 없음 아니요
TargetServers 이 API 프록시의 모든 TargetEndpoint에서 참조되는 TargetServer의 목록입니다. 사용자는 다음 작업을 수행합니다. 일반적으로 Edge 관리 UI를 사용하여 API 프록시가 생성된 경우에만 이 요소가 표시됩니다. 이 설정은 그야말로 API 매니페스트의 콘텐츠를 볼 수 있도록 설계된 '매니페스트' 설정입니다. 해당 없음 아니요
TargetEndpoints 이 API 프록시의 /targets 디렉터리에 있는 TargetEndpoint 목록입니다. 나 일반적으로 Edge API를 사용하여 API 프록시가 생성된 경우에만 이 요소가 표시됩니다. 관리 UI를 제공합니다. 이 설정은 그야말로 API 프록시의 콘텐츠를 볼 수 있도록 설계된 '매니페스트' 설정입니다. 해당 없음 아니요

ProxyEndpoint

다음 이미지에서는 요청/응답 흐름을 보여줍니다.

클라이언트가 HTTP 서비스를 호출합니다. 요청은 프록시 엔드포인트를 지나 대상 엔드포인트로 전송된 후에 HTTP 서비스에 의해 처리됩니다. 응답은 대상 엔드포인트를 통과한 다음, 프록시 엔드포인트를 통과한 후 클라이언트에 반환됩니다.

/apiproxy/proxies/default.xml

ProxyEndpoint 구성은 API 프록시의 인바운드(클라이언트 연결) 인터페이스를 정의합니다. ProxyEndpoint를 구성할 때 네트워크 구성을 설정하여 클라이언트 애플리케이션('앱')이 프록시된 API를 호출하는 방법을 정의합니다.

다음의 ProxyEndpoint 구성 샘플은 /apiproxy/proxies에 저장됩니다.

<ProxyEndpoint name="default">
  <PreFlow/>
  <Flows/>
  <PostFlow/>
  <HTTPProxyConnection>
    <BasePath>/weather</BasePath>
    <VirtualHost>default</VirtualHost>
  </HTTPProxyConnection>
  <FaultRules/>
  <DefaultFaultRule/>
  <RouteRule name="default">
    <TargetEndpoint>default</TargetEndpoint>
  </RouteRule>
</ProxyEndpoint>

기본 ProxyEndpoint의 필수 구성 요소는 다음과 같습니다.

ProxyEndpoint 구성 Elements

이름 설명 기본값 필수 여부
ProxyEndpoint
name ProxyEndpoint 이름입니다. 드물지만 ProxyEndpoints가 여러 개 정의된 경우 API 프록시 구성 내에서 고유해야 합니다. 이름에 사용할 수 있는 문자는 A-Za-z0-9._\-$ %로 제한됩니다. 해당 사항 없음
PreFlow 요청 또는 응답의 PreFlow 흐름에서 정책을 정의합니다. 해당 사항 없음
Flows
요청 또는 응답의 조건부 흐름에 정책을 정의합니다.
해당 사항 없음
PostFlow
요청 또는 응답의 PostFlow 흐름에서 정책을 정의합니다.
해당 사항 없음
HTTPProxyConnection API 프록시와 연결된 네트워크 주소 및 URI 경로를 정의합니다.
BasePath

Apigee Edge에서 라우팅하는 데 사용하는 URI 경로를 고유하게 식별하는 필수 문자열입니다. 수신 메시지를 적절한 API 프록시로 보냅니다.

BasePath는 API 프록시의 기본 URL(예: http://apifactory-test.apigee.net)에 추가되는 URI 조각(예: /weather)입니다. BasePath는 환경 내에서 고유해야 합니다. 고유성은 API 프록시를 생성하거나 가져올 때 검증됩니다.

기본 경로에 와일드 카드 사용

API 프록시 기본 경로에서 하나 이상의 '*' 와일드 카드를 사용할 수 있습니다. 예를 들어 /team/*/members를 기본 경로로 사용하면 클라이언트가 새로운 팀을 지원하기 위해 새로운 API 프록시를 만들 필요 없이 https://[host]/team/blue/membershttps://[host]/team/green/members를 호출할 수 있습니다. /**/는 지원되지 않습니다.

중요: Apigee는 와일드 카드 '*'로 시작하는 기본 경로를 지원하지 않습니다. 예를 들어 /*/search는 지원되지 않습니다. '*'로 기본 경로 시작 예기치 않은 오류가 발생할 수 있으며 유효한 경로를 식별합니다.

/
VirtualHost

API 프록시를 환경의 특정 기본 URL과 연결합니다. VirtualHost는 환경의 URL을 하나 이상 정의하는 이름이 지정된 구성입니다.

ProxyEndpoint에 정의된 VirtualHost는 API 프록시가 노출되는 도메인 및 포트를 결정하고 더 나아가 앱에서 API를 호출하기 위해 사용하는 URL을 확인합니다.

기본적으로 환경 하나에 명명된 VirtualHosts 두 개(defaultsecure)가 정의됩니다. 조직은 커스텀 도메인도 정의할 수 있습니다. 예를 들어 HTTPS를 통해서만 API 프록시를 사용할 수 있게 하려면 HTTPProxyConnection의 VirtualHost를 secure로 설정합니다.

기본값 아니요
Properties 선택적 HTTP 구성 설정 집합을 <ProxyEndpoint>의 속성으로 정의할 수 있습니다. 해당 사항 없음 아니요
FaultRules
ProxyEndpoint가 오류에 반응하는 방식을 정의합니다. 오류 규칙은 두 가지 항목을 지정합니다.
  • 사전 정의된 카테고리, 하위 카테고리 또는 오류 이름을 기준으로 처리할 오류를 지정하는 조건
  • 해당 조건에 대한 오류 규칙의 동작을 정의하는 하나 이상의 정책

오류 처리를 참고하세요.

해당 사항 없음 아니요
DefaultFaultRule

다른 오류 규칙에서 명시적으로 처리되지 않는 오류(시스템, 전송, 메시지 또는 정책)를 처리합니다.

오류 처리를 참고하세요.

해당 사항 없음 아니요
RouteRule ProxyEndpoint 요청 파이프라인에서 처리한 후에 인바운드 요청 메시지의 대상을 정의합니다. 일반적으로 RouteRule은 명명된 TargetEndpoint 구성을 가리키지만 URL을 직접 가리킬 수도 있습니다.
Name RouteRule 이름을 제공하는 필수 속성입니다. 이름에 사용할 수 있는 문자는 A-Za-z0-9._\-$ %로 제한됩니다. 예를 들어 Cat2 %_는 법적 이름입니다. 해당 사항 없음
Condition 런타임 시 동적 라우팅에 사용되는 선택적 조건문입니다. 예를 들어 조건부 RouteRule은 백엔드 버전 관리를 지원하도록 콘텐츠 기반 라우팅을 사용 설정하는 데 유용합니다. 해당 사항 없음 아니요
TargetEndpoint

명명된 TargetEndpoint 구성을 식별하는 선택적 문자열입니다. 명명된 TargetEndpoint는 /targets 디렉터리의 동일한 API 프록시에 정의된 TargetEndpoint입니다.

TargetEndpoint의 이름을 지정하면 ProxyEndpoint 요청 파이프라인에서 처리한 후 요청 메시지를 전달할 위치를 지정합니다. 이 설정은 선택사항입니다.

ProxyEndpoint는 URL을 직접 호출할 수 있습니다. 예를 들어 HTTP 클라이언트 역할에서 작동하는 자바스크립트 또는 자바 리소스는 요청을 백엔드 서비스로 전달하는 TargetEndpoint의 기본 작업을 수행할 수 있습니다.

해당 사항 없음 아니요
URL ProxyEndpoint에서 호출한 아웃바운드 네트워크 주소를 정의하는 선택적 문자열이며, /targets에 저장할 수 있는 TargetEndpoint 구성을 우회합니다. 해당 사항 없음 아니요

RouteRule 구성 방법

명명된 TargetEndpoint는 /apiproxy/targets 아래 구성 파일을 나타내며, RouteRule은 ProxyEndpoint에서 요청을 처리한 후 구성 파일로 전달합니다.

예를 들어 다음 RouteRule은 /apiproxy/targets/myTarget.xml 구성을 나타냅니다.

<RouteRule name="default">
  <TargetEndpoint>myTarget</TargetEndpoint>
</RouteRule>

직접 URL 호출

ProxyEndpoint는 백엔드 서비스를 직접 호출할 수도 있습니다. 직접 URL 호출은 /apiproxy/targets에 있는 명명된 TargetEndpoints 구성을 우회합니다. 따라서 TargetEndpoint는 선택적 API 프록시 구성이지만 실제로는 ProxyEndpoint의 직접 호출은 권장되지 않습니다.

예를 들어 다음 RouteRule은 http://api.mycompany.com/v2에 대한 HTTP 호출을 수행합니다.

<RouteRule name="default">
  <URL>http://api.mycompany.com/v2</URL> 
</RouteRule>

조건부 경로

RouteRule을 체인으로 연결하여 런타임 시 동적 라우팅을 지원할 수 있습니다. HTTP 헤더, 메시지 콘텐츠, 쿼리 매개변수 또는 시간, 로케일 등의 문맥 정보를 기반으로 명명된 TargetEndpoint 구성, URL 또는 두 개의 조합에 인바운드 요청을 라우팅할 수 있습니다.

조건부 RouteRules는 Apigee Edge의 다른 조건문처럼 작동합니다. 조건 참조변수 참조를 확인하세요.

예를 들어 다음 RouteRule 조합은 먼저 인바운드 요청을 평가하여 HTTP 헤더 값을 확인합니다. HTTP 헤더 routeTo의 값이 TargetEndpoint1인 경우 요청은 TargetEndpoint1이라는 이름의 TargetEndpoint로 전달됩니다. 그렇지 않으면 요청이 http://api.mycompany.com/v2로 전달됩니다.

<RouteRule name="MyRoute">
  <Condition>request.header.routeTo = "TargetEndpoint1"</Condition>
  <TargetEndpoint>TargetEndpoint1</TargetEndpoint>
</RouteRule>
<RouteRule name="default">
  <URL>http://api.mycompany.com/v2</URL>
</RouteRule>
<ph type="x-smartling-placeholder">

null 경로

요청 메시지를 TargetEndpoint로 전달할 필요가 없는 시나리오를 지원하려면 null RouteRule을 정의할 수 있습니다. 이 기능은 ProxyEndpoint가 자바스크립트를 사용하여 외부 서비스를 호출하거나 API 서비스의 키/값 저장소 조회로 데이터를 검색하는 등 필요한 모든 처리를 수행할 때 유용합니다.

예를 들어 다음은 null 경로를 정의합니다.

<RouteRule name="GoNowhere"/>

조건부 null 경로가 유용할 수 있습니다. 다음 예시에서 HTTP 헤더 request.header.X-DoNothingnull 외의 값이 있는 경우 null 경로를 구성하여 실행합니다.

<RouteRule name="DoNothingOnDemand">
  <Condition>request.header.X-DoNothing != null</Condition>
</RouteRule>

RouteRule은 연결할 수 있으므로 조건부 null 경로는 일반적으로 조건부 라우팅을 지원하도록 설계된 RouteRule 집합의 한 가지 구성요소가 됩니다.

조건부 null 경로를 실무에서 사용할 경우 캐싱이 지원됩니다. 캐시 정책으로 설정한 변수 값을 사용하면 캐시에서 항목을 제공할 때 null 경로를 실행하도록 API 프록시를 구성할 수 있습니다.

<RouteRule name="DoNothingUnlessTheCacheIsStale">
  <Condition>lookupcache.LookupCache-1.cachehit is true</Condition>
</RouteRule>

TargetEndpoint

클라이언트가 HTTP 서비스를 호출합니다. 요청은 프록시 엔드포인트를 지나 대상 엔드포인트로 전송된 후에 HTTP 서비스에 의해 처리됩니다. 응답은 대상 엔드포인트를 통과한 다음, 프록시 엔드포인트를 통과한 후 클라이언트에 반환됩니다.

TargetEndpoint는 ProxyEndpoint의 아웃바운드 버전입니다. TargetEndpoint는 백엔드 서비스 또는 API에 대한 클라이언트 역할을 하며 요청을 전송하고 응답을 수신합니다.

API 프록시에는 TargetEndpoint가 필요하지 않습니다. ProxyEndpoint는 URL을 직접 호출하도록 구성할 수 있습니다. TargetEndpoint가 없는 API 프록시에는 일반적으로 백엔드 서비스를 직접 호출하거나 자바 또는 자바스크립트를 사용하여 서비스를 호출하도록 구성된 ProxyEndpoint가 포함되어 있습니다.

TargetEndpoint 구성

/targets/default.xml

TargetEndpoint는 Apigee Edge에서 다른 서비스로의 아웃바운드 연결을 정의합니다. 리소스도 제공합니다

다음은 TargetEndpoint 구성 샘플입니다.

<TargetEndpoint name="default">
  <PreFlow/>
  <Flows/>
  <PostFlow/>
  <HTTPTargetConnection>
    <URL>http://mocktarget.apigee.net</URL>
    <SSLInfo/>
  </HTTPTargetConnection>
  <FaultRules/>
  <DefaultFaultRule/>
  <ScriptTarget/>
  <LocalTargetConnection/>
</TargetEndpoint>

TargetEndpoint 구성 Elements

TargetEndpoint는 다음 방법 중 한 가지로 대상을 호출할 수 있습니다.

  • HTTP(S) 호출을 위한 HTTPTargetConnection
  • 프록시와 프록시 간의 로컬 연결을 위한 LocalTargetConnection
  • 에지 호스팅 호출을 위한 ScriptTarget Node.js 스크립트

이 중 하나만 TargetEndpoint에서 구성합니다.

이름 설명 기본값 필수 여부
TargetEndpoint
name API 프록시 구성 내에서 고유해야 하는 TargetEndpoint 이름입니다. TargetEndPoint 이름은 ProxyEndpoint RouteRule에서 아웃바운드 처리 요청을 전달하는 데 사용됩니다. 이름에 사용할 수 있는 문자는 A-Za-z0-9._\-$ %로 제한됩니다. 해당 사항 없음
PreFlow 요청 또는 응답의 PreFlow 흐름에서 정책을 정의합니다. 해당 사항 없음
Flows
요청 또는 응답의 조건부 흐름에 정책을 정의합니다.
해당 사항 없음
PostFlow
요청 또는 응답의 PostFlow 흐름에서 정책을 정의합니다.
해당 사항 없음
HTTPTargetConnection

하위 요소를 사용하여 HTTP를 통한 백엔드 리소스 도달범위를 지정합니다.

HTTPTargetConnection을 사용하는 경우 다른 유형의 대상 연결(ScriptTarget 또는 LocalTargetConnection)을 구성하지 마세요.

URL TargetEndpoint가 요청 메시지를 전달할 백엔드 서비스의 네트워크 주소를 정의합니다. 해당 사항 없음 아니요
LoadBalancer

명명된 TargetServer 구성을 한 개 이상 정의합니다. 명명된 TargetServer 구성을 엔드포인트 구성 연결을 2개 이상 정의하는 부하 분산에 사용할 수 있습니다.

또한 TargetServer를 사용하여 API 프록시 구성을 구체적 백엔드 서비스 엔드포인트 URL에서 분리할 수 있습니다.

Load(로드)를 백엔드 서버 간 분산

해당 사항 없음 아니요
Properties 선택적 HTTP 구성 설정 집합을 <TargetEndpoint>의 속성으로 정의할 수 있습니다. 해당 사항 없음 아니요
SSLInfo 선택 사항으로 TargetEndpoint에 TLS/SSL 설정을 정의하여 API 프록시와 대상 서비스 간의 TLS/SSL 연결을 제어합니다. TLS/SSL TargetEndpoint 구성을 참고하세요. 해당 없음 아니요
LocalTargetConnection 하위 요소를 사용하여 부하 분산 및 메시지 프로세서와 같은 네트워크 특성을 우회하여 로컬로 연결되는 리소스를 지정합니다.

대상 리소스를 지정하려면 APIProxy 하위 요소(ProxyEndpoint 요소 포함) 또는 경로 하위 요소를 포함합니다.

자세한 내용은 API 프록시 함께 연결하기를 참고하세요.

LocalTargetConnection을 사용하는 경우 다른 유형의 대상 연결(HTTPTargetConnection 또는 ScriptTarget)을 구성하지 마세요.

APIProxy 요청의 대상으로 사용할 API 프록시의 이름을 지정합니다. 대상 프록시는 요청을 보내는 프록시와 동일한 조직 및 환경에 있어야 합니다. 이는 경로 요소 대신 사용할 수 있습니다. 해당 사항 없음 아니요
ProxyEndpoint APIProxy에서 대상 프록시의 ProxyEndpoint 이름을 지정하는 데 사용됩니다. 해당 사항 없음 아니요
Path 요청의 대상으로 사용할 API 프록시의 엔드포인트 경로를 지정합니다. 대상 프록시는 요청을 보내는 프록시와 동일한 조직 및 환경에 있어야 합니다. 이는 APIProxy 대신 사용할 수 있습니다. 해당 사항 없음 아니요
FaultRules
TargetEndpoint가 오류에 반응하는 방식을 정의합니다. 오류 규칙은 두 가지 항목을 지정합니다.
  • 사전 정의된 카테고리, 하위 카테고리 또는 오류 이름을 기준으로 처리할 오류를 지정하는 조건
  • 해당 조건에 대한 오류 규칙의 동작을 정의하는 하나 이상의 정책

오류 처리를 참고하세요.

해당 사항 없음 아니요
DefaultFaultRule

다른 FaultRule에서 명시적으로 처리하지 않은 모든 오류(시스템, 전송, 메시징 또는 정책)를 처리합니다.

오류 처리를 참고하세요.

해당 사항 없음 아니요
ScriptTarget
ResourceURL

리소스 유형 (노드) 및 기본 Node.js 스크립트의 이름을 정의합니다. TargetEndpoint 기능을 구현합니다.

<ResourceURL>node://server.js</ResourceURL>

스크립트는 API 프록시의 리소스 파일에 포함되어야 합니다. Node.js 추가를 기존 API 프록시를 선택합니다.

ScriptTarget을 사용하는 경우 다른 유형의 대상 연결을 구성하지 않습니다. (HTTPTargetConnection 또는 LocalTargetConnection) 중 하나입니다.

해당 사항 없음
EnvironmentVariable

원하는 경우 기본 Node.js 스크립트에 환경 변수를 전달합니다.

Edge 이해 Node.js 모듈 지원을 참조하세요.

해당 사항 없음 아니요
Arguments

원하는 경우 기본 Node.js 스크립트에 인수를 전달합니다.

Edge 이해 Node.js 모듈 지원을 참조하세요.

해당 사항 없음 아니요

TLS/SSL TargetEndpoint 구성

TargetEndpoint에서 이기종 백엔드 인프라로 HTTPS 연결을 관리해야 하는 경우가 많습니다. 따라서 다양한 TLS/SSL 구성 설정이 지원됩니다.

를 통해 개인정보처리방침을 정의할 수 있습니다.

TLS/SSL TargetEndpoint 구성 요소

이름 설명 기본값 필수 여부
SSLInfo
Enabled 엔드포인트에 TLS/SSL이 사용 설정되었는지 여부를 나타냅니다. <URL>이 HTTPS 프로토콜을 지정하는 경우 기본값은 true이고 <URL>이 HTTP를 지정하는 경우 false입니다. <URL>이 HTTPS를 지정하면 true 아니요
TrustStore 신뢰할 수 있는 서버 인증서가 포함된 키 저장소 해당 사항 없음 아니요
ClientAuthEnabled 아웃바운드 클라이언트 인증을 사용 설정하는 설정(양방향 TLS/SSL) false 아니요
KeyStore 아웃바운드 클라이언트 인증에 사용되는 비공개 키가 포함된 키 저장소 해당 사항 없음 예(ClientAuthEnabled가 true인 경우)
KeyAlias 아웃바운드 클라이언트 인증에 사용되는 비공개 키의 키 별칭 해당 사항 없음 예(ClientAuthEnabled가 true인 경우)
Ciphers

아웃바운드 TLS/SSL에 지원되는 암호화입니다. 암호화를 지정하지 않으면 JVM에 사용 가능한 모든 암호화가 허용됩니다.

암호화를 제한하려면 지원되는 암호화를 나열하는 다음 요소를 추가합니다.

<Ciphers>
 <Cipher>TLS_RSA_WITH_3DES_EDE_CBC_SHA</Cipher>    
 <Cipher>TLS_RSA_WITH_DES_CBC_SHA</Cipher>
</Ciphers>
해당 사항 없음 아니요
Protocols

아웃바운드 TLS/SSL에 지원되는 프로토콜입니다. 프로토콜을 지정하지 않으면 JVM에 사용 가능한 모든 프로토콜이 허용됩니다.

프로토콜을 제한하려면 지원되는 프로토콜을 나열하는 다음 요소를 추가합니다.

<Protocols>
 <Protocol>TLSv1.1</Protocol>
 <Protocol>TLSv1.2</Protocol>
</Protocols>
해당 없음 아니요
CommonName

지정된 경우 대상 인증서의 일반 이름을 확인하는 값 이 값은 TargetEndpoint 및 TargetServer 구성에만 유효합니다. 그렇지 않습니다. VirtualHost 구성에 사용할 수 있습니다.

기본적으로 지정된 값은 대상 인증서의 일반 이름과 정확하게 일치됩니다. 예를 들어 <CommonName>의 값으로 *.myhost.com를 사용합니다. 는 정확한 값 *.myhost.com이 대상 인증서가 생성됩니다

원하는 경우 Apigee는 wildcardMatch 속성을 사용하여 와일드 카드와 일치를 수행할 수 있습니다.

예를 들어 대상 인증서에서 abc.myhost.com로 지정된 일반 이름이 일치되고 검증됩니다. <CommonName> 요소는 다음과 같이 지정됩니다.

<CommonName wildcardMatch="true">*.myhost.com</CommonName>

해당 사항 없음 아니요

아웃바운드 클라이언트 인증을 사용하는 샘플 TargetEndpoint

<TargetEndpoint name="default">
  <HttpTargetConnection>
        <URL>https://myservice.com</URL>
    <SSLInfo>
      <Enabled>true</Enabled>
      <ClientAuthEnabled>true</ClientAuthEnabled>
      <KeyStore>myKeystore</KeyStore>
      <KeyAlias>myKey</KeyAlias>
      <TrustStore>myTruststore</TrustStore>
    </SSLInfo>
  </HttpTargetConnection>
</TargetEndpoint>

자세한 내용은 TLS 구성 백엔드로 (클라우드 및 프라이빗 클라우드)

흐름 변수를 사용하여 동적으로 TLS/SSL 값 설정

TLS/SSL 세부정보를 동적으로 설정하여 유연한 런타임 요구사항을 지원할 수도 있습니다. 예를 들어 프록시가 잠재적으로 상이한 두 개의 대상(테스트 대상 및 프로덕션 대상)에 연결하는 경우 API 프록시를 통해 호출 중인 환경을 프로그래매틱 방식으로 감지하고 적절한 키 저장소 및 트러스트 저장소에 대한 참조를 동적으로 설정할 수 있습니다. 다음의 Apigee 커뮤니티 자료에서 이 시나리오를 자세히 설명하고 배포 가능한 API 프록시 예시를 제공합니다. https://community.apigee.com/articles/21424/dynamic-sslinfo-for-targetendpoint-using-variable.html

TargetEndpoint 구성에서 <SSLInfo> 태그가 설정되는 방식에 대한 다음 예시에서는 가령 자바 콜아웃, 자바스크립트 정책, 할당 메시지 정책 등으로 런타임 시에 값을 제공할 수 있습니다. 설정하려는 값이 포함된 메시지 변수를 사용하세요.

변수는 다음 요소에서만 허용됩니다.

<SSLInfo>
    <Enabled>{myvars.ssl.enabled}</Enabled>
    <ClientAuthEnabled>{myvars.ssl.client.auth.enabled}</ClientAuthEnabled>
    <KeyStore>{myvars.ssl.keystore}</KeyStore>
    <KeyAlias>{myvars.ssl.keyAlias}</KeyAlias>
    <TrustStore>{myvars.ssl.trustStore}</TrustStore>
</SSLInfo>

참조를 사용하여 동적으로 TLS/SSL 값 설정

HTTPS를 사용하는 TargetEndpoint를 구성할 때는 TLS/SSL 인증서가 만료되거나 시스템 구성이 변경되면 인증서를 업데이트해야 합니다. 포함 Edge for Private Cloud 설치를 사용하거나 정적 값을 사용하여 TLS/SSL을 구성하는 경우 흐름 변수를 사용하면 메시지 프로세서를 다시 시작해야 할 수 있습니다.

자세한 내용은 TLS 인증서 업데이트를 참고하세요.

그러나 원하는 경우 키 저장소 또는 트러스트 저장소에 대한 참조를 사용하도록 TargetEndpoint를 구성할 수 있습니다. 참조를 사용하면 메시지 프로세서를 다시 시작하지 않고도 다른 키 저장소 또는 트러스트 저장소를 가리키는 참조를 업데이트하여 TLS/SSL 인증서를 업데이트할 수 있다는 이점이 있습니다.

예를 들어 아래 TargetEndpoint는 키 저장소에 대한 참조를 사용합니다.

<SSLInfo> 
    <Enabled>true</Enabled> 
    <ClientAuthEnabled>false</ClientAuthEnabled> 
    <KeyStore>ref://keystoreref</KeyStore> 
    <KeyAlias>myKeyAlias</KeyAlias> 
</SSLInfo>

다음 POST API 호출을 사용하여 keystoreref라는 참조를 만드세요.

curl -X POST  -H "Content-Type:application/xml" https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/references \
-d '<ResourceReference name="keystoreref">
    <Refers>myTestKeystore</Refers>
    <ResourceType>KeyStore</ResourceType>
</ResourceReference>' -u email:password

참조는 키 저장소의 이름과 유형을 지정합니다.

참조를 보려면 다음 GET API 호출을 사용하세요.

curl -X GET https://api.enterprise.apigee.com/v1/o/[org_name}/e/{env_name}/references/keystoreref -u uname:password

다른 키 저장소를 가리키도록 나중에 참조를 변경하여 별칭의 이름을 동일하게 하려면 다음 PUT 호출을 사용합니다.

curl -X PUT -H "Content-Type:application/xml" https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/references/keystoreref \
-d '<ResourceReference name="keystoreref">
    <Refers>myNewKeystore</Refers>
    <ResourceType>KeyStore</ResourceType>
</ResourceReference>' -u email:password

대상 부하 분산을 사용하는 TargetEndpoint

TargetEndpoint는 세 개의 부하 분산 알고리즘을 사용하여 명명된 여러 개의 TargetServer에서 부하 분산을 지원합니다.

자세한 안내는 백엔드 서버 간 부하 분산을 참고하세요.

정책

API 프록시의 /policies 디렉터리에는 API 프록시의 흐름에 연결할 수 있는 모든 정책이 포함됩니다.

정책 구성 요소

이름 설명 기본값 필수 여부
Policy
name

정책의 내부 이름입니다. 이름에 사용할 수 있는 문자는 A-Za-z0-9._\-$ %로 제한됩니다. 하지만 에지 관리 UI는 영숫자가 아닌 문자를 자동으로 삭제하는 등의 제한 사항이 있습니다.

원하는 경우 <DisplayName> 요소를 사용하여 정책을 다른 자연어 이름으로 변경합니다.

해당 사항 없음
enabled

정책을 시행하려면 true로 설정합니다.

false로 설정하여 정책을 '사용 중지'합니다. 정책이 흐름에 연결되어 있어도 정책이 시행되지 않습니다.

true 아니요
continueOnError

정책이 실패할 경우 오류가 반환되도록 하려면 false로 설정합니다. 이는 대부분의 정책에서 예상되는 동작입니다.

정책이 실패해도 흐름 실행이 계속되도록 하려면 true로 설정합니다.

false 아니요
async

참고: 이 속성을 사용한다고 해서 정책이 비동기적으로 실행되지는 않습니다. 대부분의 경우 기본값 false을 그대로 둡니다.

true로 설정하면 정책 실행이 다른 스레드로 오프로드되므로 기본 스레드가 추가 요청을 처리할 수 있습니다. 오프라인 처리가 완료되면 기본 스레드가 다시 실행되어 메시지 흐름 처리가 완료됩니다. 경우에 따라 비동기를 true로 설정하면 API 프록시 성능이 향상됩니다. 하지만 비동기를 과도하게 사용하면 스레드 전환이 너무 많을 때 성능이 저하될 수 있습니다.

API 프록시에서 비동기 동작을 사용하려면 자바스크립트 객체 모델을 참고하세요.

false 아니요

정책 연결

다음 이미지에서는 API 프록시 흐름 실행 시퀀스를 보여줍니다.

클라이언트가 HTTP 서비스를 호출합니다. 요청은 ProxyEndpoint 및 TargetEndpoint에 노출되며 여기에는 각각 정책을 트리거하는 단계가 포함됩니다. HTTP 서비스가 응답을 반환하면 응답은 TargetEndpoint에서 처리된 후 ProxyEndpoint가 클라이언트에 반환되기 전에 처리됩니다. 요청과 마찬가지로 응답은 단계 내에서 정책에 의해 처리됩니다.

다음은 위 그림에 대한 설명입니다.

정책은 흐름의 처리 단계로 연결됩니다. 정책 이름은 처리 단계에서 적용할 정책을 참조하는 데 사용됩니다. 정책 연결 형식은 다음과 같습니다.

<Step><Name>MyPolicy</Name></Step>

정책은 흐름에 연결된 순서대로 적용됩니다. 예를 들면 다음과 같습니다.

<Step><Name>FirstPolicy</Name></Step>
<Step><Name>SecondPolicy</Name></Step>

정책 연결 구성 요소

이름 설명 기본값 필수 여부
Step
Name 이 단계 정의로 실행할 정책의 이름입니다. 해당 사항 없음
Condition 정책 적용 여부를 결정하는 조건문입니다. 정책에 연결된 조건이 있으면 조건문이 true로 평가될 때만 정책이 실행됩니다. 해당 사항 없음 아니요

흐름

ProxyEndpoint 및 TargetEndpoint는 요청 및 응답 메시지 처리를 위한 파이프라인을 정의합니다. 처리 파이프라인은 요청 흐름과 응답 흐름으로 구성됩니다. 각 요청 하나 이상의 선택적 '조건부'인 또는 '이름 지정' 포스트 플로우가 있습니다

  • PreFlow: 항상 실행됩니다. 조건부 흐름 전에 실행됩니다.
  • PostFlow: 항상 실행됩니다. 조건부 흐름 후에 실행됩니다.

또한 PostClientFlow를 ProxyEndpoint에 추가할 수 있으며 그러면 요청 측 클라이언트 앱에 응답이 반환된 후에 ProxyEndpointFlow가 실행됩니다. 이 흐름에는 MessageLogging 정책Google Stackdriver Logging 확장 프로그램만 연결할 수 있습니다. PostClientFlow는 API 프록시 지연 시간을 줄이고, 응답이 클라이언트에 반환될 때까지 계산하지 않는 로깅 정보(예: client.sent.start.timestampclient.sent.end.timestamp)를 제공합니다. 이 흐름은 주로 응답 메시지의 시작 타임스탬프와 종료 타임스탬프 사이의 시간 간격을 측정하는 데 사용됩니다.

간단한 안내 동영상 보기

동영상: PostClientFlow에서 메시지 로깅을 사용하는 방법에 관한 이 짧은 동영상을 확인해 보세요.

다음은 메시지 로깅 정책이 연결된 PostClientFlow의 예시입니다.

    ...
    <PostFlow name="PostFlow">
        <Request/>
        <Response/>
    </PostFlow>
    <PostClientFlow>
        <Request/>
        <Response>
            <Step>
                <Name>Message-Logging-1</Name>
            </Step>
        </Response>
    </PostClientFlow>
    ...

API 프록시 처리 파이프라인은 다음 순서로 흐름을 실행합니다.

요청 파이프라인:

  1. 프록시 요청 PreFlow
  2. 프록시 요청 조건부 흐름(선택사항)
  3. 프록시 요청 PostFlow
  4. 대상 요청 PreFlow
  5. 대상 요청 조건부 흐름(선택사항)
  6. 대상 요청 PostFlow

응답 파이프라인:

  1. 대상 응답 PreFlow
  2. 대상 응답 조건부 흐름(선택사항)
  3. 대상 응답 PostFlow
  4. 프록시 응답 PreFlow
  5. 프록시 응답 조건부 흐름(선택사항)
  6. 프록시 응답 PostFlow
  7. PostClientFlow 응답(선택사항)

정책이 연결된 흐름만 ProxyEndpoint 또는 TargetEndpoint 구성에서 구성해야 합니다. PreFlow 및 PostFlow는 PreFlow 또는 PostFlow 처리 중에 정책을 적용해야 하는 경우 ProxyEndpoint 또는 TargetEndpoint 구성에서만 지정해야 합니다.

조건부 흐름과 달리 PreFlow 및 PostFlow 요소의 순서는 중요하지 않습니다. API 프록시는 엔드포인트 구성에서 나타나는 위치와 관계없이 항상 파이프라인의 적절한 지점에서 실행됩니다.

조건부 흐름

ProxyEndpoint 및 TargetEndpoint는 제한된 수의 조건부 흐름('명명된 흐름'이라고도 함)을 지원합니다.

API 프록시는 조건부 흐름에서 지정된 조건을 테스트하고, 조건이 충족되면 조건부 흐름의 처리 단계가 API 프록시에 의해 실행됩니다. 조건이 충족되지 않으면 조건부 흐름의 처리 단계가 우회됩니다. 조건부 흐름은 API 프록시에 정의된 순서대로 평가되며 조건이 충족되는 첫 번째 흐름이 실행됩니다.

조건부 흐름을 정의하면 다음을 기준으로 API 프록시에 처리 단계를 적용할 수 있습니다.

  • 요청 URI
  • HTTP 동사(GET/PUT/POST/DELETE)
  • 쿼리 매개변수, 헤더, 양식 매개변수의 값
  • 기타 여러 유형의 조건

예를 들어 다음 조건부 흐름은 요청 리소스 경로가 /accesstoken일 때만 실행되도록 지정합니다. 경로가 /accesstoken인 인바운드 요청으로 인해 흐름에 연결된 정책과 함께 이 흐름이 실행됩니다. 요청 경로에 /accesstoken 서픽스가 포함되어 있지 않으면 흐름은 실행되지 않습니다(다른 조건부 흐름이 있을 수 있음).

<Flows>
  <Flow name="TokenEndpoint">
    <Condition>proxy.pathsuffix MatchesPath "/accesstoken"</Condition>
    <Request>
      <Step>
        <Name>GenerateAccessToken</Name>
      </Step>
    </Request> 
  </Flow>
</Flows>   

흐름 구성 요소

이름 설명 기본값 필수 여부
Flow ProxyEndpoint 또는 TargetEndpoint에서 정의한 요청 또는 응답 처리 파이프라인
Name 흐름의 고유한 이름입니다. 해당 사항 없음
Condition 하나 이상의 변수를 평가하여 true 또는 false로 평가되는 조건문입니다. 사전 정의된 PreFlow 및 PostFlow 유형을 제외한 모든 흐름이 실행 조건을 정의해야 합니다. 해당 사항 없음
Request 요청 메시지 처리와 관련된 파이프라인 해당 사항 없음 아니요
Response 응답 메시지 처리와 관련된 파이프라인 해당 사항 없음 아니요

단계 처리

Apigee Edge는 조건부 흐름의 순차 정렬을 적용합니다. 조건부 흐름은 하향식으로 실행됩니다. 조건이 true로 평가되는 첫 번째 조건부 흐름이 실행되며, 단 하나의 조건부 흐름만 실행됩니다.

예를 들어 다음 흐름 구성에서 경로 서픽스 /first 또는 /second를 포함하지 않는 모든 인바운드 요청은 ThirdFlow를 실행하여 Return404라는 정책을 적용합니다.

<Flows>
  <Flow name="FirstFlow">
    <Condition>proxy.pathsuffix MatchesPath "/first"</Condition>
    <Request>
      <Step><Name>FirstPolicy</Name></Step>
    </Request>
  </Flow>
  <Flow name="SecondFlow">
    <Condition>proxy.pathsuffix MatchesPath "/second"</Condition>
    <Request>
      <Step><Name>FirstPolicy</Name></Step>
      <Step><Name>SecondPolicy</Name></Step>
    </Request>
  </Flow>
  <Flow name="ThirdFlow">
    <Request>
      <Step><Name>Return404</Name></Step>
    </Request>
  </Flow>
</Flows>

리소스

'리소스'(API 프록시에서 사용할 리소스 파일)는 정책을 사용하여 흐름에 연결할 수 있는 스크립트, 코드, XSL 변환입니다. 이러한 항목은 '스크립트' 섹션에 나와 있습니다 프록시 편집기를 설정할 수 있습니다.

지원되는 리소스 유형은 리소스 파일을 참고하세요.

리소스는 API 프록시, 환경, 조직에 저장될 수 있습니다. 각각의 경우 리소스는 정책의 이름을 기준으로 참조됩니다. API 서비스는 API 프록시로부터 환경, 조직 수준으로 이동하여 이름을 확인합니다.

조직 수준에 저장된 리소스는 모든 환경의 정책을 기준으로 참조될 수 있습니다. 환경 수준에 저장된 리소스는 이 환경의 정책을 기준으로 참조될 수 있습니다. API 프록시 수준에 저장된 리소스는 이 API 프록시의 정책을 기준으로만 참조될 수 있습니다.