Transformatiebeleid API Management

In dit onderwerp vindt u een naslag voor de volgende API Management beleidsregels. Zie Beleidsregels in API Management voor meer informatie over het toevoegen en configureren van API Management.

Transformatiebeleid

• JSON converteren naar XML: converteert de aanvraag- of antwoord-body van JSON naar XML.

• XML converteren naar JSON: converteert de aanvraag- of antwoord-body van XML naar JSON.

• Tekenreeks in de body zoeken en vervangen: zoekt een aanvraag- of antwoordsubtekenreeks en vervangt deze door een andere subtekenreeks.

• URL's in inhoud maskeren: schrijf koppelingen in de antwoord-body opnieuw (maskers) zodat ze via de gateway naar de equivalente koppeling verwijzen.

• Back-endservice instellen: wijzigt de back-endservice voor een binnenkomende aanvraag.

• Body instellen: hiermee stelt u de bericht body in voor binnenkomende en uitgaande aanvragen.

• HTTP-header instellen: hiermee wijst u een waarde toe aan een bestaand antwoord en/of aanvraagheader of voegt u een nieuw antwoord en/of een aanvraagheader toe.

• Queryreeksparameter instellen: hiermee wordt de waarde van toegevoegd, vervangen of de queryreeksparameter van de aanvraag verwijderd.

• URL herschrijven: converteert een aanvraag-URL van het openbare formulier naar het formulier dat wordt verwacht door de webservice.

• XML transformeren met behulp van een XSLT: hiermee wordt een XSL-transformatie toegepast op XML in de aanvraag- of antwoord body.

JSON converteren naar XML

Het json-to-xml beleid converteert een aanvraag- of antwoord-body van JSON naar XML.

Beleidsverklaring

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

Voorbeeld

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

Elementen

Kenmerken

Gebruik

Dit beleid kan worden gebruikt in de volgende beleidssecties en -scopes.

• Beleidssecties: inkomende, uitgaande, on-error

• Beleidsbereiken: alle scopes

XML converteren naar JSON

Het xml-to-json beleid converteert een aanvraag- of antwoord-body van XML naar JSON. Dit beleid kan worden gebruikt om API's te moderniseren op basis van alleen XML-back-end-webservices.

Beleidsverklaring

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

Voorbeeld

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

Elementen

Kenmerken

Gebruik

Dit beleid kan worden gebruikt in de volgende beleidssecties en -scopes.

• Beleidssecties: inkomende, uitgaande, on-error

• Beleidsbereiken: alle scopes

Tekenreeks in de body zoeken en vervangen

Het find-and-replace beleid zoekt een aanvraag- of antwoordsubtekenreeks en vervangt deze door een andere subtekenreeks.

Beleidsverklaring

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

Voorbeeld

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

Elementen

Kenmerken

Gebruik

Dit beleid kan worden gebruikt in de volgende beleidssecties en -scopes.

• Beleidssecties: inkomende, uitgaande, back-end, on-error

• Beleidsbereiken: alle scopes

URL's in inhoud maskeren

Het redirect-content-urls beleid schrijft koppelingen (maskers) opnieuw in de antwoord-body zodat ze via de gateway naar de equivalente koppeling verwijzen. Gebruik in de sectie uitgaand om antwoord bodykoppelingen opnieuw te schrijven om ze naar de gateway te laten wijzen. Gebruik in de sectie voor binnenkomende gegevens voor een tegenovergestelde werking.

Beleidsverklaring

<redirect-content-urls />

Voorbeeld

<redirect-content-urls />

Elementen

Gebruik

Dit beleid kan worden gebruikt in de volgende beleidssecties en -scopes.

• Beleidssecties: inkomende, uitgaande

• Beleidsbereiken: alle scopes

Back-endservice instellen

Gebruik het beleid om een binnenkomende aanvraag om te leiden naar een andere back-end dan de aanvraag die is opgegeven in de set-backend-service API-instellingen voor die bewerking. Met dit beleid wordt de basis-URL van de back-endservice van de binnenkomende aanvraag gewijzigd in de url die is opgegeven in het beleid.

Beleidsverklaring

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

of

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

Voorbeeld

<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>

In dit voorbeeld routeert het beleid voor de back-endservice aanvragen op basis van de versiewaarde die in de queryreeks wordt doorgegeven aan een andere back-endservice dan de service die is opgegeven in de API.

De basis-URL van de back-endservice wordt in eerste instantie afgeleid van de API-instellingen. De aanvraag-URL https://contoso.azure-api.net/api/partners/15?version=2013-05&subscription-key=abcdef wordt dus de locatie waar de URL van de http://contoso.com/api/10.4/partners/15?version=2013-05&subscription-key=abcdef http://contoso.com/api/10.4/ back-service is die is opgegeven in de API-instellingen.

Wanneer de <> beleidsverklaring wordt toegepast, kan de basis-URL van de back-service opnieuw worden gewijzigd in of , afhankelijk van de waarde van de queryparameter voor de http://contoso.com/api/8.2 http://contoso.com/api/9.1 versieaanvraag. Als de waarde bijvoorbeeld de uiteindelijke "2013-15" aanvraag-URL is, wordt http://contoso.com/api/8.2/partners/15?version=2013-05&subscription-key=abcdef .

Als verdere transformatie van de aanvraag gewenst is, kunnen andere transformatiebeleidsregels worden gebruikt. Als u bijvoorbeeld de versiequeryparameter wilt verwijderen nu de aanvraag wordt doorgeleid naar een versiespecifieke back-end, kan het beleid Queryreeksparameter instellen worden gebruikt om het nu redundante versiekenmerk te verwijderen.

Voorbeeld

<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>

In dit voorbeeld wordt de aanvraag door het beleid gerouteerd naar een service fabric-back-end, met behulp van de queryreeks userId als partitiesleutel en met behulp van de primaire replica van de partitie.

Elementen

Kenmerken

Gebruik

Dit beleid kan worden gebruikt in de volgende beleidssecties en -scopes.

• Beleidssecties: inkomende, back-end

• Beleidsbereiken: alle scopes

Body instellen

Gebruik het set-body beleid om de bericht body in te stellen voor binnenkomende en uitgaande aanvragen. Als u toegang wilt krijgen tot de berichtgedeelte, kunt u de eigenschap of de gebruiken, afhankelijk van of het beleid zich in de sectie voor binnenkomende of uitgaande gegevens in de sectie voor binnenkomende of context.Request.Body uitgaande gegevens context.Response.Body voordeed.

Zie de secties , en in de tabel context.Request.Body context.Response.Body IMessage Contextvariabele voor meer informatie.

Beleidsverklaring

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

Voorbeelden

Voorbeeld van letterlijke tekst

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

Voorbeeld van toegang tot de body als een tekenreeks. Houd er rekening mee dat we de oorspronkelijke aanvraag body behouden, zodat we deze later in de pijplijn kunnen openen.

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

Voorbeeld van toegang tot de body als een JObject. Houd er rekening mee dat omdat we de oorspronkelijke aanvraag niet reserveren, dit later in de pijplijn tot een uitzondering leidt.

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

Antwoord filteren op basis van product

In dit voorbeeld ziet u hoe u inhoud filtert door gegevenselementen te verwijderen uit het antwoord dat is ontvangen van de back-endservice wanneer u het Starter product gebruikt. Zie Cloud Cover Aflevering 177: Meer API Management-functies met Vlad Vinogradsky en fast-forward naar 34:30 voor een demonstratie van het configureren en gebruiken van dit beleid. Begin om 31:50 uur voor een overzicht van de prognose-API voor donkere lucht die wordt gebruikt voor deze demo.

<!-- 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>

Liquid-sjablonen gebruiken met de set-body

Het set-body beleid kan worden geconfigureerd voor het gebruik van de Liquid- templating-taal om de body van een aanvraag of antwoord te transformeren. Dit kan zeer effectief zijn als u de indeling van uw bericht volledig moet wijzigen.

JSON converteren naar SOAP met behulp van een Liquid-sjabloon

<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>

JSON transformeren met behulp van een Liquid-sjabloon

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

Elementen

Eigenschappen

Voor toegang tot informatie over de aanvraag en het antwoord kan de Liquid-sjabloon worden binden aan een contextobject met de volgende eigenschappen:

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

Gebruik

Dit beleid kan worden gebruikt in de volgende beleidssecties en -scopes.

• Beleidssecties: inkomende, uitgaande, back-en

• Beleidsbereiken: alle scopes

HTTP-header instellen

Het beleid wijst een waarde toe aan een bestaand antwoord en/of aanvraagheader of voegt een nieuw antwoord set-header en/of aanvraagheader toe.

Hiermee voegt u een lijst met HTTP-headers in een HTTP-bericht in. Wanneer dit beleid in een binnenkomende pijplijn wordt geplaatst, worden de HTTP-headers voor de aanvraag die wordt doorgegeven aan de doelservice, door dit beleid. Wanneer dit beleid in een uitgaande pijplijn wordt geplaatst, worden met dit beleid de HTTP-headers voor het antwoord dat naar de client van de gateway wordt verzonden,sets uitgevoerd.

Beleidsverklaring

<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>

Voorbeelden

Voorbeeld: koptekst toevoegen, bestaande overschrijven

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

Voorbeeld: header verwijderen

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

Contextinformatie doorsturen naar de back-endservice

In dit voorbeeld ziet u hoe u beleid op API-niveau kunt toepassen om contextinformatie aan de back-endservice op te geven. Zie Cloud Cover Aflevering 177: Meer API Management-functies met Vlad Vinogradsky en fast-forward naar 10:30 voor een demonstratie van het configureren en gebruiken van dit beleid. Om 12:10 is er een demo van het aanroepen van een bewerking in de ontwikkelaarsportal, waar u het beleid op het werk kunt zien.

<!-- 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>

Zie Beleidsexpressie en Contextvariabele voor meer informatie.

Elementen

Eigenschappen

Gebruik

Dit beleid kan worden gebruikt in de volgende beleidssecties en -scopes.

• Beleidssecties: inkomende, uitgaande, back-end, on-error

• Beleidsbereiken: alle scopes

Queryreeksparameter instellen

Met set-query-parameter het beleid wordt de waarde van toegevoegd, vervangen of de queryreeksparameter van de aanvraag verwijderd. Kan worden gebruikt om queryparameters door te geven die worden verwacht door de back-endservice, die optioneel zijn of nooit aanwezig zijn in de aanvraag.

Beleidsverklaring

<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>

Voorbeeld

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

Contextinformatie doorsturen naar de back-endservice

In dit voorbeeld ziet u hoe u beleid op API-niveau kunt toepassen om contextinformatie aan de back-endservice op te geven. Zie Cloud Cover Aflevering 177: Meer API Management-functies met Vlad Vinogradsky en fast-forward naar 10:30 voor een demonstratie van het configureren en gebruiken van dit beleid. Om 12:10 is er een demo van het aanroepen van een bewerking in de ontwikkelaarsportal, waar u het beleid op het werk kunt zien.

<!-- 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>

Zie Beleidsexpressie en Contextvariabele voor meer informatie.

Elementen

Eigenschappen

Gebruik

Dit beleid kan worden gebruikt in de volgende beleidssecties en -scopes.

• Beleidssecties: inkomende, back-end

• Beleidsbereiken: alle scopes

URL herschrijven

Het beleid converteert een aanvraag-URL van het openbare formulier naar het formulier dat wordt verwacht door de rewrite-uri webservice, zoals wordt weergegeven in het volgende voorbeeld.

• Openbare URL - http://api.example.com/storenumber/ordernumber

• Aanvraag-URL - http://api.example.com/v2/US/hardware/storenumber&ordernumber?City&State

  Dit beleid kan worden gebruikt wanneer een menselijke url en/of browservriendelijke URL moet worden omgezet in de URL-indeling die door de webservice wordt verwacht. Dit beleid hoeft alleen te worden toegepast bij het beschikbaar maken van een alternatieve URL-indeling, zoals schone URL's, RESTful-URL's, gebruiksvriendelijke URL's of URL's die uitsluitend structurele URL's zijn die geen queryreeks bevatten en in plaats daarvan alleen het pad van de resource bevatten (na het schema en de autoriteit). Dit wordt vaak gedaan voor vormgeving, bruikbaarheid of zoekmachineoptimalisatie (SEO).

Beleidsverklaring

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

Voorbeeld

<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 -->

Elementen

Kenmerken

Gebruik

Dit beleid kan worden gebruikt in de volgende beleidssecties en -scopes.

• Beleidssecties: inkomende

• Beleidsbereiken: alle scopes

XML transformeren met behulp van een XSLT

Het Transform XML using an XSLT beleid past een XSL-transformatie toe op XML in de aanvraag- of antwoord-body.

Beleidsverklaring

<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>

Voorbeeld

<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>

Elementen

Gebruik

Dit beleid kan worden gebruikt in de volgende beleidssecties en -scopes.

• Beleidssecties: inkomende, uitgaande

• Beleidsbereiken: alle scopes

Volgende stappen

Zie de volgende onderwerpen voor meer informatie:

• Beleidsregels in API Management
• Beleidsverwijzing voor een volledige lijst met beleidsverklaringen en de instellingen
• Voorbeelden van beleid