Utiliser les ensembles de propriétés

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

Consultez la documentation d'Apigee Edge.

Un ensemble de propriétés est une collection personnalisée de paires clé/valeur qui stockent des données. Les proxys d'API peuvent récupérer ces données lors de leur exécution.

Pourquoi utiliser des ensembles de propriétés?

En règle générale, les ensembles de propriétés vous permettent de stocker des données qui n'expirent pas et qui ne devraient pas être codées en dur dans votre logique de proxy d'API. Vous pouvez accéder aux données d'un ensemble de propriétés n'importe où dans un proxy où vous pouvez accéder aux variables de flux.

Un cas d'utilisation courant pour les ensembles de propriétés consiste à fournir des valeurs qui sont associées à un environnement ou à un autre. Par exemple, vous pouvez créer un ensemble de propriétés au niveau de l'environnement avec des valeurs de configuration spécifiques aux proxys exécutés dans votre environnement de test, et un autre défini pour votre environnement de production.

Exemple :

L'ensemble de propriétés prod-env.properties contient la propriété log-level=error.
L'ensemble de propriétés test-env.properties contient la propriété log-level=debug.

De même, vous pouvez stocker des informations de routage spécifiques à l'environnement :

L'ensemble de propriétés test-env.properties contient la propriété db-url=mydomain.test.datasource.com.
L'ensemble de propriétés prod-env.properties contient la propriété db-url=mydomain.prod.datasource.com.

Champs d'application des ensembles de propriétés

Vous pouvez étendre un ensemble de propriétés à une révision ou un environnement de proxy d'API lors de la création de l'ensemble de propriétés. Vous ne pouvez pas étendre un ensemble de propriétés à une organisation.

Le tableau suivant explique le comportement et l'administration des ensembles de propriétés avec le proxy API et le champ d'application de l'organisation :

Portée	Comportement lors de l'exécution	Administration
Proxy d'API	Les propriétés ne sont disponibles que pour la révision du proxy d'API contenant la ressource d'ensemble de propriétés. Aucun autre proxy d'API ni révision du même proxy ne peut accéder à cet ensemble de propriétés donné.	Les administrateurs peuvent utiliser l'API Apigee /resourcefiles ou l'interface utilisateur pour créer et modifier des ensembles de propriétés. L'enregistrement du proxy d'API dans l'interface utilisateur crée une nouvelle révision, et l'ensemble de propriétés modifié est associé à cette révision uniquement.
Environment	Les propriétés sont disponibles pour toutes les révisions de tous les proxys d'API existant dans cet environnement. Les proxys d'API situés d'autres environnements ne peuvent pas accéder à cet ensemble de propriétés.	Les administrateurs doivent utiliser l'API Apigee /resourcefiles pour créer, afficher, mettre à jour ou supprimer des ensembles de propriétés à l'échelle de l'environnement. Ces ensembles de propriétés ne sont pas affichés et ne peuvent pas être modifiés dans l'interface utilisateur d'Apigee.

Limites des ensembles de propriétés

Apigee impose des limites aux ensembles de propriétés, comme décrit à la section Limites. De plus, les fichiers d'ensembles de propriétés doivent utiliser la même syntaxe que les fichiers de propriétés Java, à une exception près : vous ne pouvez pas utiliser d'accolades {} dans les fichiers d'ensembles de propriétés.

Créer des fichiers d'ensembles de propriétés

En règle générale, les valeurs des ensembles de propriétés sont stockées dans un fichier sous forme de paires nom/valeur. Les fichiers d'ensembles de propriétés sont des fichiers de ressources de type properties.

Les fichiers d'ensembles de propriétés acceptent la même syntaxe que les fichiers de propriétés Java. Par exemple, ils peuvent contenir des valeurs Unicode et utiliser les caractères # ou ! comme repères de commentaires. La seule différence notable est que vous ne pouvez pas utiliser d'accolades {} dans les fichiers d'ensembles de propriétés.

Vous devez ajouter le suffixe .properties au nom de fichier de propriété. Par exemple, myconfig.my_key.properties est autorisé, mais myconfig.my_key n'est pas autorisé.

La structure d'une spécification d'ensemble de propriétés est la suivante : property_set_name.property_name.properties. Le nom de l'ensemble de propriétés et le nom de la propriété ne peuvent pas comporter de points. Par exemple : myconfig.my_key.properties est autorisé, mais myconfig.my.key.properties et my.config.my_key.properties ne le sont pas.

L'exemple suivant montre un fichier de jeu de propriétés simple qui définit plusieurs propriétés :

# myProps.properties file
# General properties
foo=bar
baz=biff

# Messages/notes/warnings
message=This is a basic message.
note_message=This is an important message.
error_message=This is an error message.

# Keys
publickey=abc123
privatekey=splitwithsoundman

Après avoir créé un fichier d'ensemble de propriétés, vous l'importez dans Apigee à l'aide de l'interface utilisateur ou de l'API.

Gérer des ensembles de propriétés à l'aide de l'interface utilisateur

La gestion des ensembles de propriétés restreints à une révision du proxy d'API s'effectue via l'interface utilisateur de la même manière la gestion d'autres ressources. Pour plus d'informations, consultez la section Gérer les ressources à l'aide de l'UI.

Gérer les ensembles de propriétés à l'aide de l'API

Gérez des ensembles de propriétés étendus à une révision ou un environnement de proxy d'API en utilisant l'API, comme décrit dans les sections suivantes.

Créer des ensembles de propriétés à l'aide de l'API

Les sections suivantes décrivent comment créer des ensembles de propriétés étendus à une révision ou un environnement de proxy d'API à l'aide de l'API.

Créer des ensembles de propriétés limités à une révision de proxy d'API à l'aide de l'API

Pour créer un ensemble de propriétés étendu à une révision de proxy d'API à l'aide de l'API :

Créez le fichier de l'ensemble de propriétés.
Ajoutez le fichier d'ensemble de propriétés à un groupe de configuration de proxy d'API.
Importez le groupe à l'aide de l'API Create API proxy ou Update API proxy revision.

Créer des ensembles de propriétés étendus à un environnement à l'aide de l'API

Pour ajouter un ensemble de propriétés étendu à un environnement à l'aide de l'API, créez le fichier d'ensembles de propriétés, puis importez-le dans un environnement de votre organisation en envoyant une requête POST à la ressource suivante : https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/resourcefiles

Incluez les informations suivantes dans votre requête :

Définissez le paramètre de requête name sur le nom de l'ensemble de propriétés.
Définissez le paramètre de requête type sur properties
Transmettez le contenu du fichier d'ensemble de propriétés en tant que application/octet-stream ou multipart/form-data.

Remarque : Lors de l'importation d'un fichier d'ensemble de propriétés à l'aide de l'API, vous devrez peut-être exécuter la commande chmod sur les autorisations du fichier pour que votre outil de développement (par exemple, curl) puisse l'importer.

L'exemple suivant importe un ensemble de propriétés nommé MyPropSet à partir du fichier /Users/myhome/myprops.properties :

curl -X POST "https://apigee.googleapis.com/v1/organizations/my-organization/environments/test/resourcefiles?name=MyPropSet&type=properties"
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-type: multipart/form-data" \
  -F file=@/Users/myhome/myprops.properties

$TOKEN est défini sur votre jeton d'accès OAuth 2.0, comme décrit dans la section Obtenir un jeton d'accès OAuth 2.0. Pour en savoir plus sur les options curl utilisées dans cet exemple, consultez la section Utiliser curl.

Voici un exemple de réponse :

{
  "name": "MyPropSet",
  "type": "properties"
}

Pour plus d'informations, consultez Créer une API de fichier de ressources.

Afficher les ensembles de propriétés à l'aide de l'API

Les sections suivantes décrivent comment utiliser l'API pour afficher les ensembles de propriétés associés à un environnement.

Afficher tous les ensembles de propriétés étendus à un environnement à l'aide de l'API

Pour afficher tous les ensembles de propriétés étendus à un environnement en utilisant l'API, envoyez une requête GET à la ressource suivante : https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/resourcefiles/properties

L'exemple suivant répertorie tous les ensembles de propriétés dans l'environnement de test :

curl -X GET "https://apigee.googleapis.com/v1/organizations/my-organization/environments/test/resourcefiles/properties" \
  -H "Authorization: Bearer $TOKEN"

Voici un exemple de réponse :

{
  "resourceFile": [
    {
      "name": "MyPropSet",
      "type": "properties"
    }
  ]
}

Pour en savoir plus, consultez la section Répertorier les API des fichiers de ressources d'environnement.

Afficher le contenu d'un ensemble de propriétés étendu à un environnement à l'aide de l'API

Pour afficher le contenu d'un ensemble de propriétés étendu à un environnement à l'aide de l'API, envoyez une requête GET à la ressource suivante : https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/resourcefiles/properties/name

L'exemple suivant affiche le contenu de l'ensemble de propriétés MyPropSet dans l'environnement de test :

curl -X GET "https://apigee.googleapis.com/v1/organizations/my-organization/environments/test/resourcefiles/properties/MyPropSet" \
  -H "Authorization: Bearer $TOKEN"

Voici un exemple de réponse :

# myProps.properties file
# General properties
foo=bar
baz=biff

# Messages/notes/warnings
message=This is a basic message.
note_message=This is an important message.
error_message=This is an error message.

# Keys
publickey=abc123
privatekey=splitwithsoundman

Pour en savoir plus, consultez la section Répertorier les API des fichiers de ressources d'environnement.

Mettre à jour les ensembles de propriétés à l'aide de l'API

Les sections suivantes décrivent comment mettre à jour des ensembles de propriétés étendus à une révision ou un environnement de proxy d'API à l'aide de l'API.

Mettre à jour les ensembles de propriétés limités à une révision de proxy d'API à l'aide de l'API

Pour mettre à jour un ensemble de propriétés étendu à une révision de proxy d'API à l'aide de l'API :

Mettez à jour le fichier d'ensemble de propriétés.
Téléchargez le groupe de configuration du proxy d'API à l'aide de l'API d'obtention de révision de proxy d'API avec les options suivantes :
- Définissez le paramètre de requête format sur bundle
- Définissez l'en-tête Accept sur application/zip
Ajoutez le fichier d'ensemble de propriétés au groupe de configuration de proxy d'API.
Importez le groupe de configuration de proxy d'API à l'aide de l'API de mise à jour de révision de proxy d'API.

Mettre à jour des ensembles de propriétés limités à un environnement à l'aide de l'API

Pour mettre à jour un ensemble de propriétés étendu à un environnement à l'aide de l'API, mettez à jour le fichier d'ensembles de propriétés, puis importez-le dans un environnement de votre organisation en envoyant une requête PUT à la ressource suivante : https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/resourcefiles/{type}/{name}

Incluez les informations suivantes dans votre requête :

Définissez {type} sur properties
Définissez {name} sur le nom de l'ensemble de propriétés que vous souhaitez mettre à jour.
Transmettez le contenu du fichier d'ensemble de propriétés en tant que application/octet-stream ou multipart/form-data.

L'exemple suivant met à jour l'ensemble de propriétés MyPropSet à l'aide du contenu du fichier /Users/myhome/myprops-revised.properties :

curl -X PUT "https://apigee.googleapis.com/v1/organizations/my-organization/environments/test/resourcefiles/properties/MyPropSet"
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-type: multipart/form-data" \
  -F file=@/Users/myhome/myprops-revised.properties

Voici un exemple de réponse :

{
  "name": "MyPropSet",
  "type": "properties"
}

Pour plus d'informations, consultez Mettre à jour une API de fichier de ressources.

Supprimer des ensembles de propriétés à l'aide de l'API

Les sections suivantes décrivent comment supprimer des ensembles de propriétés étendus à une révision ou un environnement de proxy d'API à l'aide de l'API.

Supprimer des ensembles de propriétés limités à une révision de proxy d'API à l'aide de l'API

Pour supprimer un ensemble de propriétés étendu à une révision de proxy d'API à l'aide de l'API :

Téléchargez le groupe de configuration du proxy d'API à l'aide de l'API d'obtention de révision de proxy d'API avec les options suivantes :
- Définissez le paramètre de requête format sur bundle
- Définissez l'en-tête Accept sur application/zip
Supprimez le fichier d'ensemble de propriétés du groupe de configuration du proxy d'API.
Importez le groupe de configuration de proxy d'API à l'aide de l'API de mise à jour de révision de proxy d'API.

Supprimer des ensembles de propriétés limités à un environnement à l'aide de l'API

Pour supprimer un ensemble de propriétés étendu à un environnement à l'aide de l'API, envoyez une requête DELETE à la ressource suivante : https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/resourcefiles/{type}/{name}

Transmettez les informations suivantes dans votre requête :

Définissez {type} sur properties
Définissez {name} sur le nom de l'ensemble de propriétés que vous souhaitez supprimer.

L'exemple suivant supprime l'ensemble de propriétés MyPropSet :

curl -X DELETE https://apigee.googleapis.com/v1/organizations/my-organization/environments/test/resourcefiles/properties/MyPropSet \
  -H "Authorization: Bearer $TOKEN"

Voici un exemple de réponse :

{
  "name": "MyPropSet",
  "type": "properties"
}

Pour plus d'informations, consultez Supprimer une API de fichier de ressources.

Accéder aux valeurs définies pour la propriété

Accédez aux valeurs d'ensembles de propriétés n'importe où dans un proxy d'API permettant d'accéder aux variables de flux : dans les stratégies, les flux, le code JavaScript, etc.

Pour accéder aux valeurs d'un ensemble de propriétés, utilisez la syntaxe suivante :

propertyset.[property_set_name].[property_name]

Où :

property_set_name correspond au nom de fichier que vous avez défini (si vous avez utilisé l'interface utilisateur) ou à la valeur du paramètre de requête name (si vous avez utilisé l'API).
property_name est le nom de la propriété. Par exemple, si votre ensemble de propriétés contient l'élément foo=bar, foo est le nom de la propriété et bar sa valeur.

Par exemple, dans une stratégie JavaScript, utilisez la méthode getVariable() pour obtenir une valeur à partir d'un ensemble de propriétés :

context.getVariable('propertyset.property_set_name.property_name);

L'exemple suivant obtient la valeur de la propriété foo dans l'ensemble de propriétés nommé "MyPropSet" :

context.getVariable('propertyset.MyPropSet.foo);

Vous pouvez également utiliser la règle ExtractVariables pour obtenir la valeur d'une propriété à partir d'un ensemble de propriétés et l'attribuer à une autre variable, comme le montre l'exemple suivant :

<ExtractVariables name="ExtractVariables-1">
   <DisplayName>Extract a portion of the url path</DisplayName>
   <Source>request</Source>
   <Variable name="propertyset.MyPropSet.foo">
      <Pattern>{myVar}</Pattern>
   </Variable>
   <VariablePrefix>foobar</VariablePrefix>
   <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

Dans cet exemple, la règle lit la variable à partir de l'attribut name et affecte la valeur à la variable dans l'élément Pattern.

Attribuer la valeur d'une clé d'ensemble de propriétés de manière dynamique à l'aide de la règle "Attribuer un message"

La règle "Attribuer un message" vous permet d'attribuer la valeur de la clé d'ensemble de propriétés à une variable de flux de façon dynamique. Pour en savoir plus, consultez la description de PropertySetRef dans la documentation de référence consacrée à la règle d'attribution de message.

Pour les utilisateurs d'Apigee hybride

Si vous utilisez Apigee hybride, notez les points suivants :

Le plan de gestion hybride valide l'ensemble de propriétés. Si elles sont valides, les propriétés sont stockées dans le plan de gestion.
Le synchronisateur récupère les données de l'ensemble de propriétés et les stocke localement dans le plan d'exécution.
Le sous-traitant de messages charge l'ensemble de propriétés téléchargé et le rend disponible pour exécuter des proxys.