属性を管理する

このページの内容は Apigee と Apigee ハイブリッドに適用されます。

概要

属性は、リソースのメタデータと考えることができます。たとえば API リソースの場合は、その API が公開、限定公開、内部使用のいずれを目的としているかを指定する Target Users という属性が存在する可能性があります。この他にも多くの種類の属性があります。

属性は次のような用途に役立ちます。

リソースの検索結果を属性に基づいてフィルタできます。そのため、属性が多いほど、検索結果の絞り込みが容易になります。
カスタム属性を作成して API Hub リソースに関連付けることができます。

API Hub では、属性が Key-Value 形式で保存されます。Key は属性の名前、Value は属性の対応する値です。値は次のいずれかの形式にすることができます。

文字列
列挙型
JSON

属性には次の 2 種類があります。

システム属性（API Hub で事前定義されている）。
ユーザー属性（ユーザーが定義）。

システム属性

システム属性は、リソースタイプごとに API Hub によって事前定義されています。そのような属性のリストと値の定義は、API Hub のリリースごとに変更される可能性があります。システム属性の例としては、ライフサイクルステージ、API コンプライアンス、API 認定、SLO などがあります。これらの属性は、リソースに対して必須または省略可能になる場合があります。リソースに属性が必須である場合は、リソースを登録するときに属性の値を設定する必要があります。

Enum 型のシステム属性の値は、不変または可変にすることができます。

不変 - 既存の値を変更することはできません。ただし、新しい可変値を属性に追加することは可能です。たとえば、oas-version 属性の値は 2.1、3.0、3.1 になります。これらの値を更新することはできませんが、新しいカスタム値の追加は可能です。
可変 - 既存の値を追加、編集、削除できます。たとえば、lifecycle-stage 属性には、最初は Dev、Stage、UAT、Prod などの値を設定できます。既存の値を編集することも、新しい値を追加することも可能です。

システム属性を表示する

コンソール

すべてのシステム属性を表示するには、Google Cloud コンソールで [API Hub] > [設定] ページに移動します。既存のシステム属性はすべて [System attributes] タブで確認できます。

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

列挙型のシステム属性を編集する

可変値に対しては、次の操作を行うことができます。

新しい値を追加する
既存の値を更新する
既存の属性値を削除する

このセクションの例では、列挙型のシステム属性の許容値を更新する方法を示しています。

コンソール

システム属性の値を追加する手順は次のとおりです。

Google Cloud コンソールで、[API Hub] > [設定] ページに移動します。
[属性] タブの [System attributes] セクションに、既存のシステム属性がすべて表示されます。
値を追加する属性の [編集] をクリックします。
属性の編集ペインが開き、既存の属性値が表示されます。
新しい値を追加するには、[項目を追加] をクリックして、追加する新しい値を入力します。
注: 既存の値を削除するには、削除する値の [削除] をクリックします。Delete オプションは、可変な値に対してのみ表示されます。したがって、値に削除オプションが表示されない場合、その値は不変である可能性があります。
[保存] をクリックします。

REST API

列挙型のシステム定義属性の許可値を更新するには、次の 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 Hub が UpdateAttribute API のリクエストペイロードをどのように解釈するかを理解することが重要です。

ペイロードで指定した値がすでに存在する場合、API Hub はペイロードで値が更新されたかどうかを確認し、更新された場合は値を上書きします。
ペイロードで値が使用できない場合、API Hub は値を削除する必要があると判断し、API Hub から値を削除します。
ペイロードで新しい値が使用可能な場合、API Hub はその値を属性に追加します。

ユーザー定義の属性

ユーザー定義の属性は、要件に基づいて定義します。

ユーザー定義の属性を表示する

コンソール

すべてのユーザー属性を表示するには、Google Cloud コンソールで [API Hub] > [設定] ページに移動します。[属性] タブの [ユーザー定義の属性] セクションで、すべてのユーザー属性を確認できます。

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

新しいユーザー属性を追加する

コンソール

新しいユーザー属性を追加する手順は次のとおりです。

Google Cloud コンソールで、[API Hub] > [設定] ページに移動します。
[属性] タブの [ユーザー属性] セクションにすべてのユーザー属性が表示されます。
[属性を作成] をクリックします。
[新しい属性を追加する] ペインが開きます。
次の詳細情報を入力します。
- ID: 属性の固有識別子を入力します。
  - このフィールドを空のままにすると、API Hub によって一意の 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

ユーザー属性を編集する

ユーザー属性に対しては、次の編集を行うことができます。

属性名を更新する
新しい属性値を追加する
既存の属性値を削除する

コンソール

ユーザー属性を編集する手順は次のとおりです。

Google Cloud コンソールで、[API Hub] > [設定] ページに移動します。
既存のユーザー属性がすべて [属性] タブの [ユーザー属性] セクションに表示されます。
編集する属性の [編集] をクリックします。
属性の編集ペインが開き、既存の属性値が表示されます。
名前、説明、最大許容値を編集できます。列挙型の場合は、新しい値を追加できます。列挙型に新しい値を追加するには、[項目を追加] をクリックして、追加する新しい値を入力します。
[保存] をクリックします。

REST API

ユーザー属性を編集するには、次の API に PATCH リクエストを送信します。

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

API の詳細については、UpdateAttribute をご覧ください。

次の例は、API 呼び出しで API Visibility ユーザー属性を更新する例です。

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 Hub が UpdateAttribute API のリクエストペイロードをどのように解釈するかを理解することが重要です。

ペイロードで指定した値がすでに存在する場合、API Hub はペイロードで値が更新されたかどうかを確認し、更新された場合は値を上書きします。
ペイロードで値が使用できない場合、API Hub は値を削除する必要があると判断し、API Hub から値を削除します。
ペイロードで新しい値が使用可能な場合、API Hub はその値を属性に追加します。