Omvandlingsprinciper för API Management

Det här avsnittet innehåller en referens för följande API Management principer. Information om hur du lägger till och konfigurerar principer finns i Principer i API Management.

Transformeringsprinciper

• Konvertera JSON till XML – Konverterar begäran eller svarstext från JSON till XML.

• Konvertera XML till JSON – Konverterar begäran eller svarstext från XML till JSON.

• Hitta och ersätt sträng i brödtext – Söker efter en understräng för begäran eller svar och ersätter den med en annan delsträng.

• Maskera URL:er i innehåll – Åter skrivningar (maskerar) länkar i svarstexten så att de pekar på motsvarande länk via gatewayen.

• Ange servertjänst – Ändrar servertjänst för en inkommande begäran.

• Ange brödtext – Anger meddelandetexten för inkommande och utgående begäranden.

• Ange HTTP-huvud – Tilldelar ett värde till ett befintligt svar och/eller begärandehuvud eller lägger till ett nytt svar och/eller begärandehuvud.

• Ange frågesträngsparameter – Lägger till, ersätter värdet för eller tar bort frågesträngsparametern för begäran.

• Omskrivnings-URL – Konverterar en begärande-URL från dess offentliga formulär till det formulär som förväntas av webbtjänsten.

• Transformera XML med hjälp av en XSLT – Tillämpar en XSL-transformering på XML i begäran eller svarstexten.

Konvertera JSON till XML

Principen json-to-xml konverterar en begäran eller svarstext från JSON till XML.

Principutdrag

<json-to-xml apply="always | content-type-json" consider-accept-header="true | false" parse-date="true | false"/>

Exempel

<policies>
    <inbound>
        <base />
    </inbound>
    <outbound>
        <base />
        <json-to-xml apply="always" consider-accept-header="false" parse-date="false"/>
    </outbound>
</policies>

Element

Attribut

Användning

Den här principen kan användas i följande principavsnitt och omfång.

• Principavsnitt: inkommande, utgående, vid fel

• Principomfång: alla omfång

Konvertera XML till JSON

Principen xml-to-json konverterar en begäran eller svarstext från XML till JSON. Den här principen kan användas för att modernisera API:er baserat på XML-baserade backend-webbtjänster.

Principutdrag

<xml-to-json kind="javascript-friendly | direct" apply="always | content-type-xml" consider-accept-header="true | false"/>

Exempel

<policies>
    <inbound>
        <base />
    </inbound>
    <outbound>
        <base />
        <xml-to-json kind="direct" apply="always" consider-accept-header="false" />
    </outbound>
</policies>

Element

Attribut

Användning

Den här principen kan användas i följande principavsnitt och omfång.

• Principavsnitt: inkommande, utgående, vid fel

• Principomfång: alla omfång

Hitta och ersätta sträng i brödtext

Principen find-and-replace hittar en understräng för begäran eller svar och ersätter den med en annan delsträng.

Principutdrag

<find-and-replace from="what to replace" to="replacement" />

Exempel

<find-and-replace from="notebook" to="laptop" />

Element

Attribut

Användning

Den här principen kan användas i följande principavsnitt och omfång.

• Principavsnitt: inkommande, utgående, backend, vid fel

• Principomfång: alla omfång

Maskera URL:er i innehåll

Principen redirect-content-urls skriver om (maskerar) länkar i svarstexten så att de pekar på motsvarande länk via gatewayen. Använd i avsnittet utgående för att skriva om svarstextlänkar så att de pekar på gatewayen. Använd i avsnittet inkommande för en motsatt effekt.

Principutdrag

<redirect-content-urls />

Exempel

<redirect-content-urls />

Element

Användning

Den här principen kan användas i följande principavsnitt och omfång.

• Principavsnitt: inkommande, utgående

• Principomfång: alla omfång

Ange backend-tjänst

Använd principen set-backend-service för att omdirigera en inkommande begäran till en annan server än den som anges i API-inställningarna för åtgärden. Den här principen ändrar serverdelstjänstens bas-URL för den inkommande begäran till den som anges i principen.

Principutdrag

<set-backend-service base-url="base URL of the backend service" />

eller

<set-backend-service backend-id="identifier of the backend entity specifying base URL of the backend service" />

Exempel

<policies>
    <inbound>
        <choose>
            <when condition="@(context.Request.Url.Query.GetValueOrDefault("version") == "2013-05")">
                <set-backend-service base-url="http://contoso.com/api/8.2/" />
            </when>
            <when condition="@(context.Request.Url.Query.GetValueOrDefault("version") == "2014-03")">
                <set-backend-service base-url="http://contoso.com/api/9.1/" />
            </when>
        </choose>
        <base />
    </inbound>
    <outbound>
        <base />
    </outbound>
</policies>

I det här exemplet dirigerar den angivna principen för backend-tjänsten begäranden baserat på versionsvärdet som skickas i frågesträngen till en annan backend-tjänst än den som anges i API:et.

Ursprungligen härleds bas-URL:en för backend-tjänsten från API-inställningarna. Så url:en https://contoso.azure-api.net/api/partners/15?version=2013-05&subscription-key=abcdef för begäran blir där är den url för http://contoso.com/api/10.4/partners/15?version=2013-05&subscription-key=abcdef http://contoso.com/api/10.4/ backend-tjänsten som anges i API-inställningarna.

När <> väljer principsatsen tillämpas kan den grundläggande URL:en för backend-tjänsten ändras antingen till eller , beroende på värdet för frågeparametern för http://contoso.com/api/8.2 http://contoso.com/api/9.1 versionsbegäran. Om värdet till exempel är den slutliga "2013-15" begärande-URL:en blir http://contoso.com/api/8.2/partners/15?version=2013-05&subscription-key=abcdef .

Om ytterligare omvandling av begäran önskas kan andra transformeringsprinciper användas. Om du till exempel vill ta bort frågeparametern för versionen nu när begäran dirigeras till en versionsspecifik backend kan du använda principen Ange frågesträngsparameter för att ta bort attributet för den nu redundanta versionen.

Exempel

<policies>
    <inbound>
        <set-backend-service backend-id="my-sf-service" sf-partition-key="@(context.Request.Url.Query.GetValueOrDefault("userId","")" sf-replica-type="primary" />
    </inbound>
    <outbound>
        <base />
    </outbound>
</policies>

I det här exemplet dirigerar principen begäran till en Service Fabric-backend med hjälp av userId-frågesträngen som partitionsnyckel och använder den primära repliken av partitionen.

Element

Attribut

Användning

Den här principen kan användas i följande principavsnitt och omfång.

• Principavsnitt: inkommande, backend

• Principomfång: alla omfång

Ange brödtext

Använd principen set-body för att ange meddelandetexten för inkommande och utgående begäranden. Om du vill komma åt meddelandetexten kan du använda egenskapen eller , beroende på om principen finns i context.Request.Body context.Response.Body avsnittet inkommande eller utgående.

Mer information finns i context.Request.Body avsnitten context.Response.Body , och i IMessage tabellen Kontextvariabel.

Principutdrag

<set-body>new body value as text</set-body>

Exempel

Exempel på literal text

<set-body>Hello world!</set-body>

Exempel på hur du kommer åt brödtexten som en sträng. Observera att vi bevarar den ursprungliga begärandetexten så att vi kan komma åt den senare i pipelinen.

<set-body>
@{ 
    string inBody = context.Request.Body.As<string>(preserveContent: true); 
    if (inBody[0] =='c') { 
        inBody[0] = 'm'; 
    } 
    return inBody; 
}
</set-body>

Exempel på åtkomst till brödtexten som ett JObject. Observera att eftersom vi inte reserverar den ursprungliga begärandetexten resulterar åtkomst till den senare i pipelinen i ett undantag.

<set-body> 
@{ 
    JObject inBody = context.Request.Body.As<JObject>(); 
    if (inBody.attribute == <tag>) { 
        inBody[0] = 'm'; 
    } 
    return inBody.ToString(); 
} 
</set-body>

Filtrera svar baserat på produkt

Det här exemplet visar hur du utför innehållsfiltrering genom att ta bort dataelement från svaret från backend-tjänsten när du använder Starter produkten. En demonstration av hur du konfigurerar och använder den här principen finns i Cloud CoverAvsnitt 177: Fler API Management-funktioner med Vlad Vinogradsky och fast-forward till 34:30. Börja kl. 31:50 för att se en översikt över DARK Sky Forecast-API:et som används för den här demonstrationen.

<!-- Copy this snippet into the outbound section to remove a number of data elements from the response received from the backend service based on the name of the api product -->
<choose>
  <when condition="@(context.Response.StatusCode == 200 && context.Product.Name.Equals("Starter"))">
    <set-body>@{
        var response = context.Response.Body.As<JObject>();
        foreach (var key in new [] {"minutely", "hourly", "daily", "flags"}) {
          response.Property (key).Remove ();
        }
        return response.ToString();
      }
    </set-body>
  </when>
</choose>

Använda Liquid-mallar med uppsättningstext

Principen set-body kan konfigureras att använda mallspråket Liquid för att transformera brödtexten i en begäran eller ett svar. Detta kan vara mycket effektivt om du behöver omforma formatet för ditt meddelande helt.

Konvertera JSON till SOAP med hjälp av en Liquid-mall

<set-body template="liquid">
    <soap:Envelope xmlns="http://tempuri.org/" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
        <soap:Body>
            <GetOpenOrders>
                <cust>{{body.getOpenOrders.cust}}</cust>
            </GetOpenOrders>
        </soap:Body>
    </soap:Envelope>
</set-body>

Transformera JSON med en Liquid-mall

{
"order": {
    "id": "{{body.customer.purchase.identifier}}",
    "summary": "{{body.customer.purchase.orderShortDesc}}"
    }
}

Element

Egenskaper

Mallen Liquid kan binda till ett kontextobjekt med följande egenskaper för att komma åt information om begäran och svaret:

context.
    Request.
        Url
        Method
        OriginalMethod
        OriginalUrl
        IpAddress
        MatchedParameters
        HasBody
        ClientCertificates
        Headers

    Response.
        StatusCode
        Method
        Headers
Url.
    Scheme
    Host
    Port
    Path
    Query
    QueryString
    ToUri
    ToString

OriginalUrl.
    Scheme
    Host
    Port
    Path
    Query
    QueryString
    ToUri
    ToString

Användning

Den här principen kan användas i följande principavsnitt och omfång.

• Principavsnitt: inkommande, utgående, backend

• Principomfång: alla omfång

Ange HTTP-huvud

Principen set-header tilldelar ett värde till ett befintligt svar och/eller begärandehuvud eller lägger till ett nytt svars- och/eller begärandehuvud.

Infogar en lista med HTTP-huvuden i ett HTTP-meddelande. När den placeras i en inkommande pipeline anger den här principen HTTP-huvudena för begäran som skickas till måltjänsten. När den placeras i en utgående pipeline anger den här principen HTTP-huvudena för svaret som skickas till gatewayens klient.

Principutdrag

<set-header name="header name" exists-action="override | skip | append | delete">
    <value>value</value> <!--for multiple headers with the same name add additional value elements-->
</set-header>

Exempel

Exempel – lägga till rubrik, åsidosätt befintlig

<set-header name="some header name" exists-action="override">
    <value>20</value>
</set-header>

Exempel – ta bort sidhuvud

 <set-header name="some header name" exists-action="delete" />

Vidarebefordra kontextinformation till backend-tjänsten

Det här exemplet visar hur du tillämpar en princip på API-nivå för att ange kontextinformation till backend-tjänsten. En demonstration av hur du konfigurerar och använder den här principen finns i Cloud CoverAvsnitt 177: Fler API Management-funktioner med Vlad Vinogradsky och fast-forward till 10:30. Kl. 12:10 finns en demonstration av hur du anropar en åtgärd i utvecklarportalen där du kan se principen på jobbet.

<!-- Copy this snippet into the inbound element to forward some context information, user id and the region the gateway is hosted in, to the backend service for logging or evaluation -->
<set-header name="x-request-context-data" exists-action="override">
  <value>@(context.User.Id)</value>
  <value>@(context.Deployment.Region)</value>
</set-header>

Mer information finns i Principuttryck och Kontextvariabel.

Element

Egenskaper

Användning

Den här principen kan användas i följande principavsnitt och omfång.

• Principavsnitt: inkommande, utgående, backend, on-error

• Principomfång: alla omfång

Ange frågesträngsparameter

Principen set-query-parameter lägger till, ersätter värdet för eller tar bort frågesträngparametern för förfrågningar. Kan användas för att skicka frågeparametrar som förväntas av backend-tjänsten som är valfria eller aldrig finns i begäran.

Principsats

<set-query-parameter name="param name" exists-action="override | skip | append | delete">
    <value>value</value> <!--for multiple parameters with the same name add additional value elements-->
</set-query-parameter>

Exempel

<set-query-parameter name="api-key" exists-action="skip">
  <value>12345678901</value>
</set-query-parameter>

Vidarebefordra kontextinformation till backend-tjänsten

Det här exemplet visar hur du tillämpar en princip på API-nivå för att ange kontextinformation till backend-tjänsten. En demonstration av hur du konfigurerar och använder den här principen finns i Cloud CoverAvsnitt 177: Fler API Management-funktioner med Vlad Vinogradsky och fast-forward till 10:30. Kl. 12:10 finns det en demonstration av att anropa en åtgärd i utvecklarportalen där du kan se principen på jobbet.

<!-- Copy this snippet into the inbound element to forward a piece of context, product name in this example, to the backend service for logging or evaluation -->
<set-query-parameter name="x-product-name" exists-action="override">
  <value>@(context.Product.Name)</value>
</set-query-parameter>

Mer information finns i Principuttryck och Kontextvariabel.

Element

Egenskaper

Användning

Den här principen kan användas i följande principavsnitt och omfång.

• Principavsnitt: inkommande, backend

• Principomfång: alla omfång

Skriva om URL

Principen konverterar en begärande-URL från dess offentliga formulär till det formulär som förväntas av rewrite-uri webbtjänsten, som du ser i följande exempel.

• Offentlig URL – http://api.example.com/storenumber/ordernumber

• Begärande-URL – http://api.example.com/v2/US/hardware/storenumber&ordernumber?City&State

  Den här principen kan användas när en mänsklig och/eller webbläsarvänlig URL ska omvandlas till det URL-format som förväntas av webbtjänsten. Den här principen behöver bara tillämpas när du exponerar ett alternativt URL-format, till exempel rena URL:er, RESTful-URL:er, användarvänliga URL:er eller SEO-användarvänliga URL:er som är rent strukturella URL:er som inte innehåller en frågesträng och i stället bara innehåller resursens sökväg (efter schemat och behörigheten). Detta görs ofta för estetiskt syfte, användbarhet eller sökmotoroptimering (SEO).

Principsats

<rewrite-uri template="uri template" copy-unmatched-params="true | false" />

Exempel

<policies>
    <inbound>
        <base />
        <rewrite-uri template="/v2/US/hardware/{storenumber}&{ordernumber}?City=city&State=state" />
    </inbound>
    <outbound>
        <base />
    </outbound>
</policies>

<!-- Assuming incoming request is /get?a=b&c=d and operation template is set to /get?a={b} -->
<policies>
    <inbound>
        <base />
        <rewrite-uri template="/put" />
    </inbound>
    <outbound>
        <base />
    </outbound>
</policies>
<!-- Resulting URL will be /put?c=d -->

<!-- Assuming incoming request is /get?a=b&c=d and operation template is set to /get?a={b} -->
<policies>
    <inbound>
        <base />
        <rewrite-uri template="/put" copy-unmatched-params="false" />
    </inbound>
    <outbound>
        <base />
    </outbound>
</policies>
<!-- Resulting URL will be /put -->

Element

Attribut

Användning

Den här principen kan användas i följande principavsnitt och omfång.

• Principavsnitt: inkommande

• Principomfång: alla omfång

Transformera XML med hjälp av en XSLT

Principen Transform XML using an XSLT tillämpar en XSL-transformering på XML i begäran eller svarstexten.

Principutdrag

<xsl-transform>
    <parameter name="User-Agent">@(context.Request.Headers.GetValueOrDefault("User-Agent","non-specified"))</parameter>
    <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
        <xsl:output method="xml" indent="yes" />
        <xsl:param name="User-Agent" />
        <xsl:template match="* | @* | node()">
            <xsl:copy>
                <xsl:if test="self::* and not(parent::*)">
                    <xsl:attribute name="User-Agent">
                        <xsl:value-of select="$User-Agent" />
                    </xsl:attribute>
                </xsl:if>
                <xsl:apply-templates select="* | @* | node()" />
            </xsl:copy>
        </xsl:template>
    </xsl:stylesheet>
  </xsl-transform>

Exempel

<policies>
  <inbound>
      <base />
  </inbound>
  <outbound>
      <base />
      <xsl-transform>
          <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
            <xsl:output omit-xml-declaration="yes" method="xml" indent="yes" />
            <!-- Copy all nodes directly-->
            <xsl:template match="node()| @*|*">
                <xsl:copy>
                    <xsl:apply-templates select="@* | node()|*" />
                </xsl:copy>
            </xsl:template>
          </xsl:stylesheet>
    </xsl-transform>
  </outbound>
</policies>

Element

Användning

Den här principen kan användas i följande principavsnitt och omfång.

• Principavsnitt: inkommande, utgående

• Principomfång: alla omfång

Nästa steg

Mer information finns i följande avsnitt:

• Principer i API Management
• Principreferens för en fullständig lista över principutdrag och deras inställningar
• Principexempel