管理属性

本页面适用于 Apigee 和 Apigee Hybrid。

概览

您可以将属性视为资源的元数据。例如，对于 API 资源，API 可以有一个名为 Target Users 的属性，用于指定 API 是供公共、私人还是内部使用。 还有许多其他此类属性可供使用。

属性可通过以下方式为您提供帮助：

  • 您可以根据属性过滤资源搜索结果。因此，添加更多属性可让您轻松缩小搜索结果的范围。
  • 您可以创建自定义属性并将其关联到 API Hub 资源。

API Hub 以键值对格式存储属性；其中键是属性的名称，值是属性的对应值。该值可以采用以下任一格式：

  • 字符串
  • Enum
  • JSON

属性可以是以下两种类型：

  • 系统属性，由 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 > 设置页面。您可以在系统属性标签页中查看所有现有系统属性。

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 > 设置页面。

    这会在属性标签页的系统属性部分显示所有现有系统属性。

  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 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

添加新的用户属性

控制台

如需添加新的用户属性，请按以下步骤操作：

  1. 在 Google Cloud 控制台中，依次前往 API Hub > 设置页面。

    这会在属性标签页的用户属性部分显示所有用户属性。

  2. 点击创建属性。

    此时将打开添加新属性窗格。

  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 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 Hub 如何解析 UpdateAttribute API 的请求载荷。

  • 如果您在载荷中指定的值已存在，API Hub 会检查该值是否已在载荷中更新，然后在更新后覆盖该值。
  • 如果载荷中没有该值，API Hub 会解析该值应予以删除，并从 API Hub 中删除该值。
  • 如果载荷中有新值，API Hub 会将新值添加到属性中。