API 탐색기 사용

이 가이드에서는 API 탐색기를 사용하여 Monitoring API 메서드를 사용해 보는 방법을 설명합니다. API 탐색기는 메서드의 REST API 참조 페이지에 연결된 위젯입니다. API 사용해 보기라는 제목의 패널로 표시됩니다. 다음 스크린샷은 하나의 매개변수인 name이 있는 메서드에 표시되는 패널을 보여줍니다.

API 탐색기 위젯

API 탐색기는 코드를 작성할 필요 없이 Monitoring API에서 메서드를 사용해 볼 수 있는 좋은 방법입니다. 위젯은 각 메서드의 매개변수를 보여주는 양식을 제공합니다. 양식을 작성하고 실행 버튼을 클릭한 다음 결과를 확인합니다.

또한 패널 상단에 있는 버튼을 클릭하여 위젯을 숨기거나 버튼을 클릭하여 위젯을 전체 화면으로 펼칠 수도 있습니다.

사용해 보기 버튼

문서를 통해 다음 예시와 같은 사용해 보기 버튼이 표시됩니다.

사용해 보기

버튼을 클릭하면 적절한 참조 페이지에 API 탐색기가 나타나고 예시에 따라 필드가 채워집니다. [PROJECT_ID] 값과 같이 자신의 프로젝트와 일치하도록 일부 필드를 수정해야 합니다.

오류 방지 및 수정에 대한 자세한 내용은 도움말을 참조하세요.

API 탐색기에 액세스

API 탐색기는 각 REST API 메서드의 참조 페이지에 연결됩니다. 위젯을 찾으려면 메서드의 참조 페이지(예: monitoring.projects.metricDescriptors.list의 참조 페이지)로 이동합니다.

최소 요청 실행

대부분의 메서드에는 필수 매개변수와 일부 선택 매개변수가 있습니다. 필수 매개변수는 채워질 때까지 빨간색 막대로 표시됩니다. 필수 인수만 제공하여 최소 요청을 실행할 수 있습니다.

metricDescriptors.list 메서드는 프로젝트에서 사용 가능한 모든 측정항목 유형의 설명자를 반환합니다. 유일한 필수 입력란은 name 필드입니다. 프로젝트의 이 목록을 검색하려면 nameprojects/[PROJECT_ID] 형식을 사용하여 프로젝트 이름을 제공합니다.

아래 버튼을 클릭하여 사용해 보세요. 양식에서 실행 버튼을 클릭하기 전에 [PROJECT_ID]를 프로젝트의 식별자로 변경해야 합니다.

사용해 보기

메서드 호출 결과는 실행 버튼 아래의 상자에 표시됩니다. 일반적으로 상자에는 HTTP 상태 코드 200가 포함된 녹색 헤더가 있으며, 이는 요청이 성공했음을 나타냅니다. 호출 결과는 상자에 있습니다.

성공적인 메서드 호출의 결과입니다.

헤더가 빨간색이고 헤더에 HTTP 실패 코드가 포함된 경우 상자에 오류 메시지가 포함됩니다. 오류 해결에 대한 몇 가지 도움말은 도움말을 참조하세요.

추가 매개변수 제공

표시되는 매개변수 목록은 API 탐색기 위젯이 연결된 메서드에 따라 다릅니다. metricDescriptors.list 메서드에는 name 매개변수 외에도 여러 가지가 있지만 name은 필수 매개변수입니다.

프로젝트 이름만 제공하면 프로젝트에서 사용할 수 있는 모든 측정항목 설명이 제공되며 많은 설명이 있습니다. 선택 사항인 filter 매개변수를 사용하여 검색을 더 작은 세트로 제한할 수 있습니다.

예를 들어 metricsDescriptor.list 페이지의 다음 필드를 채웁니다. [PROJECT_ID]만 프로젝트 ID로 대체하고 다른 값은 다음과 같이 제공합니다.

  • 이름: projects/[PROJECT_ID]
  • 필터: metric.type=ends_with("utilization")

이 요청을 실행하면 이름이 utilization으로 끝나는 측정항목 유형의 설명만 반환됩니다.

사용해 보기

fields(필드)를 사용하여 추가 출력 제한

기본적으로 API 탐색기에 표시되는 매개변수 집합은 연결된 메서드의 매개변수에 해당합니다. 하지만 API 탐색기 위젯에는 메서드 자체를 통해 사용할 수 없는 추가 필드 집합도 있습니다.

이러한 매개변수는 인증 섹션 위에 표시되는 표준 매개변수 표시 전환 아래에 숨겨져 있습니다.

'표준 매개변수 표시' 전환

이 전환을 클릭하여 추가 위젯 매개변수를 노출합니다. 표준 매개변수 숨기기를 클릭하여 보기에서 숨깁니다.

이러한 표준 매개변수의 가장 유용한 방법은 fields 매개변수입니다. 이 매개변수를 사용하면 반환된 출력의 필드를 선택할 수 있습니다. 이는 상자에 출력이 표시되는 API 탐색기 패널에서 매우 유용합니다. 스크롤해야 할 출력은 종종 많습니다.

예를 들어 utilization으로 끝나는 측정항목의 설명을 나열하면 많은 정보가 반환됩니다. 측정항목 유형의 이름과 설명에만 관심이 있다면 fields 필드를 사용하여 해당 필드만 지정할 수 있습니다.

차이를 확인하려면 metricsDescriptor.list 페이지에서 다음 필드를 채웁니다. [PROJECT_ID]만 프로젝트 ID로 대체하고 다른 값은 다음과 같이 제공합니다.

  • name, 이전과 동일: projects/[PROJECT_ID]
  • filter, 이전과 동일: metric.type=ends_with("utilization")
  • 필드: metricDescriptors.type,metricDescriptors.description

이 요청을 실행하면 각 측정 항목의 type(닉네임)과 description만 반환됩니다. 다음은 출력의 일부입니다.

사용해 보기

[PROJECT_ID] 반드시 변경

[PROJECT_ID]를 프로젝트 ID로 바꿔야 합니다. 잊어버린 경우, 다음과 같은 결과를 얻게 됩니다.

PROJECT_ID를 변경하지 않을 때 표시되는 오류 메시지

값 관련 문제

다음은 API 탐색기 양식을 사용할 때 주의해야 할 사항입니다. 이러한 실수로 인해 오류가 발생하거나 수락될 수 있지만 API 메서드에서 철자 오류로 처리될 수 있습니다.

  • 어떠한 유형의 필드 값도 따옴표로 묶지 않습니다.
  • 필터 안에 표시되는 문자열을 따옴표로 묶어야 합니다. 큰 따옴표(")를 사용하고 아포스트로피(')는 사용하지 마세요. 예시는 추가 매개변수 제공을 참조하세요.
  • 양식 필드에 백슬래시 또는 URL 인코딩을 사용하지 마세요. 필요한 경우 메서드를 실행할 때 필드 값에 대해 URL 인코딩이 수행됩니다.
  • 호출을 실행한 후 결과 상자의 값을 확인합니다. 문제가 있을 수 있습니다.
  • pageSize 필드의 값(예: 2)을 제공할 수 있습니다. 이렇게 하면 API 호출을 디버그할 때 반환되는 데이터 양이 제한됩니다.

디버깅을 위한 URL 북마크

원하는 출력을 얻으면 API 탐색기 URL을 북마크에 저장합니다. 이 메서드를 다시 실행하려는 경우 브라우저에 이 URL을 붙여넣습니다. 값이 이미 채워진 양식이 표시됩니다. 매개변수를 필요한 대로 변경하고 실행을 클릭하여 메서드를 다시 실행합니다.

인증

API 탐색기 페이지의 실행 버튼 위에 인증 섹션이 있습니다. 일반적으로 여기에서 아무것도 변경할 필요가 없습니다.

기본 인증 메커니즘은 Google OAuth 2.0입니다.

인증 섹션에 범위 표시 전환도 있습니다. 이를 사용하면 사용 가능한 Compute Engine 범위가 표시되며, 기본적으로 사용 가능한 모든 범위가 사용 설정됩니다.

이러한 개념에 대한 자세한 내용은 액세스 제어를 참조하세요.

문제해결

문제가 계속되면 Monitoring API 문제해결을 참조하세요.