Gestisci attributi

Questa pagina si applica ad Apigee e Apigee hybrid.

Panoramica

Un attributo è un po' come un metadati per una risorsa. Ad esempio, nel caso di una risorsa API, l'API può avere un attributo denominato Target Users che specifica se l'API è destinata all'utilizzo pubblico, privato o interno. Sono disponibili molti altri attributi di questo tipo.

Gli attributi ti sono utili per:

  • Puoi filtrare i risultati di ricerca delle risorse in base agli attributi. Pertanto, avere più attributi ti consentirà di restringere facilmente i risultati di ricerca.
  • Puoi creare attributi personalizzati e associarli alle risorse dell'hub API.

L'hub API memorizza un attributo nel formato chiave-valore, dove la chiave è il nome dell'attributo e il valore è il valore corrispondente dell'attributo. Il valore può essere in uno dei seguenti formati:

  • Stringa
  • Enum
  • JSON

Gli attributi possono essere di due tipi:

  • Attributi di sistema predefiniti dall'hub API.
  • Attributi utente definiti da te.

Attributi di sistema

Gli attributi di sistema sono predefiniti dall'hub API per ogni tipo di risorsa. L'elenco di questi attributi e le relative definizioni dei valori possono variare da una release all'altra dell'hub API. Esempi di sistema sono: fase del ciclo di vita, conformità API, accreditamento API, SLO e così via. Questi attributi possono essere obbligatori o facoltativi per una risorsa. Se un attributo è obbligatorio per una risorsa, devi impostare il valore dell'attributo quando registri la risorsa.

I valori degli attributi di sistema di tipo Enum possono essere immutabili o mutabili.

  • Immutabile: non puoi apportare modifiche ai valori esistenti. Tuttavia, puoi aggiungere nuovi valori mutevoli all'attributo. Ad esempio, l'attributo oas-version avrà i valori 2.1, 3.0 e 3.1. Non puoi aggiornare questi valori, ma puoi aggiungere nuovi valori personalizzati.
  • Mutabile: puoi aggiungere, modificare o eliminare i valori esistenti. Ad esempio, l'attributo lifecycle-stage può inizialmente avere valori come Dev, Stage, UAT o Prod. Puoi modificare questi valori esistenti e aggiungerne di nuovi.

Visualizza attributi di sistema

Console

Per visualizzare tutti gli attributi di sistema, nella console Google Cloud vai all'hub API > Impostazioni. Puoi visualizza tutti gli attributi di sistema esistenti nella scheda Attributi di sistema.

API REST

Per visualizzare tutti gli attributi di sistema di una risorsa, invia una richiesta GET alla seguente API:

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

Per ulteriori informazioni sull'API, consulta ListAttributes.

L'esempio seguente mostra la chiamata API per recuperare gli attributi di sistema per tutte le risorse.

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

Modifica un attributo di sistema di tipo Enum

Per un valore modificabile, puoi eseguire le seguenti operazioni:

  • Aggiungi un nuovo valore
  • Aggiorna un valore esistente
  • Eliminare un valore dell'attributo esistente

Gli esempi in questa sezione mostrano come aggiornare i valori consentiti di un attributo di sistema di tipo enum.

Console

Per aggiungere un valore per un attributo di sistema:

  1. Nella console Google Cloud, vai alla pagina API Hub > Impostazioni.

    Vengono visualizzati tutti gli attributi di sistema esistenti nella sezione Attributi di sistema della scheda Attributi.

  2. Fai clic su Modifica per l'attributo a cui vuoi aggiungere un valore.

    Viene visualizzato il riquadro di modifica dell'attributo, che mostra i valori esistenti.

  3. Per aggiungere un nuovo valore, fai clic su Aggiungi elemento e inserisci il nuovo valore da aggiungere.
  4. Fai clic su Salva.

API REST

Per aggiornare i valori consentiti di un attributo definito dal sistema del tipo di dati Enum, invia una richiesta PATCH all'API seguente:

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

Per ulteriori informazioni sull'API, consulta UpdateAttribute.

L'esempio seguente mostra la chiamata API per aggiornare i valori dell'attributo 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

È importante capire in che modo l'hub API interpreta il payload delle richieste per l'API UpdateAttribute.

  • Se il valore specificato nel payload è già presente, l'hub API controlla se il valore è aggiornato nel payload, e poi sovrascrive il valore se viene aggiornato.
  • Se il valore non è disponibile nel payload, l'hub API interpreta che il valore dovrebbe essere eliminato ed elimina il valore dall'hub API.
  • Se nel payload è disponibile un nuovo valore, l'hub API aggiunge il nuovo valore all'attributo.

Attributi definiti dall'utente

Sei tu a definire gli attributi definiti dall'utente in base alle tue esigenze.

Visualizza attributi definiti dall'utente

Console

Per visualizzare tutti gli attributi utente, nella console Google Cloud vai alla pagina API Hub > Impostazioni. Puoi Visualizza tutti gli attributi utente nella sezione Attributi definiti dall'utente della scheda Attributi.

API REST

Per visualizzare tutti gli attributi utente di un problema relativo a una risorsa, invia una richiesta GET alla seguente API:

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

Per ulteriori informazioni sull'API, consulta ListAttributes.

L'esempio seguente mostra la chiamata API per portare l'utente per la risorsa 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

Aggiungere un nuovo attributo utente

Console

Per aggiungere un nuovo attributo utente:

  1. Nella console Google Cloud, vai all'hub API > Impostazioni.

    In questo modo vengono visualizzati tutti gli attributi utente nella sezione Attributi utente della scheda Attributi.

  2. Fai clic su Crea attributo.

    Viene visualizzato il riquadro Aggiungi un nuovo attributo.

  3. Inserisci i seguenti dettagli:
    • ID : inserisci un identificatore univoco per l'attributo.
      • Se lasci vuoto il campo, API Hub genera automaticamente un ID univoco.
      • Se vuoi inserire manualmente un valore, assicurati che sia univoco in tutti gli attributi.
    • Nome: inserisci un nome per l'attributo.
    • Descrizione : se vuoi, inserisci una descrizione dell'attributo.
    • Valori massimi consentiti: inserisci un numero compreso tra 1 e 20. Questa impostazione specifica numero massimo di valori che l'attributo può avere.
    • Tipo di risorsa: seleziona un tipo di risorsa.
  4. Per aggiungere un nuovo valore per il tipo Enum, fai clic su Aggiungi elemento e inserisci il nuovo valore da aggiungere.
  5. Fai clic su Salva.

API REST

Per aggiungere un nuovo attributo utente, invia una richiesta POST alla seguente API:

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

Per maggiori informazioni sull'API, vedi CreateAttribute.

L'esempio seguente mostra la chiamata API per creare l'attributo utente 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

Modificare un attributo utente

Su un attributo utente puoi apportare le seguenti modifiche:

  • Aggiorna il nome dell'attributo
  • Aggiungi un nuovo valore dell'attributo
  • Eliminare un valore dell'attributo esistente

Console

Per modificare un attributo utente:

  1. Nella console Google Cloud, vai all'hub API > Impostazioni.

    In questo modo vengono visualizzati tutti gli attributi utente esistenti nella sezione Attributi utente della scheda Attributi.

  2. Fai clic su Modifica per l'attributo che vuoi modificare.

    Viene visualizzato il riquadro di modifica dell'attributo in cui sono visualizzati i valori degli attributi esistenti.

  3. Puoi modificare il nome, la descrizione e i valori massimi consentiti. Per i tipi Enum, puoi aggiungere nuovi valori. Per aggiungere un nuovo valore per un tipo enum, fai clic su Aggiungi elemento e inserisci il nuovo valore che vuoi aggiungere.
  4. Fai clic su Salva.

API REST

Per modificare un attributo utente, invia una richiesta PATCH alla seguente API:

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

Per ulteriori informazioni sull'API, consulta UpdateAttribute.

L'esempio seguente mostra l'aggiornamento della chiamata API dell'attributo utente 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

È importante capire in che modo l'hub API interpreta il payload delle richieste per l'API UpdateAttribute.

  • Se il valore specificato nel payload è già presente, l'hub API controlla se il valore è stato aggiornato nel payload. e poi sovrascrive il valore se viene aggiornato.
  • Se il valore non è disponibile nel payload, API Hub lo interpreta come un valore da eliminare ed esegue l'eliminazione.
  • Se nel payload è disponibile un nuovo valore, l'hub API lo aggiunge all'attributo.