Application Integration에 지원되는 커넥터를 참조하세요.

통합의 OpenAPI 사양 보기

애플리케이션 통합은 하나 이상의 API 트리거로 구성된 게시된 통합의 OpenAPI 사양을 동적으로 생성하고 볼 수 있는 기능을 제공합니다. 통합의 OpenAPI 사양에 액세스하면 다음 작업을 할 수 있습니다.

  • 통합의 API 엔드포인트, 메서드, 데이터 구조를 포괄적으로 이해합니다.
  • 통합 API의 세부적이고 중앙 집중식 보기를 제공하여 더 효율적인 개발 및 문제 해결을 지원합니다.
  • 통합 API를 노출하고 Google Cloud 대화형 에이전트와 같은 대화형 에이전트와 원활하게 통합합니다.

OpenAPI 사양이란 무엇인가요?

OpenAPI 사양 로고

OpenAPI 사양 (OAS)은 RESTful API를 설명하는 언어와 관계없는 표준 형식입니다. 일반적으로 YAML 또는 JSON 형식으로 작성되는 OpenAPI 사양은 기본 URL, 경로 및 동사, 헤더, 쿼리 매개변수, 콘텐츠 유형, 요청 및 응답 모델과 같은 API 요소에 대한 공식 설명을 제공합니다. OpenAPI 사양에 대한 자세한 내용은 OpenAPI 사양을 참고하세요.

OpenAPI 사양 생성 및 보기

Google Cloud 콘솔의 통합 편집기에서 또는 API 호출을 사용하여 통합의 OpenAPI 사양을 동적으로 생성하고 볼 수 있습니다.

시작하기 전에

  • 통합이 하나 이상의 API 트리거로 구성되어 있는지 확인합니다. API 트리거 구성에 대한 자세한 내용은 API 트리거를 참고하세요.
  • 통합을 게시합니다. 통합을 게시하는 방법에 대한 자세한 내용은 통합 테스트 및 게시를 참고하세요.

OpenAPI 사양 보기

통합의 OpenAPI 사양을 보려면 다음 옵션 중 하나를 선택합니다.

콘솔

특정 통합의 OpenAPI 사양을 보려면 다음 단계를 따르세요.

  1. Application Integration 페이지로 이동합니다.

    Application Integration으로 이동

  2. 탐색 메뉴에서 통합을 클릭합니다.

    Google Cloud 프로젝트에서 사용할 수 있는 모든 통합이 나열된 통합 페이지가 나타납니다.

  3. OpenAPI 사양을 보려는 통합을 클릭합니다. 통합 편집기에서 통합이 열립니다.
  4. 통합 편집기 툴바에서 (작업 메뉴)를 클릭하고 OpenAPI 사양 보기를 선택합니다.

    통합의 OpenAPI 사양을 표시하는 OpenAPI 사양 보기 창이 표시됩니다. 생성된 OpenAPI 사양에는 기본적으로 통합에 구성된 모든 API 트리거가 포함됩니다.

    • 특정 API 트리거의 OpenAPI 사양을 보려면 API 드롭다운 목록에서 API 트리거를 선택합니다.
    • OpenAPI 사양을 YAML 파일로 다운로드하려면 다운로드 를 클릭합니다.

API

Application Integration API의 generateOpenApiSpec 메서드를 사용하면 API 호출을 통해 통합의 OpenAPI 사양을 볼 수 있습니다.

다음 curl 명령어를 사용하여 동일한 리전의 하나 이상의 통합에 대한 OpenAPI 사양을 확인합니다.

curl -X POST \
    -H "authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{
    "apiTriggerResources": [{
    "integrationResource": "INTEGRATION_NAME",
    "triggerId": ["api_trigger/TRIGGER_NAME", "api_trigger/TRIGGER_NAME_2", "api_trigger/TRIGGER_NAME_n"]
    },
    {
    "integrationResource": "INTEGRATION_NAME",
      "triggerId": ["api_trigger/TRIGGER_NAME"]
    }],
    "fileFormat": "DOC_TYPE"
    }' \
    "https://LOCATION-integrations.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/integrations/-:generateOpenApiSpec"

다음을 바꿉니다.

  • TRIGGER_NAME, TRIGGER_NAME_2, TRIGGER_NAME_n: OpenAPI 사양을 확인하려는 통합의 API 트리거 이름입니다.
  • INTEGRATION_NAME: 통합의 이름입니다.
  • DOC_TYPE: 생성할 문서 유형입니다. 지원되는 값은 YAML 또는 JSON입니다.
  • PROJECT_ID: Google Cloud 프로젝트의 ID입니다.
  • LOCATION: Google Cloud 프로젝트의 위치입니다.

OpenAPI 사양 이해하기

Application Integration은 OpenAPI 사양 3.0 표준에 따라 게시된 통합의 OpenAPI 사양을 생성합니다. 다음 표에서는 Application Integration에서 생성된 OpenAPI 사양의 요소를 설명합니다.

요소 설명
openapi 사용된 OpenAPI 사양 버전입니다.
info 이름 (제목), 설명, 게시된 버전과 같은 통합에 관한 정보
servers 통합을 호스팅하는 서버 URL입니다.
paths 통합에서 선택한 각 API 트리거에 대해 경로가 생성됩니다. 서버 URL과 경로를 결합하면 API 호출을 위한 API 엔드포인트가 구성됩니다.

Request 및 Response 필드는 상응하는 API 트리거에 구성된 입력 및 출력 변수를 기반으로 채워집니다.

components schemas 필드에는 API 트리거의 입력 및 출력 변수에 대한 JSON 스키마가 포함됩니다.

securitySchemes 필드에는 API 트리거의 인증 정보가 포함됩니다.

고려사항

통합의 OpenAPI 사양을 볼 때는 다음 고려사항이 적용됩니다.

  • OpenAPI 사양은 게시된 통합에 대해서만 생성됩니다.
  • OpenAPI 사양은 하나 이상의 API 트리거로 구성된 통합에 대해서만 생성됩니다.
  • OpenAPI 사양은 동일한 리전에 있는 통합에 대해서만 생성됩니다.
  • OpenAPI 사양은 기본적으로 YAML 형식으로 생성됩니다. JSON 형식으로 OpenAPI 사양을 생성하고 보려면 API 호출에서 fileFormat 매개변수를 JSON로 설정하세요.
  • Application Integration은 현재 다음과 같은 제한된 JSON 스키마 키워드 집합만 지원합니다.
    • type
    • items
    • properties
    • description
    • required
    • array
    • object
    • oneOf
    • allOf
    • anyOf
    • not
    • null
    • enum
    • additionalProperties
    • default
  • Swagger 편집기를 사용하여 OpenAPI 사양을 검증할 때 다음 이미지와 같이 API 경로와 관련된 시맨틱 오류가 발생할 수 있습니다.

    Swagger 편집기 Swagger 편집기

    이러한 오류는 무시해도 됩니다. OpenAPI 사양은 여전히 유효합니다.