Välja rätt API Management-princip

  • 7 minuter

Du kan använda API Management-principer till att styra beteendet för ett distribuerat API utan att skriva om dess kod.

I brädspelsföretaget har du en uppsättning API:er som gör att partnerorganisationer kan få prisuppskattningar, personal kan kontrollera lagernivåer och kunder kan skapa beställningar. Du vill åtgärda ett visst problem med prestanda och undersöka vad mer du kan uppnå med principer.

Först tittar vi på vad du kan göra med hjälp av principer.

Vad är principer?

I Azure API Management kan administratörer använda principer för att ändra beteendet för API:er via konfiguration. De primära funktionerna och beteendet för ett API utformas av utvecklarna som skriver koden. Administratörer kan dock använda principer för att ange gränser, konvertera svarsformat eller framtvinga säkerhetskrav. I den här modulen koncentrerar vi oss på att använda principer för att konfigurera och kontrollera en cache.

Principer består av enskilda instruktioner som körs i ordning. Principdokumenten är XML-strukturer som innehåller element som du kan använda för att styra API:ets beteende.

När körs principer?

I Azure API Management körs principer vid fyra olika tidpunkter:

  • Inkommande: Dessa principer körs när en begäran tas emot från en klient.
  • Serverdel: Dessa principer körs innan en begäran vidarebefordras till ett hanterat API.
  • Utgående: Dessa principer körs innan ett svar skickas till en klient.
  • Vid fel: Dessa principer körs när ett undantag utlöses.

I princip-XML finns det en separat tagg för var och en av dessa körningstider:

<policies>
    <inbound>
        <base />
        <check-header name="Authorization" failed-check-httpcode="401" failed-check-error-message="Not authorized" ignore-case="false">
        </check-header>
    </inbound>
    <backend>
        <base />
    </backend>
    <outbound>
        <base />
        <json-to-xml apply="always" consider-accept-header="false" parse-date="false" />
    </outbound>
    <on-error>
        <base />
    </on-error>
</policies>

I det här exemplet ser du att principen kontrollerar inkommande begäranden för en rubrik som heter Authorization (Auktorisering). Om en sådan rubrik inte finns visar principen ett felmeddelande.

Den här principen översätter även alla utgående svar i JSON-format till XML.

Principomfattningar

Omfånget för en princip avgör hur brett principen tillämpas. Följande är principomfattningar som du kan välja mellan:

  • Global
  • Produkt
  • API
  • Åtgärd

Global

Principer som tillämpas med globalt omfång påverkar alla API:er i API Management-instansen.

Om du vill använda det globala omfånget går du till fönstret API Management-tjänsten i det vänstra menyfönstret. Under API Management väljer du API:er och sedan Alla API:er i menyfönstret i mitten. Välj + Lägg till princip i avsnittet Inkommande bearbetning eller Utgående bearbetning för att visa principer som du kan lägga till i det omfånget.

Screenshot of the All APIs scope in the portal.

Från de tillgängliga valen gör du ett val för att starta en guide som hjälper dig att lägga till principen med rätt syntax:

Screenshot of the All APIs scope to add policy in the portal.

Du kan också öppna XML-redigeraren direkt genom att välja taggsymbolen</>i avsnitten Inkommande bearbetning, Utgående bearbetning eller Serverdel. Den principredigerare som visas innehåller XML-standardinnehållet. Till höger väljer du Visa kodfragment för att hitta genvägar som lägger till principer:

Screenshot of the All APIs scope editor in the portal.

Produkt

I API Management kan du sätta ihop ett eller flera API:er till en enskild produkt och sedan hantera åtkomst till den produkten som en enskild entitet. Principer som tillämpas på produktomfånget påverkar alla API:er i den produkten. API:er i andra produkter påverkas inte. När du hanterar en produkt i Azure-portalen väljer du fönstret Principer för att lägga till principer via en guidad guide eller med hjälp av XML-principredigeraren:

Screenshot of the product scope editor in the portal.

API

Principer som tillämpas i API-omfånget påverkar bara ett enda API. Om du vill ange en princip i API-omfånget går du till startsidan för API Management, väljer API:er och väljer sedan det API som du vill hantera. Under fliken Design väljer du Slutligen Alla åtgärder. Du kan ange principer för inkommande, utgående eller serverdel som gäller för alla åtgärder i api:et:

Screenshot of the API scope in the portal.

Åtgärd

Principer som tillämpas i åtgärdsomfånget påverkar endast en enskild åtgärd i API:et. I exemplet nedan har administratören valt åtgärden GetSpeaker i Demo Conference-API:et och kan ange inkommande principer, utgående principer eller serverdelsprinciper som endast gäller för den åtgärden:

Screenshot of the operation scope in the portal.

I vilken ordning tillämpas principer?

Du kan använda taggen <base /> för att avgöra när principer från ett högre omfång tillämpas. Ta den här principen som exempel. Den tillämpas i API-omfånget:

<policies>
    <inbound>
        <base />
        <find-and-replace from="game" to="board game" />
    </inbound>
</policies>

Eftersom taggen <base> visas ovanför taggen <find-and-replace> tillämpar Azure API Management principer från de globala omfången och produktomfattningarna först och kör sedan principen find-and-replace.

Principer som används ofta

Nu ska vi undersöka några saker som du kan göra med principer i API Management. Vi introducerar några av de vanligaste principerna och du kan gå till API Management-dokumentationen för en fullständig lista och exempel.

Principer för att begränsa åtkomst

Det finns flera principer som du kan använda för att förhindra eller begränsa åtkomsten till ett API eller dess åtgärder. Till exempel:

Använd principen Kontrollera HTTP-huvud för att söka efter en egenskap i ett HTTP-huvud. Om egenskapen inte hittas släpper Azure API Management begäran.

Principen Limit call rate by subscription (Begränsa anropsfrekvens efter prenumeration) begränsar antalet anrop som kan komma från en enskild API-prenumeration. Den här principen kan se till att användare från en prenumeration inte använder all bandbredd.

Om du vill begränsa antalet anrop som kommer med en enda åtkomstnyckel använder du principen Limit call rate by key (Begränsa anropsfrekvens efter nyckel).

Om du vill tillåta eller neka anrop från specifika IP-adresser eller IP-adressintervall använder du principen Restrict caller IP's (Begränsa anroparens IP). Det här sättet att begränsa åtkomst fungerar som de IP-adressbegränsningar som du kan tillämpa på en brandvägg.

Principer för autentisering

Med flera principer kan du styra autentiseringen. Till exempel:

Använd principen Authenticate with Basic (Autentisera med grundläggande ) för att aktivera autentisering i klartext. Den här typen av autentisering stöds i stort sett, men kom ihåg att du bör skydda den med SSL-kryptering. Annars kan en skadlig attack fånga upp autentiseringsuppgifterna när de passerar nätverket.

Använd principen Authenticate with client certificate (Autentisera med klientcertifikat) om du vill att klienter ska kunna autentisera genom att ange ett klientcertifikat.

Principer mellan domäner

Korsdomänbegäranden betraktas som ett säkerhetshot och nekas av webbläsare och API:er. De kan dock vara önskvärda för specifika åtgärder, och MED API Management-principer kan du tillåta dem på ett säkert sätt.

Använd principen Allow cross-domain calls (Tillåt korsdomänanrop) om du vill tillåta anrop från Adobe Flash och Silverlight. Om ditt API eller dina klientappar är beroende av Cross-Origin Resource Sharing (CORS) använder du CORS-principen för att tillåta dem.

En del AJAX-kod, som körs i webbläsare, använder JSON med utfyllnad för att göra korsdomänanrop på ett säkert sätt. Använd JSONP-principen för att tillåta klienter att använda den här tekniken.

Transformeringsprinciper

Ofta är det bra att ändra format eller innehåll för ett svar från ett hanterat API. Du kan göra det med flera principer. Till exempel:

Om du vill konvertera till och från JSON och XML använder du principerna Convert JSON to XML (Konvertera JSON till XML) och Convert XML to JSON (Konvertera XML till JSON). Dessa principer hjälper ofta till att göra flera API:er i en produkt konsekvent. De kan också ta bort behovet av att koda om ett API när en app förväntar sig ett svar i ett visst format.

Ibland vill du behålla ett svar i XML men ändra dess schema. I sådana fall kan du använda principen Transform XML (Transformera XML) för att tillämpa en XSLT-mall.

Använd Find and replace string in body (Sök och ersätt sträng i brödtext) för att köra ett strängutbyte. Om ett varumärke till exempel har ändrats kan du använda den här principen för att säkerställa att ändringen återspeglas i alla svar, även om underliggande data fortfarande innehåller referenser till det gamla namnet.

Principen Mask URLs in content (Maskera URL:er i innehåll) skriva om alla länkar i svarstexten så att de pekar på en annan plats. Den här principen är användbar när en webbplats eller ett webb-API har flyttats.

Använd principen Set body (Ange brödtext) för att ange meddelandetexten för inkommande och utgående begäranden.

Om du vill ändra en inkommande HTTP-begäran eller ett utgående svar kan du använda flera olika principer. Om du vill lägga till objekt i ett befintligt svar eller i begärandehuvudet använder du principen Set HTTP header (Ange HTTP-huvud). Om du behöver ändra de frågesträngar som visas efter frågetecknet i URL:en använder du principen Set query string parameter (Ange frågesträngsparameter). Om en offentlig URL som en användare har begärt måste mappas till en annan intern plats kan principen Rewrite URL (Skriv om URL) utföra konverteringen både inkommande och utgående.

Avancerade principer

Dessa principer kan användas i scenarier när du vill ha ett beteende som inte är standard.

Om du till exempel endast vill tillämpa en princip när svaret klarar ett visst test använder du principen Control flow (Kontrollflöde).

Använd principen Forward request (Vidarekoppla begäran) för att vidarebefordra en begäran till en serverdelsserver.

Om du vill kontrollera vad som händer när en åtgärd misslyckas använder du principen Retry (Försök igen). Principinstruktioner som omges av Återförsök körs upprepade gånger tills ett villkor uppfylls. Körningen upprepas vid de angivna tidsintervallen tills värdet för antalet nya försök har nåtts.

Principen Send one-way request (Skicka envägsbegäran) kan skicka en begäran till en URL utan att vänta på ett svar.

Om du vill lagra ett värde för användning i en senare beräkning eller ett test använder du principen Set variable (Ange variabel) för att bevara ett värde i en namngiven variabel.