API 거버넌스

온라인에서 편집하기

API 거버넌스 도구는 스펙트럼 규칙 집합에 대해 OpenAPI 문서의 유효성을 검사합니다.

이 도구는 API Connect 의 API 거버넌스 기능을 API Agent 에서 사용할 수 있도록 제공됩니다. 예를 들어, 스펙트럼 규칙 집합에 대해 OpenAPI 문서의 유효성을 검사합니다. 또한 OpenAPI 3.0 문서 내에서 스펙트럼 유효성 검사 결과를 수정(교정)하는 데에도 사용할 수 있습니다.

도구 세부 정보 및 제한 사항

다음은 API 거버넌스 도구의 세부 사항 및 제한 사항입니다:
  • 온프레미스 설치( API Connect)에서 이 도구를 사용하려면 관리 CR에서 API 거버넌스를 사용 설정하세요.
  • 현재 API 거버넌스 도구는 API 거버넌스 서비스에서 최신 버전의 규칙 집합 작업을 지원합니다. 예를 들어 최신 버전의 규칙 집합으로 OpenAPI 문서의 유효성을 검사할 수 있습니다. 그러나 프롬프트를 사용할 때는 이전 버전을 지정할 수 없습니다. 이 제한은 OpenAPI 문서에서 유효성 검사 결과를 수정하기 위한 수정 작업에도 적용됩니다.
  • 이 도구의 수정(규칙 세트 포함) 작업은 AI 기반 수정 작업을 사용하며 시간이 다소 걸릴 수 있습니다. 더 크고 복잡한 OpenAPI 문서의 경우 이 시간이 더 오래 걸립니다. 기본 시간 제한인 3분이 적용됩니다. OpenAPI 문서를 수정하는 데 3분 이상 걸리면 도구가 시간 초과됩니다.
  • 최대 3분 동안 문제를 해결할 수 있도록 클러스터 인그레스 컨트롤러, 인그레스 경로 또는 HAProxy 시간 초과 설정이 3분 이내에 시간 초과되지 않도록 하세요.
API 거버넌스의 다음 기능은 API Agent 에서 사용할 수 있습니다:

규칙 집합 나열

공급자 조직 내에서 API 거버넌스의 일부로 제공되는 스펙트럼 규칙 집합을 나열할 수 있습니다.

표에는 규칙 집합에 대한 다음 세부 정보가 표시됩니다:
  • 이름
  • 버전
  • 설명
프롬프트 예제
List rulesets
다음 조치 제안
  • 규칙 집합을 사용하여 API 유효성 검사 {@filename} {ruleset}
  • 규칙 집합을 사용하여 API 유효성 검사 {draft-api-name}{draft-api-version} {ruleset}

규칙 집합에 규칙 나열

제공자 조직 내에서 사용할 수 있는 스펙트럼 규칙 집합의 일부인 모든 개별 규칙을 나열할 수 있습니다.

  • 표에는 지정된 규칙 집합 내의 각 규칙에 대한 다음 세부 정보가 나와 있습니다:
    • 이름
    • 설명
표 1. 매개변수
매개변수 필수 설명 기본값
ruleset 예 규칙을 나열할 규칙 집합 이름입니다. 없음
프롬프트 예시
List rules in ruleset {ruleset}
다음 조치 제안
  • 규칙 집합을 사용하여 API 유효성 검사 {@filename} {ruleset}
  • 규칙 집합을 사용하여 API 유효성 검사 {draft-api-name}{draft-api-version} {ruleset}

규칙 집합을 사용하여 OpenAPI 문서의 유효성을 검사합니다

제공자 조직에서 다음 옵션을 사용하여 스펙트럼 규칙 집합이 있는 OpenAPI 문서의 유효성을 검사할 수 있습니다:
  • Visual Studio Code 플러그인 채팅 창에서 로컬 파일 첨부 파일 업로드를 사용합니다.
  • API 관리자에서 사용자의 공급자 조직 내에 있는 기존 초안 API의 이름과 버전을 제공합니다.

이 작업을 수행하면 다음 세부 정보가 표시됩니다:

  • 스펙트럼 결과의 수와 그 심각도에 대한 간략한 요약입니다.
  • 검증 보고서. 다음의 모든 결과를 포함하고 있으며 다운로드 가능한. CSV 파일입니다:
    • 규칙 및 규칙 집합
    • 규칙을 위반하는 유효성 검사 결과를 설명하는 메시지입니다.
    • OpenAPI 문서의 줄 번호가 해당 결과에 해당합니다.
    • OpenAPI 문서 내 검색 결과의 위치(JSON 경로)입니다.
  • 다음 스크린샷과 같이 결과와 해당 위치도 문제 패널에서 열립니다.

  • OpenAPI 문서가 로컬 파일인 경우 Visual Studio Code 파일 편집기에서 자동으로 열립니다. 모든 스펙트럼 결과는 파일에서 강조 표시됩니다.
표 2. 매개변수
매개변수 필수 설명 기본값
input_file 아니오 유효성을 검사할 YAML 또는 JSON 형식의 OpenAPI 사양입니다. 없음
api_name 아니오 유효성을 검사할 API 초안의 이름(info.x-ibm-name)입니다. 없음
api_version 아니오 유효성을 검사할 API 초안의 버전(info.version)입니다. 없음
ruleset 예 유효성 검사에 사용할 규칙 집합 목록입니다. 없음
프롬프트 예시
단일 규칙 집합에 대해 로컬 파일의 유효성을 검사하려면 다음 프롬프트를 실행합니다:
validate api {@filename} using {ruleset} ruleset
두 개 이상의 규칙 세트에 대해 로컬 파일의 유효성을 검사하려면 다음 프롬프트를 실행합니다
Validate api {@filename} using rulesets {ruleset-1}, {ruleset-2}
단일 규칙 집합에 대해 초안 API의 유효성을 검사하려면 다음 프롬프트를 실행합니다
Validate api {api-name}:{api-version} using {ruleset} ruleset
여러 규칙 집합에 대해 초안 API의 유효성을 검사하려면 다음 프롬프트를 실행하세요
Validate api {api-name}:{api-version} using Rulesets {ruleset-1}, {ruleset-2}
다음 조치 제안
  • 규칙 집합을 사용하여 {@filename} API 수정하기 {ruleset}
  • 규칙 집합을 사용하여 API {@filename} 재검증하기 {ruleset}

또는

  • 규칙 집합을 사용하여 API {draft-api-name} : {draft-api-version} 수정하기 {ruleset}
  • 규칙 집합을 사용하여 API 재확인 {draft-api-name}{draft-api-version} {ruleset}

규칙 집합을 사용하는 OpenAPI 문서 수정(수정)

OpenAPI 문서의 API 거버넌스 유효성 검사에서 제공자 조직 내의 스펙트럼 규칙 집합을 기반으로 한 결과가 발견되면 AI 기반 해결 방법을 사용하여 이러한 결과를 해결할 수 있습니다. Visual Studio Code 플러그인 채팅 창에서 로컬 파일을 업로드하거나 API 관리자에서 기존 초안 API를 지정합니다.

이 작업을 수행하면 다음 세부 정보가 표시됩니다:

  • 다운로드할 수 있는 OpenAPI 문서 파일로, 선택한 규칙 집합에 대해 AI 기반 수정이 자동으로 수정할 수 있었던 모든 적용된 수정 사항이 포함되어 있습니다.

  • 또한 수정된 OpenAPI 문서 파일은 Visual Studio Code 파일 편집기에서 자동으로 열립니다. 적용된 수정 사항은 파일에서 바로 강조 표시됩니다.

  • 적용된 각 수정 사항에 대한 다음 세부 정보는 AI 권장 사항 패널에 표시됩니다:

    • 경로(JSON 경로)를 권장 사항에 추가합니다
    • 추천(설명)
    • 설명(권장 사항 설명)
    • 권장 사항의 출처가 되는 스펙트럼 규칙의 세부 정보(심각도, 규칙 집합 이름, 규칙 이름 및 메시지).
참고:
  • AI 기반 수정은 API 거버넌스의 스펙트럼-오와스 및 스펙트럼-오아스 규칙 집합에 대해서만 지원됩니다. 지원되지 않는 규칙 집합을 사용하여 문제를 해결하라는 메시지가 표시되면 API Agent 에서 지원되지 않는 규칙 집합이 채팅 응답에 사용되지 않았다는 경고가 표시됩니다.
  • 이 도구는 유효한 OpenAPI 3.0 문서가 입력으로 사용되기를 기대합니다. 잘못된 파일을 제공해도 경고가 표시되지 않습니다. 예를 들어 OpenAPI 문서에 적용되는 규칙이 있는 규칙 집합에 대한 입력으로 AsyncAPI 문서를 제공하거나 그 반대의 경우도 마찬가지입니다.
  • 처음에 문제를 찾지 못한 경우 동일한 OpenAPI 문서에서 문제 해결을 여러 번 실행하여 문제를 해결할 수 있습니다.
  • AI를 통해 수정 사항을 적용하면 시스템이 각 변경 후 규칙 집합에 대한 수정 및 권장 사항을 자동으로 검증하지 않기 때문에 다른 스펙트럼 규칙에 대한 새로운 위반이 발생할 수 있습니다.
표 3. 매개변수
매개변수 필수 설명 기본값
input_file 아니오 다시 수정할 YAML 또는 JSON 형식의 OpenAPI 사양입니다. 없음
api_name 아니오 수정할 초안 API의 이름(info.x-ibm-name)입니다. 없음
api_version 아니오 수정할 API 초안의 버전(info.version)입니다. 없음
ruleset 예 수정에 사용할 규칙 집합 목록입니다. 없음
프롬프트 예시
규칙 집합에 대해 로컬 파일을 수정하려면 다음 프롬프트를 실행하세요:
Remediate api {@filename} using {ruleset} ruleset
두 개 이상의 규칙 집합에 대해 로컬 파일을 수정하려면 다음 프롬프트를 실행하세요:
Remediate api {@filename} using rulesets {ruleset-1}, {ruleset-2}
단일 규칙 집합에 대해 초안 API를 수정하려면 다음 프롬프트를 실행하세요:
Remediate api {api-name}:{api-version} using {ruleset} ruleset
여러 규칙 집합에 대해 초안 API를 수정하려면 다음 프롬프트를 실행하세요:
Remediate api {api-name}:{api-version} using Rulesets {ruleset-1}, {ruleset-2}
다음 조치 제안
  • 규칙 집합을 사용하여 {@filename} API 다시 수정하기 {ruleset}
  • 규칙 집합을 사용하여 API 유효성 검사 {@filename} {ruleset}

또는

  • 규칙 집합을 사용하여 API {draft-api-name} : {draft-api-version} 다시 수정하기 {ruleset}
  • 규칙 집합을 사용하여 API 유효성 검사 {draft-api-name}{draft-api-version} {ruleset}