API Management dönüştürme ilkeleri

Bu konu, aşağıdaki API Management ilkelerine yönelik bir başvuru sağlar. İlke ekleme ve yapılandırma hakkında daha fazla bilgi için bkz. API Management ilkeleri.

Dönüştürme ilkeleri

• JSON 'ı XML 'e Dönüştür -JSON 'dan XML 'e istek veya Yanıt gövdesini dönüştürür.

• XML 'YI JSON 'A Dönüştür -istek veya Yanıt gövdesini XML 'den JSON 'a dönüştürür.

• Gövdede dize bul ve Değiştir -bir istek veya Yanıt alt dizesini bulur ve farklı bir alt dizeyle değiştirir.

• Yanıt gövdesindeki içerik-yazma (maske) bağlantılarında bulunan URL 'leri , ağ geçidi aracılığıyla eşdeğer bağlantıya işaret eden şekilde maskelerle.

• Arka uç hizmetini ayarlama -gelen istek için arka uç hizmetini değiştirir.

• Gövde ayarla -ileti gövdesini gelen ve giden istekler için ayarlar.

• Http üstbilgisini ayarla -mevcut bir yanıt ve/veya istek üstbilgisine bir değer atar veya yeni bir yanıt ve/veya istek üst bilgisi ekler.

• Sorgu dizesi parametresini ayarla -ekler, değerini değiştirir veya istek sorgu dizesi parametresini siler.

• Yeniden yazma URL 'si -BIR istek URL 'sini ortak formdan Web hizmeti tarafından beklenen biçime dönüştürür.

• XSLT kullanarak XML dönüştürme -istek veya yanıt gövdesinde XML 'e bir XSL dönüştürmesi uygular.

JSON 'ı XML 'e Dönüştür

json-to-xmlİlke, JSON 'DAN XML 'e bir istek veya yanıt gövdesi dönüştürür.

İlke ekstresi

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

Örnek

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

Öğeler

Öznitelikler

Kullanım

Bu ilke, aşağıdaki ilke bölümlerinde ve kapsamlardakullanılabilir.

• İlke bölümleri: gelen, giden, hata üzerine

• İlke kapsamları: tüm kapsamlar

XML 'i JSON 'ye Dönüştür

xml-to-jsonİlke bir isteği veya Yanıt GÖVDESINI XML 'den JSON 'a dönüştürür. Bu ilke, yalnızca XML arka uç Web Hizmetleri tabanlı API 'Leri modernleştirin için kullanılabilir.

İlke ekstresi

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

Örnek

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

Öğeler

Öznitelikler

Kullanım

Bu ilke, aşağıdaki ilke bölümlerinde ve kapsamlardakullanılabilir.

• İlke bölümleri: gelen, giden, hata üzerine

• İlke kapsamları: tüm kapsamlar

Gövdede dize bul ve Değiştir

find-and-replaceİlke bir istek veya Yanıt alt dizesi bulur ve farklı bir alt dizeyle değiştirir.

İlke ekstresi

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

Örnek

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

Öğeler

Öznitelikler

Kullanım

Bu ilke, aşağıdaki ilke bölümlerinde ve kapsamlardakullanılabilir.

• İlke bölümleri: gelen, giden, arka uç, hata durumunda

• İlke kapsamları: tüm kapsamlar

İçerikte maske URL 'Leri

redirect-content-urlsAğ Geçidi aracılığıyla eşdeğer bağlantıyı işaret ettikleri için, yanıt gövdesindeki ilke yeniden yazma (maskeleri) bağlantıları. Yanıt gövdesi bağlantılarını, ağ geçidine işaret etmek üzere yeniden yazmak için çıkış bölümünde kullanın. Ters bir efekt için gelen bölümünde kullanın.

İlke ekstresi

<redirect-content-urls />

Örnek

<redirect-content-urls />

Öğeler

Kullanım

Bu ilke, aşağıdaki ilke bölümlerinde ve kapsamlardakullanılabilir.

• İlke bölümleri: gelen, giden

• İlke kapsamları: tüm kapsamlar

Arka uç hizmetini ayarla

set-backend-serviceGelen bir isteği, bu işlem IÇIN API ayarlarında belirtilenden farklı bir arka uca yeniden yönlendirmek için ilkeyi kullanın. Bu ilke, gelen isteğin arka uç hizmeti taban URL 'sini ilkede belirtilen bir şekilde değiştirir.

İlke ekstresi

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

veya

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

Örnek

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

Bu örnekte, arka uç hizmet ilkesi, sorgu dizesinde geçirilen sürüm değerine bağlı olarak istekleri API 'de belirtilenden farklı bir arka uç hizmetine yönlendirir.

Başlangıçta arka uç hizmeti temel URL 'si API ayarlarından türetilir. Bu nedenle, istek URL 'si 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 http://contoso.com/api/10.4/ API ayarlarında arka uç hizmeti URL 'si olarak belirtilir.

<Select Policy deyimin seçimi > uygulandığında, arka uç hizmeti taban URL 'si, http://contoso.com/api/8.2 http://contoso.com/api/9.1 Sürüm isteği sorgu parametresinin değerine bağlı olarak ya da olarak yeniden değişebilir. Örneğin, değer "2013-15" son istek URL 'si ise olur http://contoso.com/api/8.2/partners/15?version=2013-05&subscription-key=abcdef .

İsteğin daha fazla dönüşümü isteniyorsa, diğer dönüştürme ilkeleri de kullanılabilir. Örneğin, isteğin sürüme özgü bir arka uca yönlendirildiğini artık sürüm sorgu parametresini kaldırmak için, artık gereksiz sürüm özniteliğini kaldırmak üzere sorgu dizesi ayarla parametresi ilkesi kullanılabilir.

Örnek

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

Bu örnekte ilke, bir Service Fabric arka ucuna, bölüm anahtarı olarak UserID sorgu dizesini ve bölümün birincil çoğaltmasını kullanarak isteği yönlendirir.

Öğeler

Öznitelikler

Kullanım

Bu ilke aşağıdaki ilke bölümlerinde ve kapsamlarında kullanılabilir.

• İlke bölümleri: gelen, arka uç

• İlke kapsamları: tüm kapsamlar

Gövdeyi ayarla

set-bodyİlkeyi kullanarak gelen ve giden isteklerin ileti gövdelerini ayarlayın. İleti gövdesine erişmek için, ilkenin gelen veya giden bölümünde olup olmadığını bağlı olarak özelliğini context.Request.Body context.Response.Body veya kullanabilirsiniz.

Daha fazla bilgi için context.Request.Body Bağlam değişkeni tablosunda , ve context.Response.Body IMessage bölümlerine bakın.

İlke deyimi

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

Örnekler

Değişmez metin örneği

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

Gövdeye dize olarak erişme örneği. Özgün istek gövdesinde daha sonra işlem hattında erişime izin veremek için bu gövdeyi koruruz.

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

Gövdeye JObject olarak erişme örneği. Özgün istek gövdesini korumamamız nedeniyle işlem hattında daha sonra bu gövdeye erişirken bir özel durumla sonuçlanmayacaktır.

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

Yanıtı ürüne göre filtreleme

Bu örnekte, ürün kullanılırken arka uç hizmetten alınan yanıttan veri öğelerini kaldırarak içerik filtrelemenin nasıl gerçekleştir olduğu Starter gösterir. Bu ilkeyi yapılandırmanın ve kullanmanın bir gösterimi için bkz. Cloud Cover Bölüm 177: More API Management Features with Vinogradsky ve fast-forward to 34:30. Bu tanıtım için kullanılan The Dark Sky Forecast API'sini görmek için 31:50'de çalışmaya başlayabilirsiniz.

<!-- 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 şablonlarını küme gövdesiyle kullanma

İlke, bir isteğin veya yanıtın gövdesini dönüştürmek için set-body Liquid templating dilini kullanmak üzere yalıt edilebilir. İletinizin biçimini tamamen yeniden şekillendirmeniz gerekirse bu çok etkili olabilir.

Liquid şablonu kullanarak JSON'u SOAP'ye dönüştürme

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

Liquid şablonu kullanarak JSON dönüştürme

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

Öğeler

Özellikler

Liquid şablonu, istek ve yanıtla ilgili bilgilere erişmek için aşağıdaki özelliklere sahip bir bağlam nesnesine bağlanabilir:

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

Kullanım

Bu ilke aşağıdaki ilke bölümlerinde ve kapsamlarında kullanılabilir.

• İlke bölümleri: gelen, giden, arka uç

• İlke kapsamları: tüm kapsamlar

HTTP üst bilgisi ayarlama

İlke, mevcut yanıt ve/veya istek üst bilgisinde bir değer set-header atar ya da yeni bir yanıt ve/veya istek üst bilgisi ekler.

BIR HTTP iletisine HTTP üst bilgileri listesi ekler. Gelen işlem hattına yerleştirilseniz, bu ilke hedef hizmete geçirilen isteğin HTTP üst bilgilerini ayarlar. Giden işlem hattına yerleştirilseniz, bu ilke ağ geçidinin istemcisine gönderilen yanıtın HTTP üst bilgilerini ayarlar.

İlke deyimi

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

Örnekler

Örnek - üst bilgi ekleme, var olan verileri geçersiz kılma

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

Örnek - üst bilgi kaldırma

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

Bağlam bilgilerini arka uç hizmetine iletme

Bu örnekte, arka uç hizmetine bağlam bilgileri sağlamak için ILKEnin API düzeyinde nasıl uygulanacakları gösterir. Bu ilkeyi yapılandırmanın ve kullanmanın bir gösterimi için bkz. Cloud Cover Bölüm 177: More API Management Features with Vinogradsky ve fast-forward to 10:30. Saat 12:10'da, geliştirici portalında ilkeyi iş yerinde gördüğünüz bir işlemi çağırma demosu vardır.

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

Daha fazla bilgi için bkz. İlke ifadeleri ve Bağlam değişkeni.

Öğeler

Özellikler

Kullanım

Bu ilke, aşağıdaki ilke bölümlerinde ve kapsamlardakullanılabilir.

• İlke bölümleri: gelen, giden, arka uç, hata durumunda

• İlke kapsamları: tüm kapsamlar

Sorgu dizesi parametresini ayarla

set-query-parameterİlke, değer ekler veya siler veya istek sorgu dizesi parametresini siler. İsteğe bağlı olan veya istekte hiçbir şekilde bulunmayan arka uç hizmeti tarafından beklenen sorgu parametrelerini geçirmek için kullanılabilir.

İlke ekstresi

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

Örnek

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

Bağlam bilgilerini arka uç hizmetine ilet

Bu örnek, arka uç hizmetine bağlam bilgilerini sağlamak üzere API düzeyinde ilkenin nasıl uygulanacağını gösterir. Bu ilkeyi yapılandırma ve kullanma gösterimi için bkz. Cloud Cover bölüm 177: Vlad Vinogradsky Ile daha fazla API Management özelliği ve 10:30 ile ileri sarma. 12:10 ' de, bir işlemi iş üzerindeki ilkeyi görebileceğiniz Geliştirici Portalında çağırma tanıtımı vardır.

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

Daha fazla bilgi için bkz. ilke ifadeleri ve bağlam değişkeni.

Öğeler

Özellikler

Kullanım

Bu ilke, aşağıdaki ilke bölümlerinde ve kapsamlardakullanılabilir.

• İlke bölümleri: gelen, arka uç

• İlke kapsamları: tüm kapsamlar

Yeniden yazma URL 'SI

rewrite-uriİlke, aşağıdaki örnekte gösterildiği gibi, bir Istek URL 'sini ortak formdan Web hizmeti tarafından beklenen biçime dönüştürür.

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

• İstek URL 'SI- http://api.example.com/v2/US/hardware/storenumber&ordernumber?City&State

  Bu ilke, bir insan ve/veya tarayıcı kullanımı kolay URL 'SI Web hizmeti tarafından beklenen URL biçimine dönüştürülebileceğinden kullanılabilir. Bu ilkenin yalnızca bir sorgu dizesi içermeyen ve bunun yerine yalnızca kaynağın yolunu (düzen ve yetkilinin ardından) içeren, temiz URL 'ler, yeniden oluşturma URL 'leri, Kullanıcı dostu URL 'ler veya SEO kullanımı kolay URL 'ler gibi alternatif bir URL biçimi kullanıma sunulduktan sonra uygulanması gerekir. Bu genellikle Aesthetic Characteristics, kullanılabilirlik veya arama motoru iyileştirme (SEO) amaçları için yapılır.

İlke ekstresi

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

Örnek

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

Öğeler

Öznitelikler

Kullanım

Bu ilke, aşağıdaki ilke bölümlerinde ve kapsamlardakullanılabilir.

• İlke bölümleri: gelen

• İlke kapsamları: tüm kapsamlar

XSLT kullanarak XML dönüştürme

Transform XML using an XSLTİlke, istek veya Yanıt GÖVDESINDE XML 'e BIR XSL dönüştürmesi uygular.

İlke deyimi

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

Örnek

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

Öğeler

Kullanım

Bu ilke aşağıdaki ilke bölümlerinde ve kapsamlarında kullanılabilir.

• İlke bölümleri: gelen, giden

• İlke kapsamları: tüm kapsamlar

Sonraki adımlar

Daha fazla bilgi edinmek için aşağıdaki kaynaklara bakın:

• API Management'de ilkeler
• İlke deyimlerinin ve ayarlarının tam listesi için İlke Başvurusu
• İlke örnekleri