속성 관리

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

개요

속성은 리소스의 메타데이터라고 생각하면 됩니다. 예를 들어 API 리소스의 경우 API가 공개, 비공개 또는 내부 소비 대상인지를 지정하는 Target Users라는 속성을 가질 수 있습니다.

속성은 다음과 같은 점에서 유용합니다.

  • 속성을 기준으로 리소스 검색결과를 필터링할 수 있습니다. 따라서 속성이 많을수록 검색결과 범위를 쉽게 좁힐 수 있습니다.
  • 커스텀 데이터를 API 허브 리소스에 연결할 수 있습니다.

API 허브는 키-값 형식으로 속성을 저장합니다. 여기서 키는 속성의 이름이고 값은 속성에 해당하는 값입니다. 이 값은 다음 형식 중 하나일 수 있습니다.

  • 문자열
  • Enum
  • JSON

속성은 다음 두 가지 유형일 수 있습니다.

  • API 허브에서 사전 정의되는 시스템 속성
  • 사용자가 정의한 사용자 속성

시스템 속성

시스템 속성은 각 리소스 유형에 대해 API 허브에서 사전 정의됩니다. 이러한 속성 목록과 해당 값 정의는 API 허브의 출시 버전별로 다를 수 있습니다. 시스템 속성의 예시는 수명 주기 단계, API 규정 준수, API 인증, SLO 등이 있습니다. 이러한 속성은 리소스에 대해 필수 또는 선택사항일 수 있습니다. 속성이 리소스에 대해 필수인 경우 리소스를 등록할 때 속성 값을 설정해야 합니다.

Enum 유형 시스템 속성의 값은 변경 불가 또는 변경 가능할 수 있습니다.

  • 변경 불가 - 기존 값을 변경할 수 없습니다. 하지만 속성에 새로운 변경 가능 값을 추가할 수 있습니다. 예를 들어 oas-version 속성은 값이 2.1, 3.0, 3.1입니다. 이러한 값은 업데이트할 수 없지만 새 커스텀 값을 추가할 수 있습니다.
  • 변경 가능 - 기존 값을 추가, 수정 또는 삭제할 수 있습니다. 예를 들어 lifecycle-stage 속성은 처음에 Dev, Stage, UAT, Prod 등의 값을 가질 수 있습니다. 이러한 기존 값을 수정하고 새 값을 추가할 수 있습니다.

시스템 속성 보기

Console

모든 시스템 속성을 보려면 Google Cloud 콘솔에서 API 허브 > 설정 페이지로 이동합니다. 시스템 속성 탭에서 모든 기존 시스템 속성을 볼 수 있습니다.

REST API

리소스의 모든 시스템 속성을 보려면 다음 API에 GET 요청을 실행합니다.

https://apihub.googleapis.com/v1/projects/PROJECT/locations/LOCATION/attributes

API에 대한 자세한 내용은 ListAttributes를 참조하세요.

다음 예시에서는 모든 리소스의 시스템 속성을 가져오기 위한 API 호출을 보여줍니다.

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-type: application/json" \
-X GET \
https://apihub.googleapis.com/v1/projects/test-project-1/locations/us-central1/attributes?filter=definition_type=SYSTEM_DEFINED

Enum 유형의 시스템 속성 수정

변경 가능 값에 다음 작업을 수행할 수 있습니다.

  • 새 값 추가
  • 기존 값 업데이트
  • 기존 속성 값 삭제

이 섹션의 예시에서는 Enum 유형의 시스템 속성에 허용되는 값을 업데이트하는 방법을 보여줍니다.

Console

시스템 속성 값을 추가하려면 다음 단계를 수행합니다.

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

    그러면 속성 탭의 시스템 속성 섹션에 모든 기존 시스템 속성이 표시됩니다.

  2. 값을 추가하려는 속성에서 수정을 클릭합니다.

    그러면 속성 수정 창이 열리고 기존 속성 값이 표시됩니다.

  3. 새 값을 추가하려면 값 추가를 클릭한 다음 추가할 새 값을 입력합니다.
  4. 저장을 클릭합니다.

REST API

Enum 데이터 유형의 시스템 정의 속성에 허용되는 값을 업데이트하려면 다음 API에 PATCH 요청을 실행합니다.

https://apihub.googleapis.com/v1/projects/PROJECT/locations/LOCATION/attributes/ATTRIBUTE

API에 대한 자세한 내용은 UpdateAttribute를 참조하세요.

다음 예시에서는 Business unit 속성 값을 업데이트하기 위한 API 호출을 보여줍니다.

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d '{"allowed_values": [
{
"id": "bu1",
"display_name": "Business unit 1",
"description": "The API can be used by business unit 1"
},
{
"id": "bu2",
"display_name": "Business unit 2",
"description": "The API can be used by business unit 2"
},
{
"id": "bu3",
"display_name": "Business unit 3",
"description": "The API can be used by business unit 3"
}]}' \
-X PATCH https://apihub.googleapis.com/v1/projects/test-15/locations/us-central1/attributes/system-business-unit?update_mask=allowed_values 

API 허브가 UpdateAttribute API의 요청 페이로드를 해석하는 방법을 이해하는 것이 중요합니다.

  • 페이로드에 지정한 값이 이미 존재하는 경우 API 허브는 값이 페이로드에서 업데이트되었는지 확인한 다음 값이 업데이트되면 해당 값을 덮어씁니다.
  • 페이로드에서 값을 사용할 수 없는 경우 API 허브는 해당 값을 삭제해야 한다고 해석하고 API 허브에서 값을 삭제합니다.
  • 페이로드에서 새 값을 사용할 수 있는 경우 API 허브는 속성에 새 값을 추가합니다.

사용자 속성

사용자 속성은 요구사항에 따라 사용자가 정의합니다.

사용자 속성 보기

Console

모든 사용자 속성을 보려면 Google Cloud 콘솔에서 API 허브 > 설정 페이지로 이동합니다. 속성 탭의 사용자 속성 섹션에서 모든 사용자 속성을 볼 수 있습니다.

REST API

리소스의 모든 사용자 속성을 보려면 다음 API에 GET 요청을 실행합니다.

https://apihub.googleapis.com/v1/projects/PROJECT/locations/LOCATION/attributes

API에 대한 자세한 내용은 ListAttributes를 참조하세요.

다음 예시에서는 API 리소스의 사용자 속성을 가져오기 위한 API 호출을 보여줍니다.

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-type: application/json" \
-X GET \
https://apihub.googleapis.com/v1/projects/test-project-1/locations/us-central1/attributes?filter=definition_type=USER_DEFINED

새 사용자 속성 추가

Console

새 사용자 속성을 추가하려면 다음 단계를 따르세요.

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

    그러면 속성 탭의 사용자 속성 섹션에 모든 사용자 속성이 표시됩니다.

  2. 속성 추가를 클릭합니다.

    그러면 새 속성 추가 창이 열립니다.

  3. 다음 세부정보를 입력합니다.
    • ID: 속성의 고유 식별자를 입력합니다.
      • 필드를 비워 두면 API 허브에서 자동으로 고유 ID를 생성합니다.
      • 값을 직접 입력하려면 값이 모든 속성에서 고유한지 확인합니다.
    • 이름: 속성의 이름을 입력합니다.
    • 설명: 필요한 경우 속성 설명을 입력합니다.
    • 카디널리티: 1~20 사이의 숫자를 입력합니다. 카디널리티는 속성이 가질 수 있는 값의 최대 개수를 지정합니다.
    • 리소스 유형: 리소스 유형을 선택합니다.
  4. 새 값을 추가하려면 값 추가를 클릭한 다음 추가할 새 값을 입력합니다.
  5. 저장을 클릭합니다.

REST API

새 사용자 속성을 추가하려면 다음 API에 POST 요청을 수행합니다.

https://apihub.googleapis.com/v1/projects/PROJECT/locations/LOCATION/attributes?attribute_id=NEW_ATTRIBUTE_NAME

API에 대한 자세한 내용은 CreateAttribute를 참조하세요.

다음 예시에서는 attribute-01 사용자 속성을 생성하기 위한 API 호출을 보여줍니다.

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json"  \
-d '{
"display_name" : "custom attribute",
"description" : "custom attribute details",
"definition_type" : "USER_DEFINED",
"scope" : "API",
"data_type" : "ENUM",
"allowed_values" : [
{
"id" : "value-1",
"display_name" : "Value 1",
"description" : "Value 1 test description",
"immutable" : false,
},
{
"id" : "value-2",
"display_name" : "Value 2",
"description" : "Value 2 test description",
"immutable" : false,
},
],
"cardinality" : 4,
"mandatory" : false
}' \
-X POST  https://apihub.googleapis.com/v1/projects/test-15/locations/us-central1/attributes?attribute_id=attribute-01

사용자 속성 수정

사용자 속성을 다음과 같이 수정할 수 있습니다.

  • 속성 이름 업데이트
  • 새 속성 값 추가
  • 기존 속성 값 삭제

Console

사용자 속성을 수정하려면 다음 단계를 수행합니다.

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

    그러면 속성 탭의 사용자 속성 섹션에 기존 사용자 속성이 모두 표시됩니다.

  2. 수정하려는 속성에서 수정을 클릭합니다.

    그러면 속성 수정 창이 열리고 기존 속성 값이 표시됩니다.

    • 속성 이름을 업데이트하려면 이름 필드에 새 이름을 입력합니다.
    • 새 값을 추가하려면 값 추가를 클릭한 다음 추가할 새 값을 입력합니다.
    • 기존 값을 삭제하려면 삭제할 값에서 삭제를 클릭합니다.
  3. 저장을 클릭합니다.

REST API

사용자 속성을 수정하려면 다음 API에 PATCH 요청을 수행합니다.

https://apihub.googleapis.com/v1/projects/PROJECT/locations/LOCATION/attributes/ATTRIBUTE

API에 대한 자세한 내용은 UpdateAttribute를 참조하세요.

다음 예시에서는 API Visibility 사용자 속성을 업데이트하기 위한 API 호출을 보여줍니다.

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{"name": "projects/test-15/locations/us-central1/attributes/API Visibility",
    display_name" : "API Visibility Updated", "allowedValues": [
    {
    "id": "internal",
    "displayName": "Internal",
    "description": "The API is visible internally in an organization"
    },
    {
    "id": "external",
    "displayName": "External",
    "description": "The API is visible externally in an organization"
    },
    {
    "id": "public",
    "displayName": "Public",
    "description": "The API is visible public in an organization"
    }
    ]}' \
    -X PATCH https://autopush-apihub.sandbox.googleapis.com/v1/projects/common-dev-15/locations/us-central1/attributes/API Visibility?update_mask=display_name,allowed_values
    

API 허브가 UpdateAttribute API의 요청 페이로드를 해석하는 방법을 이해하는 것이 중요합니다.

  • 페이로드에 지정한 값이 이미 존재하는 경우 API 허브는 값이 페이로드에서 업데이트되었는지 확인한 다음 값이 업데이트되면 해당 값을 덮어씁니다.
  • 페이로드에서 값을 사용할 수 없는 경우 API 허브는 해당 값을 삭제해야 한다고 해석하고 API 허브에서 값을 삭제합니다.
  • 페이로드에서 새 값을 사용할 수 있는 경우 API 허브는 속성에 새 값을 추가합니다.