API 검색 및 필터링

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

이 주제에서는 Vertex AI 기반 시맨틱 검색과 필터 기반 검색 옵션을 사용하여 API 허브에서 특정 리소스를 검색하는 방법을 설명합니다.

그림 1. API 허브는 강력한 자연어 검색 및 필터링 기능을 제공합니다.

시맨틱 검색을 사용하여 API 허브 검색

시맨틱 검색을 사용하여 API 허브에 등록된 API 리소스를 쉽게 찾고 볼 수 있습니다. 시맨틱 검색을 사용하면 자유 텍스트 검색어를 사용하여 인스턴스에서 사용 가능한 모든 API 리소스를 검색할 수 있습니다. 모든 항목 유형(API, API 작업, 사양 등)을 검색할 수 있으며, 또는 쿼리할 항목 유형을 지정할 수 있습니다.

시맨틱 검색은 Vertex AI 검색엔진을 통해 검색어 '일치' 외에도 다른 작업을 수행할 수 있습니다. 시맨틱 검색은 입력된 자유 텍스트 검색어와 의미상으로 유사한 세부 API 리소스 항목의 임의 위치에 있는 용어가 포함된 결과를 반환합니다.

자유 텍스트 검색은 다음과 같은 결과 카테고리를 반환합니다.

• API: 검색어와 일치하는 API 목록입니다. 각 API에 대해 다음 세부정보가 제공됩니다.
  • API 세부정보 페이지 링크와 함께 API 이름이 표시됩니다.
  • 리소스에 대한 간단한 설명입니다.
  • 리소스 소유자의 이름 및 이메일 주소입니다.
• 버전: 검색어와 일치하는 API 버전 목록입니다. 각 버전에는 다음 세부정보가 제공됩니다.
  • API 세부정보 페이지로 연결되는 링크와 함께 해당 버전의 API 이름이 표시됩니다.
  • 버전 세부정보 페이지로 연결되는 링크와 함께 API 버전 이름이 표시됩니다.
  • 버전 설명 및 관련 메타데이터입니다.
• 사양: 검색어와 일치하는 API 사양 목록입니다. 각 사양에 대해 다음 세부정보가 제공됩니다.
  • API 세부정보 페이지로 연결되는 링크와 함께 해당 사양의 API 이름이 표시됩니다.
  • 해당 사양의 버전 세부정보 페이지로 연결되는 링크와 함께 API 사양의 이름이 표시됩니다.
  • 사양에 대한 설명입니다.
  • 사양 문서에 대한 링크입니다.
  • OpenAPI 사양과 같은 사양 유형입니다.
• 작업: 검색어와 일치하는 API 작업 목록입니다. 각 작업에 대해 다음 세부정보가 제공됩니다.
  • API 세부정보 페이지로 연결되는 링크와 함께 해당 작업과 관련된 API 이름이 표시됩니다.
  • 작업과 연결된 버전 세부정보 페이지로 연결되는 링크와 함께 해당 작업의 이름이 표시됩니다.
  • 사양에 대한 설명입니다.
  • 작업을 정의하는 사양 문서에 대한 링크입니다.
  • 작업이 포함된 버전 링크입니다.
• 배포: 검색어와 일치하는 배포 목록입니다. 각 배포에 대해 다음 세부정보가 제공됩니다.
  • 배포 이름입니다.
  • 배포의 설명입니다.
  • 배포 유형입니다. 예를 들어 Apigee Hybrid입니다.
  • 배포가 포함된 버전에 대한 링크입니다.

특정 검색어가 포함된 API를 검색하려면 다음 안내를 따르세요.

1. Google Cloud 콘솔에서 API 허브 시맨틱 검색 페이지로 이동합니다.

   API 허브로 이동

2. 검색창에 검색어를 입력합니다.

   예를 들어 '주문 관리 API' 또는 '무선 이동통신사 설정을 위한 사양 파일'을 입력할 수 있습니다.

   검색어 프롬프트 내에서 시스템 속성을 사용하여 검색 범위를 좁힐 수 있습니다. API 허브에 API를 등록할 때 사용자 속성을 만든 경우 검색어 프롬프트에 이러한 속성을 포함할 수도 있습니다.

3. 검색 결과는 다음 탭 아래에 API, 버전, 사양, 작업 및 배포와 같이 분류되어 있습니다. 탭 중 하나를 클릭하여 카테고리의 결과를 확인합니다. 결과에는 입력한 검색어와 의미상으로 유사한 용어가 포함된 API 리소스가 표시됩니다.
4. API 리소스 이름을 클릭하여 해당 리소스의 세부정보 페이지를 봅니다.
5. 현재 쿼리를 지우려면 결과 지우기를 클릭합니다.

API를 사용하여 API 허브 검색

API 허브 API를 사용하여 API 허브 리소스를 검색할 수도 있습니다. searchResources 메서드를 사용하면 무료 텍스트 쿼리 및 필터를 사용하여 API 허브 리소스를 쿼리할 수 있습니다.

다음 API 호출을 사용하여 API 허브 리소스를 검색할 수 있습니다.

curl -X POST https://apihub.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION:searchResources \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" \
  -d '{
    "query":"QUERY",
    "filter":"resource_type = RESOURCE_TYPE"
   }'

각 항목의 의미는 다음과 같습니다.

• PROJECT_ID는 API 허브 인스턴스의 호스트 프로젝트 ID입니다.
• LOCATION은 API 허브 인스턴스가 호스팅되는 위치입니다.
• QUERY는 검색에 사용할 자유 텍스트 쿼리입니다. 쿼리에는 표시 이름, 설명 또는 기타 메타데이터를 포함하여 API 허브 리소스의 세부정보와 관련된 키워드가 포함될 수 있습니다.
• RESOURCE_TYPE은 검색에 지정된 선택적 필터입니다. 다음 API 허브 리소스 유형 중 하나를 필터로 지정할 수 있습니다.
  • Api
  • ApiOperation
  • Deployment
  • Definition
  • Spec
  • Version

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

curl -X POST https://apihub.googleapis.com/v1/projects/{project-id}/locations/{location}:searchResources \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" \
  -d '{
    "query":"dog status in the store",
    "filter":"resource_type = SPEC"
    }'

이 호출은 리소스별 메타데이터가 포함된 API 허브 리소스의 페이지로 나눈 목록을 반환합니다.

API 허브 API를 사용한 자유 텍스트 검색에 대한 자세한 내용은 Method:project.locations.searchResources에 대한 API 참고 문서를 확인하세요.

필터 기반 검색 옵션

시스템 속성을 검색 파라미터로 사용하여 API 페이지에 표시되는 API 목록을 세분화할 수 있습니다. 다음 중 하나를 사용하여 표시되는 API 리소스 목록을 맞춤설정합니다.

• 필터
• 페이지 나누기

필터

필터 기반 목록 검색을 사용하면 리소스와 관련된 사전 정의된 여러 매개변수 및 시스템 속성을 기반으로 API 목록을 간소화할 수 있습니다. Match ALL 또는 Match ANY 옵션을 사용하여 필터링된 뷰를 맞춤설정할 수 있습니다.

참고: 관리자 권한이 있는 사용자가 사용 가능한 필터 옵션을 구성합니다. 자세한 내용은 API 허브 설정 관리 및 속성 관리를 참조하세요.

필터 옵션을 지정하려면 다음 안내를 따르세요.

1. Google Cloud 콘솔에서 API 허브 API 페이지로 이동합니다.

   API 허브 API로 이동

2. 테이블 필터링 필드를 클릭하여 테이블을 필터링합니다. 필터 창이 열립니다.
   도움말: API 표에서 열을 표시하거나 숨길 수 있습니다. 필터 행의 작업 메뉴를 사용하여 행 이름을 선택하고 선택 해제합니다.
3. 필터 옵션을 지정하거나 선택합니다. 필터 창에 입력하면 현재 컨텍스트와 관련된 시스템 속성 목록이 포함된 필터 옵션이 있는 메뉴가 표시됩니다. 예를 들어 API 페이지에서 API를 필터링할 때 표시될 수 있는 시스템 속성은 다음과 같습니다.
   • API 이름: API의 표시 이름
   • 사업부: API를 담당하는 사업부
   • 팀: API를 담당하는 프로덕션팀
   • 문서: API 문서에 대한 짧은 링크
   참고: 필터 옵션으로 나열되는 추가 속성이 있을 수 있습니다. 자세한 내용은 API 속성 관리를 참조하세요.

   API, 버전, 사양 표의 필터 목록에 시스템 속성이 표시됩니다.

4. 필터 옵션을 선택한 후 값 목록에서 필터 값을 선택합니다. 또는 선택한 필터 속성의 값을 입력할 수 있습니다.
5. 필터를 추가하려면 테이블 필터 필드를 클릭하여 사용 가능한 연산자 중에서 선택한 후 다른 필터 속성 및 값을 선택합니다.

6. 선택한 필터 속성에는 필터 쿼리가 사용하는 조건부 로직이 표시됩니다. OR을 연산자로 선택할 수 있습니다. 연산자를 선택하지 않으면 기본값은 AND입니다.

7. 개별 필터를 삭제하려면 필터에서 X를 클릭합니다. 모든 필터를 삭제하려면 필터 창에서 모두 지우기를 클릭합니다.

페이지로 나누기

API 리소스가 여러 개인 경우 여러 페이지에 표시될 수 있습니다.

목록 표시 및 페이지 탐색을 맞춤설정하려면 다음 안내를 따르세요.

1. Google Cloud 콘솔에서 API 허브 API 페이지로 이동합니다.

   API 허브 API로 이동

   기본적으로 API 목록 페이지가 표시됩니다.

2. API 목록에서 그림 2와 같이 페이지로 나누기 도구를 찾습니다.

   

   그림 2. 페이지로 나뉜 결과를 앞뒤로 이동합니다.

3. 페이지당 표시할 API 수를 선택합니다.
4. > 앞으로를 클릭하여 다음 페이지로 이동합니다.
5. < 뒤로를 클릭하여 이전 페이지로 이동합니다.

다음 단계

• 배포 관리 방법 알아보기