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.
