Gérer les attributs

Cette page s'applique à Apigee et à Apigee hybrid.

Présentation

Vous pouvez considérer un attribut comme une métadonnée pour une ressource. Par exemple, dans le cas d'une ressource d'API, celle-ci peut avoir un attribut appelé Target Users qui spécifie si l'API est destinée à une utilisation publique, privée ou interne. De nombreux autres attributs de ce type sont disponibles.

Les attributs vous sont utiles des manières suivantes :

Vous pouvez filtrer les résultats de votre recherche de ressources en fonction des attributs. Par conséquent, un plus grand nombre d'attributs vous permettra d'affiner plus facilement vos résultats de recherche.
Vous pouvez créer des attributs personnalisés et les associer à des ressources du hub d'API.

Le hub d'API stocke un attribut au format clé-valeur. où la clé est le nom de l'attribut et la valeur est la valeur correspondante de l'attribut. La valeur peut avoir l'un des formats suivants :

Chaîne
Enum
JSON

Les attributs peuvent être de deux types :

Les attributs système, qui sont prédéfinis par le hub d'API.
Les attributs utilisateur, qui sont définis par vous.

Attributs système

Les attributs système sont prédéfinis par le hub d'API pour chaque type de ressource. La liste de ces attributs et leurs définitions de valeurs dépendent de la version du hub d'API et peuvent donc changer d'une version à l'autre. Voici quelques exemples d'attributs système : étape du cycle de vie, conformité des API, accréditation des API, SLO, etc. Ces attributs peuvent être obligatoires ou facultatifs pour une ressource. Si un attribut est obligatoire pour une ressource, vous devez définir la valeur de l'attribut lors de l'enregistrement de la ressource.

Les valeurs des attributs système de type Enum peuvent être immuables ou modifiables.

Immuable : vous ne pouvez pas modifier les valeurs existantes. Toutefois, vous pouvez ajouter de nouvelles valeurs modifiables à l'attribut. Par exemple, l'attribut oas-version aura les valeurs 2.1, 3.0 et 3.1. Vous ne pouvez pas mettre à jour ces valeurs, mais vous pouvez ajouter de nouvelles valeurs personnalisées.
Modifiable : vous pouvez ajouter des valeurs et modifier ou supprimer les valeurs existantes. Par exemple, l'attribut lifecycle-stage peut initialement avoir des valeurs telles que Dev, Stage, UAT ou Prod. Vous pouvez modifier ces valeurs existantes et ajouter de nouvelles valeurs.

Afficher les attributs système

Console

Pour afficher tous les attributs système, accédez à la page API Hub > Paramètres dans la console Google Cloud. Vous pouvez afficher tous les attributs système existants dans l'onglet Attributs système.

API REST

Pour afficher tous les attributs système d'une ressource, envoyez une requête GET à l'API suivante :

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

Pour en savoir plus sur l'API, consultez la section ListAttributes.

L'exemple suivant montre l'appel d'API permettant d'obtenir les attributs système de toutes les ressources.

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

Modifier un attribut système de type Enum

Vous pouvez effectuer les opérations suivantes pour une valeur modifiable :

Ajouter une valeur
Mettre à jour une valeur existante
Supprimer une valeur d'attribut existante

Les exemples de cette section montrent comment mettre à jour les valeurs autorisées d'un attribut système de type Enum.

Console

Pour ajouter une valeur à un attribut système, procédez comme suit :

Dans la console Google Cloud, accédez à la page API Hub > Paramètres.
Tous les attributs système existants s'affichent dans la section Attributs système de l'onglet Attributs.
Cliquez sur Modifier pour l'attribut auquel vous souhaitez ajouter une valeur.
Le volet de modification de l'attribut s'ouvre et affiche les valeurs d'attributs existantes.
Pour ajouter une valeur, cliquez sur Ajouter un élément, puis saisissez la nouvelle valeur que vous souhaitez ajouter.
Remarque : Pour supprimer une valeur existante, cliquez sur Supprimer pour la valeur que vous souhaitez supprimer. L'option Delete ne s'affiche que pour les valeurs modifiables. Par conséquent, si l'option de suppression n'est pas affichée pour une valeur, vous pouvez déduire que cette valeur est immuable.
Cliquez sur Enregistrer.

API REST

Pour mettre à jour les valeurs autorisées d'un attribut défini par le système de type Enum, envoyez une requête PATCH à l'API suivante :

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

Pour en savoir plus sur l'API, consultez la section UpdateAttribute.

L'exemple suivant montre l'appel d'API permettant de mettre à jour les valeurs de l'attribut 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

Il est important de comprendre comment le hub d'API interprète la charge utile de requête pour l'API UpdateAttribute.

Si la valeur que vous spécifiez dans la charge utile est déjà présente, le hub d'API vérifie si la valeur a été mise à jour dans la charge utile, puis écrase la valeur si elle est mise à jour.
Si la valeur n'est pas disponible dans la charge utile, le hub d'API considère que cette valeur doit être supprimée et la supprime du hub d'API.
Si une nouvelle valeur est disponible dans la charge utile, le hub d'API l'ajoute à l'attribut.

Attributs définis par l'utilisateur

Les attributs utilisateur sont définis par vos soins en fonction de vos besoins.

Afficher les attributs définis par l'utilisateur

Console

Pour afficher tous les attributs utilisateur, accédez à la page API Hub > Paramètres dans la console Google Cloud. Vous pouvez afficher tous les attributs utilisateur dans la section Attributs définis par l'utilisateur de l'onglet Attributs.

API REST

Pour afficher tous les attributs utilisateur d'une ressource, envoyez une requête GET à l'API suivante :

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

Pour en savoir plus sur l'API, consultez la section ListAttributes.

L'exemple suivant montre l'appel d'API permettant d'obtenir les attributs utilisateur de la ressource d'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

Ajouter un attribut utilisateur

Console

Pour ajouter un attribut utilisateur, procédez comme suit :

Dans la console Google Cloud, accédez à la page API Hub > Paramètres.
Tous les attributs utilisateur s'affichent dans la section Attributs utilisateur de l'onglet Attributs.
Cliquez sur Créer un attribut.
Le volet Ajouter un attribut s'ouvre.
Saisissez les informations suivantes :
- Identifiant : saisissez un identifiant unique pour l'attribut.
  - Si vous laissez ce champ vide, le hub d'API génère automatiquement un identifiant unique pour vous.
  - Si vous souhaitez saisir une valeur manuellement, assurez-vous qu'elle est unique pour tous les attributs.
- Nom : saisissez un nom pour l'attribut.
- Description : si vous le souhaitez, saisissez une description de l'attribut.
- Valeurs maximales autorisées : saisissez un nombre compris entre 1 et 20. Ce paramètre spécifie le nombre maximal de valeurs que l'attribut peut contenir.
- Type de ressource : sélectionnez un type de ressource.
Pour ajouter une valeur pour le type d'énumération, cliquez sur Ajouter un élément, puis saisissez la nouvelle valeur que vous souhaitez ajouter.
Remarque : Pour supprimer une valeur existante, cliquez sur Supprimer pour la valeur que vous souhaitez supprimer.
Cliquez sur Enregistrer.

API REST

Pour ajouter un attribut utilisateur, envoyez une requête POST à l'API suivante :

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

Pour en savoir plus sur l'API, consultez la section CreateAttribute.

L'exemple suivant montre l'appel d'API permettant de créer l'attribut utilisateur 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

Modifier un attribut utilisateur

Vous pouvez effectuer les modifications suivantes sur un attribut utilisateur :

Mettre à jour le nom de l'attribut
Ajouter une valeur d'attribut
Supprimer une valeur d'attribut existante

Console

Pour modifier un attribut utilisateur, procédez comme suit :

Dans la console Google Cloud, accédez à la page API Hub > Paramètres.
Tous les attributs utilisateur existants s'affichent dans la section Attributs utilisateur de l'onglet Attributs.
Cliquez sur Modifier pour l'attribut que vous souhaitez modifier.
Le volet de modification de l'attribut s'ouvre et affiche les valeurs d'attributs existantes.
Vous pouvez modifier le nom, la description et les valeurs maximales autorisées. Pour les types d'énumération, vous pouvez ajouter de nouvelles valeurs. Pour ajouter une valeur pour un type d'énumération, cliquez sur Ajouter un élément, puis saisissez la nouvelle valeur que vous souhaitez ajouter.
Cliquez sur Enregistrer.

API REST

Pour modifier un attribut utilisateur, envoyez une requête PATCH à l'API suivante :

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

Pour en savoir plus sur l'API, consultez la section UpdateAttribute.

L'exemple suivant montre l'appel d'API permettant de mettre à jour l'attribut utilisateur 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

Il est important de comprendre comment le hub d'API interprète la charge utile de requête pour l'API UpdateAttribute.

Si la valeur que vous spécifiez dans la charge utile est déjà présente, le hub d'API vérifie si la valeur a été mise à jour dans la charge utile, puis écrase la valeur si elle est mise à jour.
Si la valeur n'est pas disponible dans la charge utile, le hub d'API considère que cette valeur doit être supprimée et la supprime du hub d'API.
Si une nouvelle valeur est disponible dans la charge utile, le hub d'API l'ajoute à l'attribut.