Condividi tramite


Usare i metadati per la governance delle API

Questo articolo fornisce informazioni generali sui metadati e su come usarli per la governance delle API nel Centro API di Azure. I metadati vengono definiti e impostati per organizzare e filtrare le API e altre entità nel centro API. I metadati possono essere compilati o personalizzati ed è possibile sviluppare uno schema di metadati per applicare la coerenza tra LE API, gli ambienti e le distribuzioni.

Metadati predefiniti

Quando si creano o si aggiornano API, ambienti e distribuzioni nel centro API, si impostano determinate proprietà predefinite dei metadati, ad esempio il tipo di API (REST, WSDL e così via).

Le tabelle seguenti elencano i metadati predefiniti forniti per le entità del Centro API di Azure. Per informazioni dettagliate, vedere le informazioni di riferimento sull'API REST del Centro API. Le tabelle non includono proprietà standard di Azure, ad esempio identificatori di risorsa, titoli di visualizzazione e descrizioni. Non tutte le proprietà sono obbligatorie.

API

Metadati UFX Descrizione Valori di esempio
kind tipo (tipo) di API REST, SOAP, GraphQL
fase del ciclo di vita fase del ciclo di vita di sviluppo dell'API progettazione, sviluppo
Licenza informazioni sulla licenza per l'API Identificatore SPDX, collegamento al testo della licenza
documentazione esterna sito per la documentazione esterna per l'API URL che punta alla documentazione
informazioni di contatto punti di contatto per l'API indirizzo di posta elettronica, nome, URL
condizioni per il servizio condizioni di servizio per l'API URL che punta alle condizioni per il servizio

Ambienti

Metadati UFX Descrizione Valori di esempio
kind tipo (tipo) di ambiente produzione, gestione temporanea, sviluppo
server informazioni sul server dell'ambiente tipo e URL che puntano al server dell'ambiente
tipo di server tipo di server di ambiente server Gestione API, server Kubernetes, server Apigee
onboarding informazioni sull'onboarding per l'ambiente istruzioni e URL che puntano al portale per sviluppatori dell'ambiente

Deployments

Metadati UFX Descrizione Valori di esempio
server informazioni sul server della distribuzione URL che punta al server di distribuzione
state stato della distribuzione attivo, inattivo

Metadati personalizzati

Definire metadati personalizzati usando il portale di Azure, l'API REST del Centro API di Azure o l'interfaccia della riga di comando di Azure per organizzare e filtrare API, ambienti e distribuzioni nel centro API. Centro API di Azure supporta metadati personalizzati dei tipi seguenti.

Tipo Descrizione Nome di esempio
boolean true o false IsInternal
number valore numerico YearOfCreation
string valore di testo GitHubRepository
array elenco di valori Tag
scelta predefinita elenco di scelte predefinite Reparto
oggetto oggetto complesso composto da più tipi APIApprover

Importante

Non includere informazioni riservate, riservate o personali nei titoli (nomi) dei metadati definiti. Questi titoli sono visibili nei log di monitoraggio usati da Microsoft per migliorare la funzionalità del servizio. Tuttavia, altri dettagli e valori dei metadati sono i dati dei clienti protetti.

Assegnare metadati alle entità

Le proprietà dei metadati personalizzate possono essere assegnate alle API, agli ambienti o alle distribuzioni nel centro API. Ad esempio, definire e assegnare metadati di reparto alle API, in modo che quando viene registrata un'API o venga aggiunta una nuova versione dell'API, viene specificato il reparto responsabile dell'API.

Se assegnato a un'entità, i metadati sono facoltativi o obbligatori. Ad esempio, potrebbe essere necessario impostare i metadati del reparto solo per le API, ma consentire a YearOfCreation di essere metadati facoltativi per gli ambienti.

Nota

  • Definire metadati personalizzati in qualsiasi momento e applicarli alle API e ad altre entità nel centro API.
  • Dopo aver definito metadati personalizzati, è possibile modificarne l'assegnazione in un'entità, ad esempio da obbligatoria a facoltativa per le API.
  • È possibile modificare i valori dei metadati, ma non è possibile eliminare o modificare il tipo di metadati personalizzati attualmente impostati nelle API, negli ambienti e nelle distribuzioni. Annullare prima di tutto l'assegnazione dei metadati personalizzati dalle entità e quindi eliminarli o modificarli.

Usare i metadati per la governance

Usare metadati predefiniti e personalizzati per organizzare le API, gli ambienti e le distribuzioni nel centro API. Ad esempio:

  • Applicare gli standard di governance nell'organizzazione richiedendo l'impostazione di determinati metadati per API, ambienti e distribuzioni.

  • Cercare e filtrare le API nel centro API in base ai valori dei metadati. È possibile filtrare direttamente nella pagina API nel portale di Azure oppure usare l'API REST del Centro API di Azure o l'interfaccia della riga di comando di Azure per eseguire query sulle API in base ai valori di determinati metadati.

    Screenshot delle API di filtro nel portale.