API 탐색기 사용

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

API 탐색기 위젯입니다.

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

또한 버튼을 클릭하여 위젯을 숨기거나 버튼을 클릭하여 위젯을 전체 화면으로 확장할 수 있습니다.

사용해 보기 버튼

문서에 다음과 같은 사용해 보기 버튼이 표시될 수 있습니다.

사용해 보기

버튼을 클릭하면 메서드 참조 페이지에서 API 탐색기가 열립니다. 일반적으로 예시에 적합한 일부 매개변수가 채워집니다. 하지만 [PROJECT_ID] 값과 같이 고유 프로젝트와 일치하도록 일부 매개변수를 수정해야 할 수 있습니다.

오류 방지 및 수정에 대한 자세한 내용은 문제 해결을 참조하세요.

API 탐색기 액세스

API 탐색기는 각 REST API 메서드의 참조 페이지에 연결됩니다. 위젯을 찾으려면 메서드의 참조 페이지를 확인합니다. 예를 들어 metricDescriptors.list를 참조하세요.

요청 실행

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

metricDescriptors.list 메서드는 프로젝트에서 모든 사용 가능한 측정항목 유형에 대한 설명자를 반환합니다. 유일한 필수 매개변수는 name 매개변수입니다.

metricDescriptors.list 메서드를 실행하려면 다음을 수행합니다.

  1. 사용해 보기를 클릭합니다.
  2. name 매개변수에서 projects/[PROJECT_ID] 형식을 사용하여 프로젝트 ID를 입력합니다. [PROJECT_ID]를 프로젝트 ID로 바꿉니다.
  3. 실행을 클릭합니다. 명령어를 실행하려면 API 탐색기가 계정에 액세스할 수 있어야 합니다. 프롬프트가 표시되면 계정을 선택하고 허용을 클릭합니다. 액세스 권한은 제한된 기간 동안 사용되고 실행 중인 API 메서드로 제한됩니다.

메서드 호출의 결과가 녹색 또는 빨간색 헤더 상자에 표시됩니다. 요청이 성공하면 상자가 녹색 헤더로 표시되고 그 안에 HTTP 상태 코드 200이 포함됩니다. 호출 결과는 상자에 있습니다.

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

헤더가 빨간색이면 HTTP 오류 코드가 포함되고, 상자에 오류 메시지가 있습니다. 오류 해결에 대한 자세한 내용은 문제 해결을 참조하세요.

추가 매개변수 제공

표시되는 매개변수 목록은 API 탐색기 위젯이 연결된 메서드에 따라 다릅니다. 예를 들어 metricDescriptors.list 메서드에 name 매개변수 이상이 포함되지만, name이 유일한 필수 매개변수입니다.

프로젝트 이름만 제공하면 프로젝트에서 사용할 수 있는 모든 측정항목 설명이 제공되며 많은 설명이 있습니다. 검색을 작은 집합으로 제한하려면 필터 매개변수를 사용합니다.

예를 들어 이름이 utilization으로 끝나는 측정항목 유형만 나열하려면 다음을 수행합니다.

  1. 사용해 보기를 클릭합니다.

  2. name 매개변수에서 projects/[PROJECT_ID] 형식을 사용하여 프로젝트 ID를 입력합니다. [PROJECT_ID]를 프로젝트 ID로 바꿉니다.

  3. filter 매개변수의 값이 metric.type=ends_with("utilization")인지 확인합니다.

  4. 실행을 클릭하고 승인 대화상자를 완료합니다.

표준 매개변수

기본적으로 API 탐색기에 표시되는 매개변수 집합은 연결된 메서드의 매개변수에 해당합니다. 하지만 API 탐색기 위젯에는 메서드 자체에 포함되지 않는 추가 매개변수 집합도 포함됩니다. 추가 매개변수를 표시하려면 표준 매개변수 표시를 클릭합니다.

표준 매개변수 전환을 표시합니다.

화면에서 추가 매개변수를 숨기려면 표준 매개변수 숨기기를 클릭합니다.

가장 유용한 표준 매개변수는 fields 매개변수입니다. 이 매개변수를 사용하면 반환된 출력에서 확인하려는 필드를 선택할 수 있습니다.

예를 들어 utilization으로 끝나는 측정항목의 설명자를 나열하면 아직 많은 결과가 반환됩니다. 측정항목 유형의 이름과 설명만 확인하려면 fields 매개변수를 사용하여 이 제한을 지정할 수 있습니다.

fields 매개변수 설정 결과를 확인하려면 다음을 수행합니다.

  1. 사용해 보기를 클릭합니다.

  2. name 매개변수에서 projects/[PROJECT_ID] 형식을 사용하여 프로젝트 ID를 입력합니다. [PROJECT_ID]를 프로젝트 ID로 바꿉니다.

  3. filter 매개변수의 값이 metric.type=ends_with("utilization")인지 확인합니다.

  4. 표준 매개변수 표시를 클릭하고 fields 매개변수의 값이 metricDescriptors.type,metricDescriptors.description인지 확인합니다.

  5. 실행을 클릭하고 승인 대화상자를 완료합니다.

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

문제 해결

이 섹션에서는 API 탐색기를 사용할 때의 일반적인 문제에 대해 설명합니다.

Cloud Monitoring API 사용에 대한 자세한 내용은 Cloud Monitoring API 문제 해결을 참조하세요.

잘못된 필터 구문

여러 줄로 된 표현식을 복사하여 API 탐색기에 표시된 필드에 붙여넣으면 API 탐색기에 오류 메시지가 표시됩니다.

해야 할 일: 문자열이 한 줄에 있는지 확인합니다.

"query": "fetch gce_instance::compute.googleapis.com/instance/disk/read_bytes_count | within 5m"

하지 말아야 할 일: 줄 연속 또는 줄 바꿈 문자를 복사하여 붙여넣습니다.

예를 들어 timeSeries.query 메서드에 다음을 추가하면 API 탐색기에 Select an underlined section to see more details 오류 메시지가 표시됩니다.

"query": "fetch gce_instance::compute.googleapis.com/instance/disk/read_bytes_count
          | within 5m"

잘못된 프로젝트 식별자

프로젝트 식별자가 잘못된 경우 API 요청이 HTTP 오류 400과 함께 실패합니다.

이 문제를 해결하려면 [PROJECT_ID] 텍스트가 프로젝트 ID로 대체되었는지 확인합니다.

잘못된 양식 값

API 요청이 실패하거나 예기치 않은 값을 반환하는 경우 모든 양식 매개변수를 확인합니다.

API 탐색기 매개변수에는 특정 형식이 필요합니다. 형식 지정 실수로 인해 오류가 발생하거나 수락되더라도 API 메서드에서 철자 오류 등으로 취급될 수 있습니다.

  • 어떠한 유형의 매개변수 값도 따옴표로 묶지 않습니다.

  • 하위 문자열을 보호해야 하는 경우를 제외하고 백슬래시를 사용하지 않습니다.

    예를 들어 다음은 개별 양식 매개변수를 완성하는 대신 JSON으로 콘텐츠를 입력하는 API 메서드의 샘플입니다. filter 값이 문자열이므로 하위 문자열 k8s_cluster는 백슬래시로 보호됩니다.

    {
      "resourceNames": [...],
      "filter": "resource.type = \"k8s_cluster\""
    }
  • 필터 안에 표시되는 문자열을 따옴표로 묶습니다. 아포스트로피(') 대신 큰 따옴표(")를 사용합니다. 예시를 보려면 추가 매개변수 제공을 참조하세요.
  • 양식에 URL 인코딩을 사용하지 않습니다. API 메서드에 URL 인코딩이 필요한 경우 메서드를 실행할 때 위젯이 변환을 수행합니다.

너무 많은 데이터가 반환됨

반환되는 결과 수를 제한하려면 pageSize 매개변수에 2와 같은 값을 입력합니다. pageSize 매개변수는 반환된 결과의 최대 개수를 정의하며 대부분의 API 메서드에 사용 가능합니다.

특정 필드를 반환하도록 선택하려면 fields 매개변수를 사용합니다. 자세한 내용은 표준 매개변수를 사용합니다.

인증

API 탐색기 페이지에 사용자 인증 정보 섹션이 있습니다. 이러한 필드는 기본값으로 두는 것이 좋습니다. 기본 인증 메커니즘은 Google OAuth 2.0입니다.

메서드에 필요한 API 범위를 확인하려면 범위 표시를 클릭합니다. 기본적으로 필요한 모든 범위가 부여됩니다.

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