Utilizzo dei set di proprietà

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Un set di proprietà è una raccolta personalizzata di coppie chiave/valore in cui sono archiviati i dati. I proxy API possono recuperare questi dati durante l'esecuzione.

Perché utilizzare gli insiemi di proprietà?

In genere, i set di proprietà vengono utilizzati per archiviare dati in scadenza che non devono essere hardcoded nella logica del proxy API. Puoi accedere ai dati dei set di proprietà ovunque in un proxy da cui puoi accedere alle variabili di flusso.

Un caso d'uso comune per i set di proprietà è la fornitura di valori associati a un ambiente o a un altro. Ad esempio, puoi creare una proprietà basata sull'ambiente con valori di configurazione specifici per i proxy in esecuzione nel tuo ambiente di test e un altro set per l'ambiente di produzione.

Ad esempio:

• Il set di proprietà prod-env.properties contiene la proprietà log-level=error
• Il set di proprietà test-env.properties contiene la proprietà log-level=debug

Analogamente, potresti archiviare informazioni di routing specifiche per l'ambiente:

• Il set di proprietà test-env.properties contiene la proprietà db-url=mydomain.test.datasource.com
• Il set di proprietà prod-env.properties contiene la proprietà db-url=mydomain.prod.datasource.com

Ambiti set di proprietà

Quando crei il set di proprietà, puoi definire l'ambito di una proprietà impostata su una revisione del proxy API o su un ambiente. Non puoi definire l'ambito di una proprietà impostata su un'organizzazione.

La tabella seguente spiega il comportamento e l'amministrazione dei set di proprietà con proxy API e ambito dell'organizzazione:

Ambito	Comportamento di runtime	Amministrazione
proxy API	Le proprietà sono disponibili solo per la revisione del proxy API che contiene la risorsa del set di proprietà. Nessun altro proxy API o nessuna revisione dello stesso proxy può accedere a quel particolare set di proprietà.	Gli amministratori possono utilizzare l'API Apigee /resourcefiles o la UI per creare e modificare set di proprietà. Se salvi il proxy API nell'interfaccia utente, verrà creata una nuova revisione e il set di proprietà modificato verrà associato solo a quella revisione.
Ambiente	Le proprietà sono disponibili per tutte le revisioni di tutti i proxy API all'interno dell'ambiente. I proxy API in altri ambienti non possono accedere all'insieme di proprietà.	Gli amministratori devono utilizzare l'API Apigee /resourcefiles per creare, visualizzare, aggiornare o eliminare set di proprietà basati sull'ambiente. Questi set di proprietà non vengono visualizzati e non possono essere modificati nella UI di Apigee.

Limiti impostati per le proprietà

Apigee impone limiti ai set di proprietà, come descritto in Limiti. Inoltre, i file dei set di proprietà devono utilizzare la stessa sintassi dei file delle proprietà Java, con una sola eccezione: non puoi utilizzare parentesi graffe {} nei file dei set di proprietà.

Crea file di set di proprietà

In genere, i valori impostati per le proprietà vengono memorizzati come coppie nome/valore in un file. I file di set di proprietà sono file di risorse di tipo properties.

I file di set di proprietà supportano la stessa sintassi dei file di proprietà Java. Ad esempio, possono contenere valori Unicode e utilizzare caratteri # o ! come indicatori di commento. Nota questa unica eccezione: non puoi utilizzare parentesi graffe {} nei file di set di proprietà.

Devi aggiungere il suffisso .properties al nome file di una proprietà. Ad esempio: myconfig.my_key.properties è consentito, ma myconfig.my_key non è consentito.

La struttura della specifica di un set di proprietà è: property_set_name.property_name.properties Il nome e il nome della proprietà non possono contenere punti. Ad esempio: myconfig.my_key.properties è consentito, ma myconfig.my.key.properties e my.config.my_key.properties non sono consentiti.

L'esempio seguente mostra un semplice file di set di proprietà che definisce diverse proprietà:

# 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

Dopo aver creato un file di set di proprietà, puoi caricarlo su Apigee utilizzando l'interfaccia utente o l'API.

Gestire i set di proprietà utilizzando l'UI

Gestisci i set di proprietà con ambito di una revisione del proxy API utilizzando l'interfaccia utente nello stesso modo in cui gestisci altre risorse. Per saperne di più, consulta Gestire le risorse utilizzando l'interfaccia utente.

Nota:

• Puoi creare, aggiornare o eliminare i set di proprietà con ambito a una revisione proxy API solo se non è stato eseguito il deployment di questa revisione. Una volta eseguito il deployment, la revisione del proxy API rimane immutabile.
• Non puoi gestire i set di proprietà che hanno come ambito un'organizzazione o un ambiente utilizzando la UI. Per ulteriori informazioni, consulta la sezione Ambiti dei set di proprietà.

.

Gestire i set di proprietà utilizzando l'API

Gestisci i set di proprietà con ambito a una revisione del proxy API o a un ambiente utilizzando l'API, come descritto nelle sezioni seguenti.

Creare set di proprietà utilizzando l'API

Le sezioni seguenti descrivono come creare set di proprietà con ambito a una revisione proxy API o a un ambiente utilizzando l'API.

Crea set di proprietà con ambito a una revisione del proxy API utilizzando l'API

Nota: puoi aggiungere un set di proprietà con ambito a una revisione del proxy API esistente solo se non è stato eseguito il deployment della revisione. Dopo il deployment, la revisione del proxy API rimane immutabile.

Per creare un set di proprietà che abbia come ambito una revisione proxy API utilizzando l'API:

1. Crea il file del set di proprietà.
2. Aggiungi il file di set di proprietà a un pacchetto di configurazione del proxy API.
3. Carica il bundle utilizzando l'API Crea proxy API o Aggiorna revisione API proxy.

Crea set di proprietà con ambito a un ambiente utilizzando l'API

Per aggiungere un set di proprietà che ha come ambito un ambiente utilizzando l'API, crea il file del set di proprietà e poi caricalo in un ambiente della tua organizzazione inviando una richiesta POST alla seguente risorsa: https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/resourcefiles

Includi le seguenti informazioni nella richiesta:

• Imposta il parametro di query name sul nome dell'insieme di proprietà
• Imposta il parametro di query type su properties
• Trasmettere i contenuti del file del set di proprietà come application/octet-stream o multipart/form-data

Nota: quando importi il file di un set di proprietà utilizzando l'API, potresti dover chmodle autorizzazioni del file in modo che lo strumento di sviluppo (ad esempio curl) possa caricarlo.

L'esempio seguente importa un set di proprietà denominato MyPropSet dal file /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 is set to your OAuth 2.0 access token, as described in Obtaining an OAuth 2.0 access token. For information about the curl options used in this example, see Using curl.

The following provides an example of the response.

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

For more information, see Create resource file API.

View property sets using the API

The following sections describe how to view property sets scoped to an environment using the API.

View all property sets scoped to an environment using the API

To view all property sets scoped to an environment using the API, issue a GET request to the following resource: https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/resourcefiles/properties

The following example lists all property sets in the test environment:

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

$TOKEN is set to your OAuth 2.0 access token, as described in Obtaining an OAuth 2.0 access token. For information about the curl options used in this example, see Using curl.

The following provides an example of the response.

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

For more information, see List environment resource files API.

View the contents of a property set scoped to an environment using the API

To view the contents of a property set scoped to an environment using the API, issue a GET request to the following resource: https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/resourcefiles/properties/name

The following example displays the contents of the MyPropSet property set in the test environment:

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

$TOKEN is set to your OAuth 2.0 access token, as described in Obtaining an OAuth 2.0 access token. For information about the curl options used in this example, see Using curl.

The following provides an example of the response.

# 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

For more information, see List environment resource files API.

Update property sets using the API

The following sections describe how to update property sets scoped to an API proxy revision or environment using the API.

Update property sets scoped to an API proxy revision using the API

Note: You can update a property set scoped to an API proxy revision only if the revision has not been deployed. After an API proxy revision is deployed, it is immutable.

To update a property set that is scoped to an API proxy revision using the API:

1. Update the property set file.
2. Download the API proxy configuration bundle using the Get API proxy revision API with the following options:
   • Set the format query parameter to bundle
   • Set the Accept header to application/zip
3. Add the property set file to the API proxy configuration bundle.
4. Upload the API proxy configuration bundle using the Update API proxy revision API.

Update property sets scoped to an environment using the API

To update a property set that is scoped to an environment using the API, update the property set file and then upload it to an environment in your organization by issuing a PUT request to the following resource: https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/resourcefiles/{type}/{name}

Include the following information with your request:

• Set {type} to properties
• Set {name} to the name of the property set that you want to update
• Pass the contents of the property set file as application/octet-stream or multipart/form-data

Note: When importing a property set file using the API, you might need to chmod the file's permissions so that your development tool (such as curl) can upload it.

The following example updates the MyPropSet property set using the contents of the /Users/myhome/myprops-revised.properties file:

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
  

$TOKEN is set to your OAuth 2.0 access token, as described in Obtaining an OAuth 2.0 access token. For information about the curl options used in this example, see Using curl.

The following provides an example of the response.

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

For more information, see Update resource file API.

Delete property sets using the API

The following sections describe how to delete property sets scoped to an API proxy revision or environment using the API.

Delete property sets scoped to an API proxy revision using the API

Note: You can delete a property set scoped to an API proxy revision if it has not been deployed. After an API proxy revision is deployed, it is immutable.

To delete a property set that is scoped to an API proxy revision using the API:

1. Download the API proxy configuration bundle using the Get API proxy revision API with the following options:
   • Set the format query parameter to bundle
   • Set the Accept header to application/zip
2. Delete the property set file from the API proxy configuration bundle.
3. Upload the API proxy configuration bundle using the Update API proxy revision API.

Delete property sets scoped to an environment using the API

To delete a property set scoped to an environment using the API, issue a DELETE request to the following resource: https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/resourcefiles/{type}/{name}

Pass the following information with your request:

• Set {type} to properties
• Set {name} to the name of the property set that you want to delete

The following example deletes the MyPropSet property set:

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

$TOKEN is set to your OAuth 2.0 access token, as described in Obtaining an OAuth 2.0 access token. For information about the curl options used in this example, see Using curl.

The following provides an example of the response.

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

For more information, see Delete resource file API.

Access property set values

Access property set values anywhere in an API proxy where you can access flow variables: in policies, flows, JavaScript code, and so on.

To access values in a property set, use the following syntax:

propertyset.[property_set_name].[property_name]

Where:

• property_set_name is the filename that you defined (if you used the UI) or the value of the name query parameter (if you used the API).
• property_name is the name of the property. For example, if your property set contains foo=bar, foo is the name of the property and bar is the value.

For example, in a JavaScript policy, use the getVariable() method to get a value from a property set:

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

The following example gets the value of the foo property in the property set named "MyPropSet":

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

You can also use the ExtractVariables policy to get the value of a property from a property set and assign it to another variable, as the following example shows:

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

In this example, the policy reads the variable from the attribute name, and assigns the value to the variable in the Pattern element.

Assign the value of a property set key dynamically using the Assign Message policy

You can use the Assign Message policy to assign the value of property set key to a flow variable dynamically. For details, see the PropertySetRef description in the Assign Message policy reference.

For Apigee hybrid users

If you are using Apigee hybrid, note the following:

1. The hybrid management plane validates the property set; if valid, the properties are stored in the management plane.
2. The Synchronizer retrieves the property set data and stores it locally on the runtime plane.
3. The Message Processor loads the downloaded property set and makes it available to executing proxies.