Zásady transformace ve službě API Management

Toto téma obsahuje referenční informace o následujících API Management zásad. Informace o přidávání a konfiguraci zásad najdete v tématu Zásady v API Management.

Zásady transformace

• Převod JSON na XML – Převede text požadavku nebo odpovědi z JSON na XML.

• Převod XML na JSON – převede text požadavku nebo odpovědi z XML na JSON.

• Vyhledání a nahrazení řetězce v textu – najde podřetězec požadavku nebo odpovědi a nahradí ho jiným podřetězec.

• Mask urls in content (Maskovat adresy URL v obsahu) – přepíše (masky) odkazy v textu odpovědi tak, aby odkazují na ekvivalentní odkaz přes bránu.

• Nastavení back-endové služby – Změní back-endovou službu pro příchozí požadavek.

• Nastavte text – Nastaví text zprávy pro příchozí a odchozí požadavky.

• Nastavení hlavičky HTTP – Přiřadí hodnotu existující odpovědi nebo hlavičce požadavku nebo přidá novou odpověď nebo hlavičku požadavku.

• Nastavení parametru řetězce dotazu – Přidá, nahradí hodnotu parametru řetězce dotazu požadavku nebo ho odstraní.

• Přepsat adresu URL – převede adresu URL požadavku z veřejného formuláře na formulář očekávaný webovou službou.

• Transformovat XML pomocí XSLT – Použije transformaci XSL na XML v textu požadavku nebo odpovědi.

Převod JSON na XML

Zásada json-to-xml převede text požadavku nebo odpovědi z FORMÁTU JSON na XML.

Prohlášení o zásadách

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

Příklad

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

Elementy

Atributy

Využití

Tuto zásadu můžete použít v následujících oddílech zásad a oborech.

• Oddíly zásad: příchozí, odchozí, on-error

• Obory zásad: všechny obory

Převod XML na JSON

Zásada xml-to-json převede text požadavku nebo odpovědi z XML na JSON. Tuto zásadu je možné použít k modernizaci rozhraní API na základě back-endových webových služeb pouze xml.

Prohlášení o zásadách

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

Příklad

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

Elementy

Atributy

Využití

Tuto zásadu můžete použít v následujících oddílech zásad a oborech.

• Oddíly zásad: příchozí, odchozí, on-error

• Obory zásad: všechny obory

Vyhledání a nahrazení řetězce v textu

Zásada find-and-replace najde podřetězec požadavku nebo odpovědi a nahradí ho jiným dílčím řetězcem.

Prohlášení o zásadách

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

Příklad

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

Elementy

Atributy

Využití

Tyto zásady se dají použít v následujících oddílech a oborechzásad.

• Oddíly zásad: příchozí, odchozí, back-end, zapnutá chyba

• Obory zásad: všechny rozsahy

Maskování adres URL v obsahu

redirect-content-urlsV těle odpovědi odkazují nové zápisy (masky) zásad tak, aby odkazovaly na ekvivalentní odkaz přes bránu. Použijte v části odchozí pro opětovné psaní odkazů na text odpovědi, aby odkazovaly na bránu. Použijte v části příchozí pro opakový efekt.

Prohlášení o zásadách

<redirect-content-urls />

Příklad

<redirect-content-urls />

Elementy

Využití

Tyto zásady se dají použít v následujících oddílech a oborechzásad.

• Oddíly zásad: příchozí, odchozí

• Obory zásad: všechny rozsahy

Nastavit back-end službu

Pomocí této set-backend-service zásady můžete přesměrovat příchozí požadavek na jiný back-end než ten, který je zadaný v nastavení rozhraní API pro tuto operaci. Tato zásada změní základní adresu URL služby back-end příchozího požadavku na službu zadanou v zásadě.

Prohlášení o zásadách

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

nebo

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

Příklad

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

V tomto příkladu nastavovaná zásada služby back-end směruje požadavky na základě hodnoty verze předané v řetězci dotazu do jiné back-endové služby, než je ta zadaná v rozhraní API.

Zpočátku je základní adresa URL služby back-end odvozená od nastavení rozhraní API. Adresa URL požadavku se ale na https://contoso.azure-api.net/api/partners/15?version=2013-05&subscription-key=abcdef http://contoso.com/api/10.4/partners/15?version=2013-05&subscription-key=abcdef to, kde http://contoso.com/api/10.4/ je adresa URL back-end služby zadané v nastavení rozhraní API.

Pokud je použita <> příkaz zásady, základní adresa URL služby back-end se může změnit znovu buď na http://contoso.com/api/8.2 nebo http://contoso.com/api/9.1 , v závislosti na hodnotě parametru dotazu na žádost o verzi. Například pokud je hodnota "2013-15" konečná adresa URL požadavku http://contoso.com/api/8.2/partners/15?version=2013-05&subscription-key=abcdef , bude.

Pokud je požadována další transformace žádosti, lze použít další zásady transformace . Chcete-li například odebrat parametr dotazu verze nyní, že je požadavek směrován do specifického back-endu konkrétní verze, lze použít zásadu parametru řetězce dotazu set , pomocí níž lze odebrat atribut Now redundantní verze.

Příklad

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

V tomto příkladu zásady směrují požadavek do back-endu Service Fabric pomocí řetězce dotazu userId jako klíče oddílu a pomocí primární repliky oddílu.

Elementy

Atributy

Využití

Tuto zásadu můžete použít v následujících oddílech zásad a oborech.

• Oddíly zásad: příchozí, back-end

• Obory zásad: všechny obory

Nastavení textu

Pomocí zásady set-body můžete nastavit text zprávy pro příchozí a odchozí požadavky. Pokud chcete získat přístup k textu zprávy, můžete použít vlastnost nebo v závislosti na tom, jestli je zásada v části context.Request.Body context.Response.Body příchozí nebo odchozí.

Další informace najdete v částech context.Request.Body , a v tabulce context.Response.Body IMessage kontextových proměnných.

Prohlášení o zásadách

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

Příklady

Příklad literálového textu

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

Příklad přístupu k textu jako řetězci Všimněte si, že zachováme původní text požadavku, abychom k ní mohli později v kanálu přistupovat.

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

Příklad přístupu k textu jako objektu JObject Všimněte si, že vzhledem k tomu, že původní text požadavku nezahájíme, bude mít přístup k tomuto textu později v kanálu za následek výjimku.

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

Filtrování odpovědí na základě produktu

Tento příklad ukazuje, jak provádět filtrování obsahu odebráním datových prvků z odpovědi přijaté z back-endové služby při Starter použití produktu. Ukázku konfigurace a používání této zásady najdete v článku Cloud Cover Scene 177: More API Management Features with Vlad Vinogradsky and fast-forward to 34:30 (Přeposílání do 34:30). Začněte v 31:50, abyste si pro tuto ukázku prohlédněte přehled rozhraní API dark sky forecast.

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

Použití šablon Liquid s nastaveným tělem

Zásady je možné nakonfigurovat tak, aby k transformaci textu požadavku nebo odpovědi bylo možné použít jazyk šablon set-body Liquid. To může být velmi efektivní, pokud potřebujete zcela změnit formát zprávy.

Převod JSON na SOAP pomocí šablony Liquid

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

Transformace JSON pomocí šablony Liquid

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

Elementy

Vlastnosti

Pro přístup k informacím o požadavku a odpovědi může šablona Liquid vytvořit vazbu na kontextový objekt s následujícími vlastnostmi:

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

Využití

Tuto zásadu můžete použít v následujících oddílech zásad a oborech.

• Oddíly zásad: příchozí, odchozí, back-end

• Obory zásad: všechny obory

Nastavení hlavičky PROTOKOLU HTTP

Zásada přiřadí hodnotu existující hlavičce odpovědi nebo požadavku nebo přidá novou odpověď set-header nebo hlavičku požadavku.

Vloží seznam hlaviček PROTOKOLU HTTP do zprávy HTTP. Při umístění do příchozího kanálu tato zásada nastaví hlavičky PROTOKOLU HTTP pro požadavek předaný cílové službě. Při umístění do odchozího kanálu tato zásada nastaví hlavičky PROTOKOLU HTTP pro odpověď odesílané klientovi brány.

Prohlášení o zásadách

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

Příklady

Příklad – přidání hlavičky, přepsání existujícího

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

Příklad – odebrání hlavičky

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

Předání informací o kontextu back-endové službě

Tento příklad ukazuje, jak použít zásady na úrovni rozhraní API k poskytování kontextových informací back-endové službě. Ukázku konfigurace a používání této zásady najdete v článku Cloud Cover Scene 177: More API Management Features with Vlad Vinogradsky and fast-forward to 10:30 (Více funkcí API Management s Vladem Vinogradskym a fast-forward to 10:30). Ve 12:10 je ukázka volání operace na portálu pro vývojáře, kde můžete vidět zásady v práci.

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

Další informace najdete v tématu Výrazy zásad a Kontextová proměnná.

Elementy

Vlastnosti

Využití

Tuto zásadu můžete použít v následujících oddílech zásad a oborech.

• Oddíly zásad: příchozí, odchozí, back-end, chyba

• Obory zásad: všechny obory

Nastavení parametru řetězce dotazu

Zásada přidá, nahradí hodnotu parametru řetězce dotazu požadavku nebo set-query-parameter ho odstraní. Lze použít k předání parametrů dotazu očekávaných back-endovou službou, které jsou volitelné nebo se v požadavku nikdy nenacházejí.

Prohlášení o zásadách

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

Příklad

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

Předání informací o kontextu back-endové službě

Tento příklad ukazuje, jak použít zásady na úrovni rozhraní API k poskytování kontextových informací back-endové službě. Ukázku konfigurace a používání této zásady najdete v článku Cloud Cover Scene 177: More API Management Features with Vlad Vinogradsky and fast-forward to 10:30 (Přeposílání do 10:30). Ve 12:10 je ukázka volání operace na portálu pro vývojáře, kde můžete vidět zásady v práci.

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

Další informace najdete v tématu Výrazy zásad a Kontextová proměnná.

Elementy

Vlastnosti

Využití

Tuto zásadu můžete použít v následujících oddílech zásad a oborech.

• Oddíly zásad: příchozí, back-end

• Obory zásad: všechny obory

Přepsání adresy URL

Zásady převádí adresu URL požadavku z veřejného formuláře na formulář očekávaný webovou službou, jak je rewrite-uri znázorněno v následujícím příkladu.

• Veřejná adresa URL – http://api.example.com/storenumber/ordernumber

• Adresa URL požadavku – http://api.example.com/v2/US/hardware/storenumber&ordernumber?City&State

  Tuto zásadu můžete použít, když by se adresa URL vhodná pro člověka nebo prohlížeč měla transformovat do formátu adresy URL očekávaného webovou službou. Tuto zásadu je potřeba použít pouze při vystavení alternativního formátu adresy URL, jako jsou čisté adresy URL, adresy URL restful, uživatelsky přívětivé adresy URL nebo adresy URL vhodné pro SEO, které jsou čistě strukturální adresy URL, které neobsahují řetězec dotazu a místo toho obsahují pouze cestu k prostředku (po schématu a autoritě). To se často provádí z důvodů, které se používají pro zajištění vzhledu, použitelnosti nebo optimalizace vyhledávacího webu (SEO).

Prohlášení o zásadách

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

Příklad

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

Elementy

Atributy

Využití

Tuto zásadu můžete použít v následujících oddílech zásad a oborech.

• Oddíly zásad: příchozí

• Obory zásad: všechny obory

Transformace XML pomocí XSLT

Zásady Transform XML using an XSLT aplikují transformaci XSL na XML v textu požadavku nebo odpovědi.

Prohlášení o zásadách

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

Příklad

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

Elementy

Využití

Tuto zásadu můžete použít v následujících oddílech zásad a oborech.

• Oddíly zásad: příchozí, odchozí

• Obory zásad: všechny obory

Další kroky

Další informace najdete v následujících tématech:

• Zásady v API Management
• Referenční informace o zásadách pro úplný seznam prohlášení o zásadách a jejich nastavení
• Ukázky zásad