OpenAPI 사양에서 API 프록시 만들기

이 페이지는 Apigee 및 Apigee Hybrid에 적용됩니다.

학습할 내용

이 튜토리얼에서는 다음 방법을 배웁니다.

OpenAPI 사양에서 Apigee API 프록시를 만듭니다.
cURL을 사용하여 API 프록시를 호출합니다.
조건부 흐름에 정책을 추가합니다.
cURL을 사용하여 정책 호출을 테스트합니다.

Apigee UI를 사용하여 OpenAPI 사양에서 Apigee API 프록시를 만드는 방법을 알아봅니다. cURL과 같은 HTTP 클라이언트로 API 프록시를 호출하면 API 프록시가 요청을 Apigee 모의 대상 서비스로 전송합니다.

Open API Initiative 정보

"Open API Initiative(OAI)는 Swagger 사양에 따라 공급업체 중립적인 API 설명 형식을 생성, 진화, 홍보하는 데 중점을 두고 있습니다." Open API Initiative에 대한 자세한 내용은 OpenAPI 사양을 참조하세요.

OpenAPI 사양에서는 표준 형식을 사용하여 RESTful API를 설명합니다. JSON 또는 YAML 형식으로 작성된 OpenAPI 사양을 머신에서 읽을 수 있지만 사람도 쉽게 읽고 이해할 수 있습니다. 사양은 기본 경로, 경로 및 동사, 헤더, 쿼리 매개변수, 작업, 콘텐츠 유형, 응답 설명과 같은 API 요소를 설명합니다. 또한 OpenAPI 사양은 일반적으로 API 참고 리소스를 생성하는 데 사용됩니다.

Apigee 모의 대상 서비스에 대한 정보

이 튜토리얼에서 사용되는 Apigee 모의 대상 서비스는 Apigee에서 호스팅되며 간단한 데이터를 반환합니다. API 키 또는 액세스 토큰이 필요하지 않습니다. 실제로 웹브라우저에서 액세스할 수 있습니다. 다음을 클릭하여 사용해 보세요.

http://mocktarget.apigee.net

대상 서비스가 인사말 Hello, guest!를 반환합니다.

모의 대상 서비스가 지원하는 전체 API 세트에 대한 자세한 내용은 Apigee Sample API를 참조하세요.

준비물

시작하기 전에, 개요 및 기본 요건의 단계를 완료해야 합니다.
OpenAPI 사양. 이 튜토리얼에서는 Apigee의 모의 대상 서비스인 http://mocktarget.apigee.net을 설명하는 mocktarget.yaml OpenAPI 사양을 사용합니다. 자세한 내용은 apigee/api-platform-samples를 참조하세요.
명령줄에서 API 호출을 수행하기 위해 머신에 설치된 cURL 또는 웹브라우저

API 프록시 만들기

OpenAPI 사양에서 API 프록시를 만들려면 다음 안내를 따르세요.

Cloud 콘솔의 Apigee

Google Cloud 콘솔에서 프록시 개발 > API 프록시 페이지로 이동합니다.

API 프록시로 이동
API 프록시 창에서 + 만들기를 클릭합니다.
프록시 만들기 창의 프록시 템플릿 > OpenAPI 사양 템플릿에서 리버스 프록시(가장 일반적)를 선택합니다.

웹브라우저에서 다음 URL로 이동합니다.

https://raw.githubusercontent.com/apigee/api-platform-samples/master/default-proxies/helloworld/openapi/mocktarget3.0.yaml

표시된 코드를 마우스 오른쪽 버튼으로 클릭하고 다른 이름으로 저장을 선택합니다.
저장을 클릭하여 원하는 위치에 mocktarget3.0.yaml을 저장합니다.
OpenAPI 사양 필드에서 찾아보기 버튼을 클릭합니다.
mocktarget3.0.yaml 파일로 이동하여 열기를 클릭합니다.
다음을 클릭합니다.
프록시 만들기 마법사의 프록시 세부정보 단계에서는 OpenAPI 사양에서 직접 추출한 값으로 필드가 자동으로 채워집니다.

다음 표에서는 OpenAPI 사양을 사용하여 미리 채워진 기본값을 설명합니다.

필드	설명	기본값
프록시 이름	API 프록시 이름입니다. 예를 들면 `Mock-Target-API`입니다.	대시에 의해 공백이 교체된 OpenAPI 사양의 `title` 속성
기본 경로	조직 내에서 이 API 프록시를 고유하게 식별하는 경로 구성요소입니다. 이 API 프록시의 공개용 URL은 외부 또는 내부 도메인 이름과 이 기본 경로로 구성됩니다. 예를 들면 다음과 같습니다. `http://apitest.acme.com/mock-target-api`	이름 필드 콘텐츠가 모두 소문자로 변환됨
설명	API 프록시의 설명입니다.	OpenAPI 사양의 `description` 속성
대상(기존 API)	이 API 프록시를 대신하여 호출된 대상 URL. 개방형 인터넷을 통해 액세스할 수 있는 모든 URL을 사용할 수 있습니다. 예를 들면 다음과 같습니다. `http://mocktarget.apigee.net`	OpenAPI 사양의 `servers` 속성

다음은 OpenAPI 사양에서 필드를 자동 입력하는 데 사용되는 속성을 보여주는 발췌문을 제공합니다.

      openapi: 3.0.0
      info:
        description: OpenAPI Specification for the Apigee mock target service endpoint.
        version: 1.0.0
        title: Mock Target API
      paths:
        /:
          get:
            summary: View personalized greeting
            operationId: View a personalized greeting
            description: View a personalized greeting for the specified or guest user.
            parameters:
              - name: user
                in: query
                description: Your user name.
                required: false
                schema:
                  type: string
            responses:
              "200":
                description: Success
      ...
      servers:
        - url: http://mocktarget.apigee.net
        - url: https://mocktarget.apigee.net
      ...

프록시 세부정보 페이지에서 설명 필드를 다음과 같이 수정합니다.
```
API proxy for the Apigee mock target service endpoint.
```
다음을 클릭합니다.
흐름 단계에서 모든 작업이 선택되었는지 확인합니다.
팁: 조건부 흐름은 OpenAPI 사양의 paths 객체 내에 정의된 작업으로부터 자동으로 생성됩니다. 조건부 흐름은 Apigee에 "이 메시지가 표시되면 이 로직을 수행하라"고 명령합니다. 예를 들어 API 호출이 /xml 리소스(조건)의 GET인 경우, 조건부 흐름에 연결된 정책을 통해 응답을 JSON으로 변환합니다. 트랜잭션당 하나의 흐름, 즉 조건이 true로 평가되는 첫 번째 흐름만 수행합니다.
다음을 클릭합니다.
배포 단계에서 하나 이상의 환경을 선택하고 확인을 클릭합니다.
만들기를 클릭합니다.

기본 Apigee UI

개발 > API 프록시를 선택하고 프록시 창에서 프록시 환경을 선택합니다.
기본 창에서 API 프록시를 클릭합니다.
또는 왼쪽 탐색 메뉴에서 개발 > API 프록시를 선택할 수 있습니다.
새로 만들기를 클릭합니다.
프록시 만들기 마법사에서 리버스 프록시(가장 일반적) 템플릿에 대해 OpenAPI 사양 사용을 클릭합니다.
URL을 클릭하고 다음 정보를 입력합니다.
OpenAPI 사양 URL: URL 필드에서 GitHub의 OpenAPI 사양에 대한 원시 콘텐츠 경로입니다.
```
https://raw.githubusercontent.com/apigee/api-platform-samples/master/default-proxies/helloworld/openapi/mocktarget3.0.yaml
```

선택을 클릭합니다.

프록시 만들기 마법사의 프록시 세부정보 페이지가 표시됩니다. 필드는 다음 그림과 같이 OpenAPI 사양에 정의된 값을 사용하여 미리 채워집니다.

다음 표에서는 OpenAPI 사양을 사용하여 미리 채워진 기본값을 설명합니다.

필드	설명	기본값
이름	API 프록시 이름입니다. 예를 들면 `Mock-Target-API`입니다.	대시에 의해 공백이 교체된 OpenAPI 사양의 `title` 속성
기본 경로	조직 내에서 이 API 프록시를 고유하게 식별하는 경로 구성요소입니다. 이 API 프록시의 공개용 URL은 외부 또는 내부 도메인 이름과 이 기본 경로로 구성됩니다. 예를 들면 `http://apitest.acme.com/mock-target-api`입니다.	이름 필드 콘텐츠가 모두 소문자로 변환됨
설명	API 프록시의 설명입니다.	OpenAPI 사양의 `description` 속성
대상(기존 API)	이 API 프록시를 대신하여 호출된 대상 URL. 개방형 인터넷을 통해 액세스할 수 있는 모든 URL을 사용할 수 있습니다. 예를 들면 `http://mocktarget.apigee.net`입니다.	OpenAPI 사양의 `servers` 속성

다음은 OpenAPI 사양에서 필드를 자동 입력하는 데 사용되는 속성을 보여주는 발췌문을 제공합니다.

openapi: 3.0.0
info:
  description: OpenAPI Specification for the Apigee mock target service endpoint.
  version: 1.0.0
  title: Mock Target API
paths:
  /:
    get:
      summary: View personalized greeting
      operationId: View a personalized greeting
      description: View a personalized greeting for the specified or guest user.
      parameters:
        - name: user
          in: query
          description: Your user name.
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Success
...
servers:
  - url: http://mocktarget.apigee.net
  - url: https://mocktarget.apigee.net
...

프록시 세부정보 페이지에서 설명 필드를 다음과 같이 수정합니다.
```
API proxy for the Apigee mock target service endpoint.
```
다음을 클릭합니다.
일반 정책 페이지의 보안: 승인에서 통과(승인 없음)가 선택되었는지 확인하고 다음을 클릭합니다.
흐름 페이지에서 모든 작업이 선택되었는지 확인합니다.
팁: 조건부 흐름은 OpenAPI 사양의 paths 객체 내에 정의된 작업으로부터 자동으로 생성됩니다. 조건부 흐름은 Apigee에 "이 메시지가 표시되면 이 로직을 수행하라"고 명령합니다. 예를 들어 API 호출이 /xml 리소스(조건)의 GET인 경우, 조건부 흐름에 연결된 정책을 통해 응답을 JSON으로 변환합니다. 트랜잭션당 하나의 흐름, 즉 조건이 true로 평가되는 첫 번째 흐름만 수행합니다.
다음을 클릭합니다.
요약 페이지의 선택적 배포에서 환경이 선택되어 있는지 확인하고 만들기 및 배포를 클릭합니다.

Apigee는 새 API 프록시를 만들어 개발자 환경에 배포합니다.
프록시 수정을 클릭하여 API 프록시의 개요 페이지를 표시합니다.

API 프록시 테스트

cURL 또는 웹브라우저를 사용하여 Mock-Target-API API를 테스트할 수 있습니다.

curl -v YOUR_ENV_GROUP_HOSTNAME/myproxy

여기서 YOUR_ENV_GROUP_HOSTNAME은 환경 그룹 호스트 이름입니다. 환경 그룹 호스트 이름 찾기를 참조하세요.

예를 들면 다음과 같습니다.

curl -v -k https://apitest.acme.com/myproxy

응답

다음과 같은 응답이 표시됩니다.

Hello, Guest!

JSON 정책에 XML 추가

다음으로, OpenAPI 사양에서 API 프록시를 만들 때 자동으로 생성된 XML 응답 보기 조건부 흐름에 대한 JSON 정책에 XML을 추가합니다. 정책은 대상의 XML 응답을 JSON 응답으로 변환합니다.

먼저 API를 호출하여 정책을 추가한 후에 얻은 결과와 비교할 수 있습니다. 터미널 창에서 다음 cURL 명령어를 실행합니다. 대상 서비스의 /xml 리소스를 호출하면 기본적으로 XML의 간단한 블록이 반환됩니다.

curl -v https://YOUR_ENV_GROUP_HOSTNAME/mock-target-api/xml

여기서 YOUR ENV_GROUP_HOSTNAME은 환경 그룹 호스트 이름입니다. 환경 그룹 호스트 이름 찾기를 참조하세요.

응답

다음과 같은 응답이 표시됩니다.

<root> 
  <city>San Jose</city> 
  <firstName>John</firstName> 
  <lastName>Doe</lastName> 
  <state>CA</state> 
</root>

이제 XML 응답을 JSON으로 변환하는 작업을 해보겠습니다. API 프록시에서 XML에서 JSON으로 변환 정책을 XML 응답 보기 조건부 흐름에 추가합니다.

Cloud 콘솔의 Apigee

Apigee UI의 Mock-Target-API 개요 페이지에서 개발 탭을 클릭합니다.

XML 응답 보기 선택

왼쪽 창의 프록시 엔드포인트 > 기본값에서 XML 응답 보기 조건부 흐름을 클릭합니다.
왼쪽 창에서 정책 행에 있는 + 버튼을 클릭합니다.
정책 만들기 대화상자에서 정책 유형 선택 필드를 클릭하고 미디에이션으로 스크롤하고 XMLToJSON을 선택합니다. 표시 이름과 이름의 기본값을 그대로 둡니다.
만들기를 클릭하여 정책을 만듭니다.
응답에서 XML 응답 보기 흐름 옆에 있는 + 버튼을 클릭합니다.
정책 단계 추가 대화상자에서 기존 정책 선택 필드를 클릭하고 XML to JSON-1을 선택합니다.
추가를 클릭합니다. XML to JSON 정책이 응답에 적용됩니다.

XML 응답 보기 조건부 흐름의 코드를 보려면 코드 편집기로 전환을 클릭합니다.
저장을 클릭합니다.

기본 Apigee UI

Apigee UI의 Mock-Target-API 개요 페이지에서 개발 탭을 클릭합니다.
왼쪽 탐색기 창의 프록시 엔드포인트 > 기본값에서 XML 응답 보기 조건부 흐름을 클릭합니다.
흐름의 응답에 해당하는 하단의 +단계 버튼을 클릭합니다.

단계 추가 대화상자가 열리고 추가할 수 있는 모든 정책이 분류된 목록이 표시됩니다.
미디에이션 카테고리로 스크롤하고 XML to JSON을 선택합니다.
표시 이름과 이름의 기본값을 그대로 둡니다.
추가를 클릭합니다. XML to JSON 정책이 응답에 적용됩니다.
저장을 클릭합니다.

정책을 추가했으므로 이제 cURL을 사용하여 API를 다시 호출합니다. 동일한 /xml 리소스를 여전히 호출하는 중입니다. 대상 서비스는 여전히 XML 블록을 반환하지만 이제 API 프록시의 정책이 응답을 JSON으로 변환합니다. 다음과 같이 호출합니다.

curl -v https://YOUR_ENV_GROUP_HOSTNAME/mock-target-api/xml

여기서 YOUR ENV_GROUP_HOSTNAME은 환경 그룹 호스트 이름입니다. 환경 그룹 호스트 이름 찾기를 참조하세요.

XML 응답은 JSON으로 변환됩니다.

{"root":{"city":"San Jose","firstName":"John","lastName":"Doe","state":"CA"}}

OpenAPI 사양에서 API 프록시 만들기 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

준비물

API 프록시 만들기

Cloud 콘솔의 Apigee

기본 Apigee UI

API 프록시 테스트

JSON 정책에 XML 추가

Cloud 콘솔의 Apigee

기본 Apigee UI

OpenAPI 사양에서 API 프록시 만들기