API 통합을 위한 API 요구사항

이 문서에서는 Deployment Manager에 유형 공급자로 추가하려는 API의 일반 요구사항을 설명합니다. 이러한 가이드라인에 따라 Deployment Manager에 요구되는 API의 특성을 이해할 수 있습니다. API가 여기에 설명된 사양과 정확하게 일치하지 않을 경우, 고급 API 옵션을 사용하여 이러한 불일치 문제를 해결할 수 있습니다.

API에 유효한 설명자 문서가 포함됨

설명자 문서는 API 및 해당 리소스를 설명합니다. OpenAPI 사양 또는 Google Discovery 설명자 문서로 지원되는 API만 Deployment Manager에 통합할 수 있습니다. OpenAPI 사양을 만드는 방법에 대한 자세한 내용은 OpenAPI GitHub 저장소를 참조하세요.

API 설명자 문서 엔드포인트에 액세스 가능

Deployment Manager는 API 설명자 문서를 가져오기 위해 HTTP 요청을 수행합니다. 따라서 Deployment Manager가 액세스할 수 있는 위치에서 문서를 호스팅해야 합니다. 이러한 위치는 공개적으로 사용할 수 있는 URL이거나 기본 인증으로 보호되는 엔드포인트일 수 있습니다.

특정 Google 서비스에서 호스팅되는 경우 API가 기본 인증 또는 OAuth2 수락

Deployment Manager는 개발자가 프로젝트의 서비스 계정을 사용하기 위해 인증을 설정할 수 있는 Kubernetes Engine 또는 Google Endpoints에서 호스팅되는 특정 API에 대해 현재까지 기본 인증(사용자 이름과 비밀번호) 및 OAuth 2.0 인증을 지원합니다.

자세한 내용은 유형 공급자 만들기를 참조하세요.

CRUD(만들기, 읽기, 업데이트, 삭제) 작업 지원

문제의 API는 CRUD 작업을 지원하는 RESTful API여야 합니다. 즉, 다음을 수행하는 메소드가 있습니다.

  • 만들기 작업 - 리소스를 만듭니다. HTTP POST 요청이어야 합니다.
  • 읽기 작업 - API 리소스에 대한 정보를 가져옵니다. HTTP GET 요청이어야 합니다.
  • 업데이트 작업 - 리소스를 업데이트합니다. HTTP PUT 요청이어야 합니다.
  • 삭제 작업 - 리소스를 삭제합니다. HTTP DELETE 요청이어야 합니다.

부분적인 CRUD 작업만 지원하는 API도 계속 작동하지만 사용 가능한 작업에 따라 동작이 달라집니다.

GET 요청 지원 CREATE 요청 지원 UPDATE 요청 지원 DELETE 요청 지원 특별한 API 동작 여부
예 예 예 예 없음
예 예 예 아니요 사용자가 리소스를 폐기할 수 있지만 삭제할 수는 없습니다.
예 예 아니요 예 기존 리소스에 대한 모든 변경이 실패합니다. 리소스를 업데이트하려면 사용자가 리소스를 삭제하고 다시 만들어야 합니다.
예 예 아니요 아니요 위에 설명된 동작 모두
예 아니요 예 예 API가 만들기 요청을 지원하지 않을 경우, 사용자가 배포를 ACQUIRE 정책으로 업데이트하여 배포에 기존 리소스를 추가할 수 있습니다.
예 아니요 예 아니요 사용자가 리소스를 획득한 후 이를 가져오거나 업데이트할 수 있지만, 리소스를 삭제할 수는 없습니다.
예 아니요 아니요 예 사용자가 리소스를 삭제하고, 리소스를 가져오거나, 기존 리소스를 배포에 추가할 수 있습니다.
예 아니요 아니요 아니요 사용자가 ABANDON 정책을 사용하여 기존 리소스를 가져오거나 삭제할 수 있습니다.

모든 경로와 쿼리 매개변수를 성공적으로 확인

API의 모든 경로 및 쿼리 매개변수가 리소스 본문의 일부로 존재하거나 API의 모든 메서드에 존재해야 합니다. 그러면 사용자가 매개변수를 제공할 때 Deployment Manager가 이를 일치시킬 수 있습니다. 경로 및 쿼리 매개변수에는 다음 조건이 적용됩니다.

POST의 모든 경로/쿼리 매개변수는 PUT의 매개변수여야 함

myParameter가 POST에 있지만 PUT에는 없으므로 다음 구문은 유효하지 않습니다.

POST  /my-api/{myParameter}/resource/{mySecondParameter}
PUT   /my-api/resource/{mySecondParameter}  # myParameter is not present

POST가 아닌 메서드의 모든 매개변수는 모든 메서드 인터페이스에 또는 리소스의 일부로 존재해야 하며, 특히 이 매개변수가 서버에서 생성되는지 여부를 고려해야 합니다.

최적 사례 시나리오에서는 API가 다음과 같을 수 있으며, 여기서 모든 메서드에 name 매개변수가 나타납니다.

POST   /my-api/my-resource/{name}
PUT    /my-api/my-resource/{name}
GET    /my-api/my-resource/{name}
DELETE /my-api/my-resource/{name}

다른 시나리오에서는 필드가 메서드의 경로 매개변수로 표시될 수 있지만 다른 메서드의 경로 매개변수로는 표시되지 않습니다. 이 사례에서 필드는 API 리소스의 일부여야 합니다. 예를 들면 다음과 같습니다.

POST  /my-api/my-resource ← the 'id' field  is not present on the POST request
GET   /my-api/my-resource/{id}

schema for my-resource
type: object
properties:
# id is part of the resource so Deployment Manager will use this value for
# POST requests after creation
  id:
    type: string

이 예에서는 id가 리소스에 존재하지만 POST 요청을 수행할 때 존재하지 않는 서버 생성 값이라고 가정합니다. 기존 리소스에 요청을 보내려면 id 속성이 필요하지만 속성이 리소스에 없거나 경로에 제공되지 않았으면 이로 인해 API를 Deployment Manager에 포팅할 때 문제가 발생할 수 있습니다.

미세한 API 동작에 추가 구성 필요

특정 API 동작은 API를 Deployment Manager와 통합하기 위해 추가적인 API 구성이 필요합니다. 이러한 동작은 다음과 같습니다.

  • 서버 생성 값: 일부 API 리소스에는 각 요청 이후 또는 특정 이벤트가 API에서 발생할 때 변경되는 서버 생성 속성이 있습니다. 고급 API 옵션을 사용하여 요청이 수행될 때마다 Deployment Manager가 이 새로운 값을 가져오도록 지정할 수 있습니다.

    예를 들어 API가 업데이트 요청을 허용하려면 리소스의 최신 지문 속성이 필요할 수 있습니다. 고급 API 옵션을 사용하여 사용자가 배포를 업데이트하기 위해 요청을 수행할 때마다 Deployment Manager가 이 값을 가져오도록 지정할 수 있습니다.

  • 사용자 입력 조작: 예를 들어 API에서 항상 필드 값에 프로젝트 ID를 프리픽스로 지정하도록 요구하는 경우 사용자가 이를 수동으로 추가하도록 강제하는 대신 입력 매핑을 사용하여 이러한 정보를 자동으로 추가할 수 있습니다.

  • 각 메소드에서 변경되는 필드 값: 동일 필드를 재사용하지만 다른 값으로 바꾸는 메소드의 경우 API 옵션을 활용하여 언제, 어떤 값을 사용할지를 Deployment Manager에 지정할 수 있습니다.

자세한 내용은 고급 API 옵션 설정을 참조하세요.

다음 단계