Administra atributos

Esta página se aplica a Apigee y Apigee Hybrid.

Descripción general

Puedes pensar en un atributo como los metadatos de un recurso. Por ejemplo, en el caso de un recurso de API, la API puede tener un atributo llamado Target Users que especifique si la API está destinada al consumo público, privado o interno. Hay muchos otros atributos disponibles.

Los atributos son útiles para ti de las siguientes maneras:

Puedes filtrar los resultados de la búsqueda de recursos según los atributos. Por lo tanto, tener más atributos te ayudará a limitar los resultados de la búsqueda con mayor facilidad.
Puedes crear atributos personalizados y asociarlos a recursos del centro de APIs.

El concentrador de APIs almacena un atributo en el formato de clave-valor, en el que la clave es el nombre del atributo y el valor es el valor correspondiente del atributo. Y el valor puede estar en cualquiera de los siguientes formatos:

String
Enum
JSON

Los atributos pueden ser de los siguientes dos tipos:

Atributos del sistema, que están predefinidos por el concentrador de APIs.
Atributos de usuario, que tú defines.

Atributos del sistema

El concentrador de APIs predefine los atributos del sistema para cada tipo de recurso. La lista de estos atributos y sus definiciones de valor pueden cambiar de una versión a otra del concentrador de APIs. Estos son algunos ejemplos de atributos del sistema: etapa del ciclo de vida, cumplimiento de la API, acreditación de la API, SLO, entre otros. Estos atributos pueden ser obligatorios o ser opcionales para un recurso. Si un atributo es obligatorio para un recurso, debes configurar el valor del atributo cuando registras el recurso.

Los valores de los atributos del sistema de tipo Enum pueden ser inmutables o mutables.

Inmutable: no puedes realizar ningún cambio en los valores existentes. Sin embargo, puedes agregar nuevos valores mutables al atributo. Por ejemplo, el atributo oas-version tendrá los valores 2.1, 3.0 y 3.1. No puedes actualizar estos valores, pero puedes agregar valores personalizados nuevos.
Mutable: puedes agregar, editar o borrar los valores existentes. Por ejemplo, el atributo lifecycle-stage puede tener valores como Dev, Stage, UAT o Prod en un principio. Puedes editar estos valores existentes y agregar valores nuevos.

Visualiza los atributos del sistema

Console

Para ver todos los atributos del sistema ve a la página Concentrador de APIs > Configuración en la consola de Google Cloud. Puedes ver todos los atributos del sistema existentes en la pestaña Atributos del sistema.

API de REST

Para ver todos los atributos del sistema de un recurso, envía una solicitud GET a la siguiente API:

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

Para obtener más información acerca de la API, consulta ListAttributes.

En el siguiente ejemplo, se muestra la llamada a la API para obtener los atributos del sistema para todos los recursos.

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

Edita un atributo del sistema de tipo Enum

Puedes realizar las siguientes operaciones para un valor mutable:

Agregar un valor nuevo
Actualizar un valor existente
Borrar un valor de atributo existente

En los ejemplos de esta sección, se muestra cómo actualizar los valores permitidos de un atributo del sistema de tipo Enum.

Console

Para agregar un valor a un atributo del sistema, sigue estos pasos:

En la consola de Google Cloud, ve a la página Concentrador de APIs > Configuración.
De esta manera, se muestran todos los atributos existentes del sistema en la sección Atributos del sistema de la pestaña Atributos.
Haz clic en Editar en el atributo al que deseas agregar un valor.
Se abrirá el panel de edición del atributo, en el que se muestran los valores de los atributos existentes.
Para agregar un valor nuevo, haz clic en Agregar elemento y, luego, ingresa el valor nuevo que deseas agregar.
Nota: Para borrar un valor existente, haz clic en Borrar en el valor que deseas borrar. La opción Delete solo se muestra para los valores que son mutables. Por lo tanto, si no se muestra la opción de borrar para un valor, puedes inferir que ese valor es inmutable.
Haz clic en Guardar.

API de REST

Para actualizar los valores permitidos de un atributo definido por el sistema del tipo de datos Enum, envía una solicitud PATCH a la siguiente API:

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

Para obtener más información acerca de la API, consulta UpdateAttribute.

En el siguiente ejemplo, se muestra la llamada a la API para actualizar los valores del atributo Business unit.

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

Es importante comprender cómo el concentrador de APIs interpreta la carga útil de la solicitud para la API de UpdateAttribute.

Si el valor que especificas en la carga útil ya está presente, el concentrador de APIs verifica si el valor se actualizó en la carga útil y, luego, lo reemplaza si está actualizado.
Si el valor no está disponible en la carga útil, el concentrador de APIs interpreta que ese valor debe borrarse y lo borra del concentrador de APIs.
Si hay un valor nuevo disponible en la carga útil, el concentrador de APIs agrega el valor nuevo al atributo.

Atributos definidos por el usuario

Tú defines los atributos de usuario según tus requisitos.

Visualiza los atributos definidos por el usuario

Console

Para ver todos los atributos de usuario, ve a la página Concentrador de APIs > Configuración en la consola de Google Cloud. Puedes ver todos los atributos de usuario en la sección Atributos definidos por el usuario de la pestaña Atributos.

API de REST

Para ver todos los atributos de usuario de un recurso, envía una solicitud GET a la siguiente API:

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

Para obtener más información acerca de la API, consulta ListAttributes.

En el siguiente ejemplo, se muestra la llamada a la API para obtener los atributos de usuario para el recurso de la 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

Agrega un atributo de usuario nuevo

Console

Para agregar un atributo de usuario nuevo, sigue estos pasos:

En la consola de Google Cloud, ve a la página Concentrador de APIs > Configuración.
De esta forma, se muestran todos los atributos de usuario en la sección Atributos de usuario de la pestaña Atributos.
Haz clic en Crear atributo.
Se abrirá el panel Agregar un atributo nuevo.
Ingresa los siguientes detalles:
- ID: ingresa un identificador único para el atributo.
  - Si dejas el campo vacío, el concentrador de APIs genera automáticamente un ID único para ti.
  - Si deseas ingresar un valor de forma manual, asegúrate de que sea único en todos los atributos.
- Nombre: ingresa un nombre para el atributo.
- Descripción: de manera opcional, ingresa una descripción del atributo.
- Valores máximos permitidos: Ingresa un número del 1 al 20. Este parámetro de configuración especifica la cantidad máxima de valores que puede tener el atributo.
- Tipo de recurso: selecciona un tipo de recurso.
Para agregar un valor nuevo para el tipo Enum, haz clic en Agregar elemento y, luego, ingresa el valor nuevo que deseas agregar.
Nota: Para borrar un valor existente, haz clic en Borrar en el valor que deseas borrar.
Haz clic en Guardar.

API de REST

Para agregar un atributo de usuario nuevo, envía una solicitud POST a la siguiente API:

https://apihub.googleapis.com/v1/projects/PROJECT/locations/LOCATION/attributes?attribute_id=NEW_ATTRIBUTE_NAME

Para obtener más información acerca de la API, consulta CreateAttribute.

En el siguiente ejemplo, se muestra la llamada a la API para crear el atributo de usuario attribute-01.

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

Edita un atributo de usuario

Puedes realizar las siguientes ediciones en un atributo de usuario:

Actualizar el nombre del atributo
Agregar un valor de atributo nuevo
Borrar un valor de atributo existente

Console

Para editar un atributo de usuario, sigue estos pasos:

En la consola de Google Cloud, ve a la página Concentrador de APIs > Configuración.
De esta forma, se muestran todos los atributos de usuario existentes en la sección Atributos de usuario de la pestaña Atributos.
Haz clic en Editar en el atributo que desea editar.
Se abrirá el panel de edición del atributo, en el que se muestran los valores de los atributos existentes.
Puedes editar el nombre, la descripción y los valores máximos permitidos. Para los tipos de Enum, puedes agregar valores nuevos. Para agregar un valor nuevo para un tipo de Enum, haz clic en Agregar elemento y, luego, ingresa el valor nuevo que deseas agregar.
Haz clic en Guardar.

API de REST

Para editar un atributo de usuario, envía una solicitud PATCH a la siguiente API:

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

Para obtener más información acerca de la API, consulta UpdateAttribute.

En el siguiente ejemplo, se muestra la actualización del atributo de usuario API Visibility en la llamada a la 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

Es importante comprender cómo el concentrador de APIs interpreta la carga útil de la solicitud para la API de UpdateAttribute.

Si el valor que especificas en la carga útil ya está presente, el concentrador de APIs verifica si el valor se actualizó en la carga útil y, luego, lo reemplaza si está actualizado.
Si el valor no está disponible en la carga útil, el concentrador de APIs interpreta que ese valor debe borrarse y lo borra del concentrador de APIs.
Si hay un valor nuevo disponible en la carga útil, el concentrador de APIs agrega el valor nuevo al atributo.