Použití metadat pro zásady správného řízení rozhraní API

Článek
05/02/2024

Tento článek obsahuje základní informace o metadatech a jeho použití pro zásady správného řízení rozhraní API ve službě Azure API Center. Definujete a nastavíte metadata pro uspořádání a filtrování rozhraní API a dalších entit v centru rozhraní API. Metadata můžou být sestavená nebo vlastní a můžete vyvíjet schéma metadat, které vynucuje konzistenci napříč rozhraními API, prostředími a nasazeními.

Integrovaná metadata

Při vytváření nebo aktualizaci rozhraní API, prostředí a nasazení v centru rozhraní API nastavíte určité předdefinované vlastnosti metadat, jako je typ rozhraní API (REST, WSDL atd.).

Následující tabulky uvádějí předdefinovaná metadata poskytovaná pro entity Azure API Center. Podrobnosti najdete v referenčních informacích k rozhraní REST API služby API Center. Tabulky nezahrnují standardní vlastnosti Azure, jako jsou identifikátory prostředků, zobrazované názvy a popisy. Nejsou vyžadovány všechny vlastnosti.

Rozhraní API

Metadata	Popis	Ukázkové hodnoty
kind	kind (typ) rozhraní API	REST, SOAP, GraphQL
fáze životního cyklu	fáze životního cyklu vývoje rozhraní API	návrh, vývoj
license	informace o licencích pro rozhraní API	Identifikátor SPDX, odkaz na text licence
externí dokumentace	web pro externí dokumentaci k rozhraní API	Adresa URL odkazující na dokumentaci
kontaktní informace	kontaktní body pro rozhraní API	e-mailová adresa, jméno, adresa URL
podmínky služby	podmínky služby pro rozhraní API	Adresa URL odkazující na podmínky služby

Prostředí

Metadata	Popis	Ukázkové hodnoty
kind	druh (typ) prostředí	produkční, přípravný, vývoj
server	informace o serveru prostředí	typ a adresa URL odkazující na server prostředí
typ serveru	typ serveru prostředí	Server API Management, server Kubernetes, server Apigee
onboarding	informace o onboardingu pro prostředí	pokyny a adresa URL odkazující na portál pro vývojáře prostředí

Nasazení

Metadata	Popis	Ukázkové hodnoty
server	informace o serveru nasazení	Adresa URL odkazující na server nasazení
state	stav nasazení	aktivní, neaktivní

Vlastní metadata

Definujte vlastní metadata pomocí webu Azure Portal, rozhraní REST API služby Azure API Center nebo Azure CLI, které vám pomůžou uspořádat a filtrovat rozhraní API, prostředí a nasazení ve vašem centru rozhraní API. Azure API Center podporuje vlastní metadata následujících typů.

Typ	Popis	Příklad názvu
boolean	true nebo false	IsInternal
Číslo	číselná hodnota	YearOfCreation
string	textová hodnota	GitHubRepository
pole	seznam hodnot	Značky
integrovaná volba	předdefinovaný seznam voleb	Oddělení
objekt	komplexní objekt složený z více typů	APIApprover

Důležité

Do názvů (názvů) definovaných metadat nezahrnujte žádné citlivé, důvěrné ani osobní údaje. Tyto názvy jsou viditelné v protokolech monitorování, které Microsoft používá ke zlepšení funkčnosti služby. Další podrobnosti a hodnoty metadat jsou však chráněná zákaznická data.

Přiřazení metadat entit

Vlastní vlastnosti metadat se dají přiřadit k rozhraním API, prostředím nebo nasazením v centru rozhraní API. Například definujte a přiřaďte metadata oddělení k rozhraním API, aby se při registraci rozhraní API nebo přidání nové verze rozhraní API zadalo oddělení zodpovědné za rozhraní API.

Pokud je entita přiřazená, metadata jsou volitelná nebo povinná. Můžete například vyžadovat, aby metadata oddělení byla nastavena pouze pro rozhraní API, ale pro prostředí mohla být volitelná metadata YearOfCreation .

Poznámka:

Definujte vlastní metadata kdykoli a platí pro rozhraní API a další entity v centru rozhraní API.
Po definování vlastních metadat můžete změnit jeho přiřazení k entitě, například z požadavku na volitelné pro rozhraní API.
Hodnoty metadat můžete změnit, ale nemůžete odstranit ani změnit typ vlastních metadat, která jsou aktuálně nastavená v rozhraních API, prostředích a nasazeních. Nejprve zrušte přiřazení vlastních metadat od entit a pak je můžete odstranit nebo změnit.