속성 관리

이 페이지는 Apigee 및 Apigee 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

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

Google Cloud 콘솔에서 API 허브 > 설정 페이지로 이동합니다.
그러면 속성 탭의 시스템 속성 섹션에 모든 기존 시스템 속성이 표시됩니다.
값을 추가하려는 속성에서 수정을 클릭합니다.
그러면 속성 수정 창이 열리고 기존 속성 값이 표시됩니다.
새 값을 추가하려면 값 추가를 클릭한 다음 추가할 새 값을 입력합니다.
참고: 기존 값을 삭제하려면 삭제할 값에서 삭제를 클릭합니다. Delete 옵션은 변경 가능한 값에만 표시됩니다. 따라서 값에 삭제 옵션이 표시되지 않으면 해당 값을 변경할 수 없음을 유추할 수 있습니다.
저장을 클릭합니다.

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

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

Google Cloud 콘솔에서 API 허브 > 설정 페이지로 이동합니다.
그러면 속성 탭의 사용자 속성 섹션에 모든 사용자 속성이 표시됩니다.
속성 추가를 클릭합니다.
그러면 새 속성 추가 창이 열립니다.
다음 세부정보를 입력합니다.
- ID: 속성의 고유 식별자를 입력합니다.
  - 필드를 비워 두면 API 허브에서 자동으로 고유 ID를 생성합니다.
  - 값을 직접 입력하려면 값이 모든 속성에서 고유한지 확인합니다.
- 이름: 속성의 이름을 입력합니다.
- 설명: 필요한 경우 속성 설명을 입력합니다.
- 카디널리티: 1~20 사이의 숫자를 입력합니다. 카디널리티는 속성이 가질 수 있는 값의 최대 개수를 지정합니다.
- 리소스 유형: 리소스 유형을 선택합니다.
새 값을 추가하려면 값 추가를 클릭한 다음 추가할 새 값을 입력합니다.
참고: 기존 값을 삭제하려면 삭제할 값에서 삭제를 클릭합니다.
저장을 클릭합니다.

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

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

Google Cloud 콘솔에서 API 허브 > 설정 페이지로 이동합니다.
그러면 속성 탭의 사용자 속성 섹션에 기존 사용자 속성이 모두 표시됩니다.
수정하려는 속성에서 수정을 클릭합니다.
그러면 속성 수정 창이 열리고 기존 속성 값이 표시됩니다.
- 속성 이름을 업데이트하려면 이름 필드에 새 이름을 입력합니다.
- 새 값을 추가하려면 값 추가를 클릭한 다음 추가할 새 값을 입력합니다.
- 기존 값을 삭제하려면 삭제할 값에서 삭제를 클릭합니다.
저장을 클릭합니다.

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 허브는 속성에 새 값을 추가합니다.