このページの内容は Apigee と Apigee ハイブリッドに適用されます。
概要
属性は、リソースのメタデータと考えることができます。たとえば、API リソースの場合、API には Target Users
という属性があり、API が公開、限定公開、内部使用のいずれを目的としているか指定できます。他にも多くの属性が使用できます。
属性は次のような場合に役立ちます。
- リソースの検索結果を属性に基づいてフィルタできます。属性を増やすと、検索結果の絞り込みが容易になります。
- カスタム属性を作成して 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] セクションに、既存のシステム属性がすべて表示されます。
- 値を追加する属性の [編集] をクリックします。
属性の編集ペインが開き、既存の属性値が表示されます。
- 新しい値を追加するには、[項目を追加] をクリックして、追加する新しい値を入力します。
- [保存] をクリックします。
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 はその値を属性に追加します。
ユーザー定義の属性
ユーザー定義の属性は、要件に基づいて定義します。
ユーザー定義の属性を表示する
Console
すべてのユーザー属性を表示するには、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] > [設定] ページに移動します。
[属性] タブの [ユーザー属性] セクションにすべてのユーザー属性が表示されます。
- [属性を作成] をクリックします。
[Add a new attribute] ペインが開きます。
- 次の詳細情報を入力します。
- ID: 属性の固有識別子を入力します。
- このフィールドを空のままにすると、API Hub によって一意の ID が自動的に生成されます。
- 手動で値を入力する場合は、すべての属性で値が一意であることを確認してください。
- 名前: 属性の名前を入力します。
- 説明: 必要に応じて、属性の説明を入力します。
- 最大許容値: 1 ~ 20 の数値を入力します。この設定では、属性に設定できる値の最大数を指定します。
- リソースの種類: リソースの種類を選択します。
- ID: 属性の固有識別子を入力します。
- 列挙型の新しい値を追加するには、[項目を追加] をクリックして、追加する新しい値を入力します。
- [保存] をクリックします。
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 はその値を属性に追加します。