属性を管理する

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

概要

属性は、リソースのメタデータと考えることができます。たとえば、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 属性には、最初は DevStageUATProd などの値を設定できます。既存の値を編集することも、新しい値を追加することも可能です。

システム属性を表示する

コンソール

すべてのシステム属性を表示するには、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

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

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

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

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

コンソール

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

  1. Google Cloud コンソールで、[API Hub] > [設定] ページに移動します。

    [属性] タブの [System attributes] セクションに、既存のシステム属性がすべて表示されます。

  2. 値を追加する属性の [編集] をクリックします。

    属性の編集ペインが開き、既存の属性値が表示されます。

  3. 新しい値を追加するには、[項目を追加] をクリックして、追加する新しい値を入力します。
  4. [保存] をクリックします。

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

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

コンソール

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

  1. Google Cloud コンソールで、[API Hub] > [設定] ページに移動します。

    [属性] タブの [ユーザー属性] セクションにすべてのユーザー属性が表示されます。

  2. [属性を作成] をクリックします。

    [Add a new attribute] ペインが開きます。

  3. 次の詳細情報を入力します。
    • ID: 属性の固有識別子を入力します。
      • このフィールドを空のままにすると、API Hub によって一意の 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

ユーザー属性を編集する

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

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

コンソール

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

  1. Google Cloud コンソールで、[API Hub] > [設定] ページに移動します。

    既存のユーザー属性がすべて [属性] タブの [ユーザー属性] セクションに表示されます。

  2. 編集する属性の [編集] をクリックします。

    属性の編集ペインが開き、既存の属性値が表示されます。

  3. 名前、説明、最大許容値を編集できます。列挙型の場合は、新しい値を追加できます。列挙型の新しい値を追加するには、[項目を追加] をクリックして、追加する新しい値を入力します。
  4. [保存] をクリックします。

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 はその値を属性に追加します。