Kebijakan ExtractVariables

Halaman ini berlaku untuk Apigee dan Apigee hybrid.

Lihat dokumentasi Apigee Edge.

Kebijakan ExtractVariables mengekstrak konten dari permintaan atau respons dan menetapkan nilai variabel ke konten tersebut. Anda dapat mengekstrak setiap bagian pesan, termasuk header, jalur URI, payload JSON/XML, parameter formulir, dan parameter kueri. Kebijakan ini berfungsi dengan menerapkan pola teks ke konten pesan dan, setelah menemukan kecocokan, menetapkan variabel dengan konten pesan yang ditentukan.

Anda juga dapat menggunakan kebijakan ini untuk mengekstrak informasi dari sumber lain, seperti entitas yang dibuat oleh kebijakan AccessEntity, objek XML, atau objek JSON.

Setelah mengekstrak konten pesan yang ditentukan, Anda dapat mereferensikan variabel dalam kebijakan lain sebagai bagian dari pemrosesan permintaan dan respons. Misalnya, Anda dapat menambahkan kebijakan RaiseFault untuk menampilkan error jika nilai yang diekstrak tidak valid.

Saat menentukan kebijakan ExtractVariables, Anda dapat memilih:

  • Nama variabel yang akan ditetapkan
  • Sumber variabel
  • Jumlah variabel yang akan diekstrak dan ditetapkan

Saat dijalankan, kebijakan ini menerapkan pola teks ke konten dan, setelah menemukan kecocokan, menetapkan nilai variabel yang ditentukan dengan konten tersebut. Kebijakan dan kode lain kemudian dapat menggunakan variabel tersebut untuk mengaktifkan perilaku dinamis atau mengirim data bisnis ke Apigee API Analytics.

Kebijakan ini adalah Kebijakan yang dapat diperluas dan penggunaan kebijakan ini mungkin memiliki implikasi biaya atau penggunaan, bergantung pada lisensi Apigee Anda. Untuk mengetahui informasi tentang jenis kebijakan dan implikasi penggunaannya, lihat Jenis kebijakan.

Sampel

Contoh kode kebijakan ini menggambarkan cara mengekstrak variabel dari jenis artefak berikut:

URI

<ExtractVariables name="ExtractVariables-1">
   <DisplayName>Extract a portion of the url path</DisplayName>
   <Source>request</Source>
   <URIPath>
      <Pattern ignoreCase="true">/accounts/{id}</Pattern>
   </URIPath>
   <VariablePrefix>urirequest</VariablePrefix>
   <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

Pertimbangkan kode kebijakan contoh di atas. Elemen <URIPath> memberi tahu kebijakan ExtractVariables untuk mengekstrak informasi dari jalur URI. Elemen <Pattern> menentukan pola yang akan diterapkan ke jalur URI. Pola diperlakukan sebagai template sederhana, dengan tanda kurung kurawal yang menunjukkan bagian jalur URI yang bervariasi.

Nama variabel yang akan ditetapkan ditentukan oleh nilai yang ditentukan dalam elemen <VariablePrefix>, serta nilai yang diapit dalam tanda kurung kurawal {} dalam elemen <Pattern>. Kedua nilai digabungkan dengan titik di antaranya, sehingga menghasilkan nama variabel urirequest.id misalnya. Jika tidak ada elemen <VariablePrefix>, nama variabel hanyalah nilai yang diapit dalam tanda kurung kurawal.

Pertimbangkan kode kebijakan contoh di atas yang berfungsi dengan permintaan masuk berikut:

GET http://example.com/svc1/accounts/12797282

Misalkan basepath untuk Proxy API adalah /svc1. Saat Apigee menerapkan kode kebijakan ExtractVariables di atas ke permintaan masuk ini, Apigee akan menetapkan variabel urirequest.id ke 12797282. Setelah Apigee menjalankan kebijakan, kebijakan atau kode berikutnya dalam alur pemrosesan dapat merujuk ke variabel bernama urirequest.id untuk mendapatkan nilai string 12797282.

Misalnya, kebijakan AssignMessage berikut menyematkan nilai variabel tersebut ke dalam payload pesan permintaan baru:

<AssignMessage async="false" continueOnError="false" enabled="true" name="AssignPayload">
  <DisplayName>AssignPayload</DisplayName>
    <Set>
      <Payload contentType="text/xml">
        <IdExtractedFromURI>{urirequest.id}</IdExtractedFromURI>
      </Payload>
    </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="true" transport="http" type="request">newRequest</AssignTo>
</AssignMessage>

Parameter kueri

<ExtractVariables name="ExtractVariables-2">
   <DisplayName>Extract a value from a query parameter</DisplayName>
   <Source>request</Source>
   <QueryParam name="code">
      <Pattern ignoreCase="true">DBN{dbncode}</Pattern>
   </QueryParam>
   <VariablePrefix>queryinfo</VariablePrefix>
   <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

Pertimbangkan kode kebijakan contoh di atas yang berfungsi dengan permintaan masuk berikut:

GET http://example.com/accounts/12797282?code=DBN88271

Saat Apigee menerapkan kode kebijakan ExtractVariables di atas ke permintaan masuk ini, Apigee akan menetapkan variabel queryinfo.dbncode ke 88271. Setelah Apigee mengeksekusi kebijakan, kebijakan atau kode berikutnya dalam alur pemrosesan dapat merujuk ke variabel bernama queryinfo.dbncode untuk mendapatkan nilai string 88271.

Anda kini dapat mengakses variabel queryinfo.dbncode di proxy Anda. Misalnya, kebijakan AssignMessage berikut menyalinnya ke payload permintaan:

<AssignMessage async="false" continueOnError="false" enabled="true" name="GetURIPath">
  <DisplayName>GetQP</DisplayName>
  <Set>
   <Payload contentType="text/xml">
    <ExtractQP>{queryinfo.dbncode}</ExtractQP>
   </Payload>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

Beberapa parameter

<ExtractVariables name="ExtractVariables-2">
  <DisplayName>Extract a value from a query parameter</DisplayName>
  <Source>request</Source>
  <QueryParam name="w">
    <Pattern ignoreCase="true">{firstWeather}</Pattern>
  </QueryParam>
  <QueryParam name="w.2">
    <Pattern ignoreCase="true">{secondWeather}</Pattern>
  </QueryParam>
  <VariablePrefix>queryinfo</VariablePrefix>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

Misalkan desain API Anda memungkinkan Anda menentukan beberapa parameter kueri dengan nama yang sama. Anda dapat menggunakan kebijakan ExtractVariables untuk mengekstrak nilai beberapa instance parameter kueri. Untuk mereferensikan parameter kueri dengan nama yang sama dalam kebijakan, gunakan indeks dengan instance pertama parameter kueri tidak memiliki indeks, yang kedua berada di indeks 2, yang ketiga di indeks 3, dan seterusnya.

Pertimbangkan kode kebijakan contoh di atas yang berfungsi dengan permintaan masuk berikut:

GET http://example.com/weather?w=Boston&w=Chicago

Saat Apigee menerapkan kode kebijakan ExtractVariables di atas ke permintaan masuk ini, Apigee akan menetapkan variabel queryinfo.firstWeather ke Boston dan variabel queryInfo.secondWeather ke Chicago.

Anda kini dapat mengakses variabel queryinfo.firstWeather dan queryinfo.secondWeather di proxy Anda. Misalnya, kebijakan AssignMessage berikut menyalinnya ke payload permintaan:

<AssignMessage async="false" continueOnError="false" enabled="true" name="GetURIPath">
  <DisplayName>GetQP</DisplayName>
  <Set>
    <Payload contentType="text/xml">
      <ExtractQP1>{queryinfo.firstWeather}</ExtractQP1>
      <ExtractQP2>{queryinfo.secondWeather}</ExtractQP2>
    </Payload>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

Header

<ExtractVariables name='ExtractVariable-OauthToken'>
  <Source>request</Source>
  <Header name="Authorization">
    <Pattern ignoreCase="false">Bearer {oauthtoken}</Pattern>
  </Header>
  <VariablePrefix>clientrequest</VariablePrefix>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

Misalkan API Anda menggunakan token pembawa OAuth v2.0. Pertimbangkan kode kebijakan contoh di atas yang berfungsi dengan permintaan yang membawa token OAuth v2.0 yang menyertakan header seperti ini: Authorization: Bearer TU08xptfFfeM7aS0xHqlxTgEAdAM.

Sebagai desainer API, misalkan Anda ingin menggunakan nilai token (tetapi bukan seluruh header) sebagai kunci dalam pencarian cache. Anda dapat menggunakan kode kebijakan ExtractVariables di atas untuk mengekstrak token.

Saat Apigee menerapkan kode kebijakan ExtractVariables di atas ke header ini, Apigee menetapkan variabel clientrequest.oauthtoken ke TU08xptfFfeM7aS0xHqlxTgEAdAM.

Anda kini dapat mengakses variabel clientrequest.oauthtoken di proxy Anda. Misalnya, kebijakan AssignMessage berikut menyalinnya ke payload permintaan:

<AssignMessage async="false" continueOnError="false" enabled="true" name="GetURIPath">
  <DisplayName>GetHeader</DisplayName>
  <Set>
    <Payload contentType="text/xml">
      <ExtractHeader>{clientrequest.oauthtoken}</ExtractHeader>
    </Payload>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

JSON

<ExtractVariables name="ExtractVariables-3">
  <Source>response</Source>
  <JSONPayload>
    <Variable name="latitude" type="float">
      <JSONPath>$.results[0].geometry.location.lat</JSONPath>
    </Variable>
    <Variable name="longitude" type="float">
      <JSONPath>$.results[0].geometry.location.lng</JSONPath>
    </Variable>
  </JSONPayload>
  <VariablePrefix>geocoderesponse</VariablePrefix>
</ExtractVariables>

Pertimbangkan payload respons JSON berikut:

{
  "results": [{
    "geometry": {
      "location": {
        "lat": 37.42291810,
        "lng": -122.08542120
      },
      "location_type": "ROOFTOP",
      "viewport": {
        "northeast": {
          "lat": 37.42426708029149,
          "lng": -122.0840722197085
        },
        "southwest": {
          "lat": 37.42156911970850,
          "lng": -122.0867701802915
        }
      }
    }
  }]
}

Saat Apigee menerapkan kode kebijakan ExtractVariables di atas ke pesan JSON ini, Apigee akan menetapkan dua variabel: geocoderesponse.latitude dan geocoderesponse.longitude. Kedua variabel menggunakan awalan variabel yang sama, yaitu geocoderesponse. Sufiks untuk variabel ini ditentukan secara eksplisit oleh atribut name elemen <Variable>.

Variabel geocoderesponse.latitude mendapatkan nilai 37.42291810. Variabel geocoderesponse.longitude mendapatkan nilai -122.08542120.

Anda kini dapat mengakses variabel geocoderesponse.latitude di proxy Anda. Misalnya, kebijakan AssignMessage berikut menyalinnya ke header bernama latitude dalam respons:

<AssignMessage async="false" continueOnError="false" enabled="true" name="GetURIPath">
  <DisplayName>GetJSONVar</DisplayName>
  <Add>
    <Headers>
      <Header name="latitude">{geocoderesponse.latitude}</Header>
    </Headers>
  </Add>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>

XML

<ExtractVariables name="ExtractVariables-4">
   <Source>response</Source>
   <XMLPayload>
      <Namespaces>
         <Namespace prefix="dir">urn:43BFF88D-D204-4427-B6BA-140AF393142F</Namespace>
      </Namespaces>
      <Variable name="travelmode" type="string">
         <XPath>/dir:Directions/dir:route/dir:leg/dir:step/@mode</XPath>
      </Variable>
      <Variable name="duration" type="string">
         <XPath>/dir:Directions/dir:route/dir:leg/dir:step/dir:duration/dir:value</XPath>
      </Variable>
      <Variable name="timeunit" type="string">
         <XPath>/dir:Directions/dir:route/dir:leg/dir:step/dir:duration/dir:text</XPath>
      </Variable>
   </XMLPayload>
   <VariablePrefix>directionsresponse</VariablePrefix>
</ExtractVariables>

Pertimbangkan payload respons XML berikut:

<Directions xmlns="urn:43BFF88D-D204-4427-B6BA-140AF393142F">
   <status>OK</status>
   <route>
      <summary>I-40 W</summary>
      <leg>
         <step mode="DRIVING">
            <start_location>
               <lat>41.8507300</lat>
               <lng>-87.6512600</lng>
            </start_location>
            <end_location>
               <lat>41.8525800</lat>
               <lng>-87.6514100</lng>
            </end_location>
            <duration>
                <value>19</value>
                <text>minutes</text>
            </duration>
         </step>
      </leg>
   </route>
</Directions>

Saat menerapkan kode kebijakan ExtractVariables di atas ke pesan XML ini, Apigee akan menetapkan tiga variabel:

  • directionsresponse.travelmode: Mendapatkan nilai DRIVING
  • directionsresponse.duration: Mendapatkan nilai 19
  • directionsresponse.timeunit: Mendapatkan nilai minutes

Semua variabel menggunakan awalan variabel yang sama, yaitu directionsresponse. Sufiks untuk variabel ini ditentukan secara eksplisit oleh atribut name elemen <Variable>.

Anda kini dapat mengakses variabel directionresponse.travelmode di proxy Anda. Misalnya, kebijakan AssignMessage berikut menyalinnya ke header bernama tmode dalam respons:

<AssignMessage async="false" continueOnError="false" enabled="true" name="GetURIPath">
  <DisplayName>GetXMLVar</DisplayName>
  <Add>
    <Headers>
      <Header name="tmode">{directionsresponse.travelmode}</Header>
    </Headers>
  </Add>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

Cakupan Variabel

Variabel yang ditetapkan dengan kebijakan ExtractVariables memiliki cakupan global. Artinya, setelah kebijakan ExtractVariables menentukan variabel baru, Anda dapat mengakses variabel tersebut dari kebijakan atau kode apa pun di tahap alur yang dijalankan setelah kebijakan ExtractVariables. Hal ini mencakup:

  • PreFlow: ProxyEndpoint dan TargetEndpoint (Permintaan dan Respons)
  • PostFlow: ProxyEndpoint dan TargetEndpoint (Permintaan dan Respons)
  • PostClientFlow: ProxyEndpoint (Khusus Respons, menggunakan kebijakan MessageLogging>)
  • Alur Error

Pencocokan dan pembuatan variabel

Kebijakan ExtractVariables mengekstrak informasi dari permintaan atau respons dan menulis informasi tersebut ke variabel. Untuk setiap jenis informasi yang dapat Anda ekstrak, seperti jalur URI atau data XML, Anda menentukan pola yang akan dicocokkan dan nama variabel yang digunakan untuk menyimpan informasi yang diekstrak.

Namun, cara kerja pencocokan pola bergantung pada sumber ekstraksi. Bagian berikut menjelaskan dua kategori dasar informasi yang dapat Anda ekstrak.

Mencocokkan jalur URI, parameter kueri, header, parameter formulir, dan variabel

Saat mengekstrak informasi dari jalur URI, parameter kueri, header, parameter formulir, dan variabel, Anda menggunakan tag <Pattern> untuk menentukan satu atau beberapa pola yang akan dicocokkan. Misalnya, contoh kebijakan berikut menunjukkan satu pola yang cocok untuk jalur URI:

<ExtractVariables name="ExtractVariables-1">
   <Source>request</Source>
   <URIPath>
      <Pattern ignoreCase="true">/a/{pathSeg}</Pattern>
   </URIPath>
   <VariablePrefix>urirequest</VariablePrefix>
   <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

Dalam contoh ini, variabel urirequest.pathSeg ditetapkan ke apa pun yang muncul di proxy.pathsuffix setelah /a/. Misalnya, jalur dasar untuk Proxy API Anda adalah /basepath/v1 . Dengan permintaan masuk ke http://myCo.com/basepath/v1/a/b, variabel ditetapkan ke b.

Menentukan beberapa pola

Anda dapat menentukan beberapa pola yang akan dicocokkan, yang sesuai dengan tag <Pattern>, dengan:

  • Semua pola diuji untuk kecocokan.
  • Jika tidak ada pola yang cocok, kebijakan tidak akan melakukan apa pun dan variabel tidak akan dibuat.
  • Jika lebih dari satu pola cocok, pola dengan segmen jalur terpanjang akan digunakan untuk ekstraksi.
  • Jika dua pola yang cocok memiliki segmen jalur terpanjang yang sama, pola yang ditentukan terlebih dahulu dalam kebijakan akan digunakan untuk ekstraksi.

Pada contoh berikutnya, Anda membuat kebijakan yang berisi tiga pola pencocokan untuk jalur URI:

<ExtractVariables name="ExtractVariables-1">
  <Source>request</Source>
  <URIPath>
    <Pattern ignoreCase="true">/a/{pathSeg}</Pattern>
    <Pattern ignoreCase="true">/a/b/{pathSeg}</Pattern>
    <Pattern ignoreCase="true">/a/b/c/{pathSeg}</Pattern>
  </URIPath>
  <VariablePrefix>urirequest</VariablePrefix>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

Misalnya, untuk Proxy API dengan basepath /basepath/v1 , URL permintaan masuk ke proxy API memiliki bentuk ini:

http://myCo.com/basepath/v1/a/b

Dalam contoh ini, pola pertama cocok dengan URI dan variabel urirequest.pathSeg disetel ke b.

Jika URL permintaan adalah:

http://myCo.com/basepath/v1/a/b/c/d

...maka pola ketiga cocok dan variabel urirequest.pathSeg disetel ke d.

Menentukan pola dengan beberapa variabel

Anda dapat menentukan beberapa variabel dalam pola pencocokan. Misalnya, Anda menentukan pola pencocokan dengan dua variabel:

<ExtractVariables name="ExtractVariables-1">
  <Source>request</Source>
  <URIPath>
    <Pattern ignoreCase="true">/a/{pathSeg}</Pattern>
    <Pattern ignoreCase="true">/a/b/{pathSeg}</Pattern>
    <Pattern ignoreCase="true">/a/{pathSeg1}/c/{pathSeg2}</Pattern>
  </URIPath>
  <VariablePrefix>urirequest</VariablePrefix>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

Sekali lagi, dengan asumsi Proxy API dengan jalur dasar /basepath/v1, untuk URL permintaan masuk:

http://myCo.com/basepath/v1/a/b/c/d

...variabel urirequest.pathSeg1 disetel ke b dan variabel urirequest.pathSeg2 disetel ke d.

Mencocokkan beberapa instance dalam pola

Anda juga dapat mencocokkan pola jika ada beberapa instance item dengan nama yang sama. Misalnya, Anda dapat membuat permintaan yang berisi beberapa parameter kueri atau beberapa header dengan nama yang sama. Permintaan berikut berisi dua parameter kueri bernama "w":

http://myCo.com/basepath/v1/a/b/c/d?w=1&w=2

Untuk mereferensikan parameter kueri ini dalam kebijakan ExtractVariables, Anda menggunakan indeks, dengan instance pertama parameter kueri tidak memiliki indeks, yang kedua berada di indeks 2, yang ketiga di indeks 3, dll. Misalnya, kebijakan berikut mengekstrak nilai parameter kueri kedua bernama "w" dalam permintaan:

<ExtractVariables name="ExtractVariables-1">
  <Source>request</Source>
  <QueryParam name="w.2">
    <Pattern ignoreCase="true">{secondW}</Pattern>
  </QueryParam>
  <VariablePrefix>urirequest</VariablePrefix>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

Variabel urirequest.secondW ditetapkan ke "2". Jika parameter kueri kedua tidak disertakan dalam permintaan, maka variabel urirequest.secondW akan kosong. Gunakan pengindeksan setiap kali ada beberapa item dengan nama yang sama dalam permintaan.

Menggunakan karakter khusus dalam pola

Saat mencocokkan jalur URI, Anda dapat menggunakan karakter pengganti "*" dan "**" dalam pola, dengan:

  • "*" cocok dengan satu segmen jalur
  • "**" cocok dengan beberapa segmen jalur

Misalnya, Anda menentukan pola ke elemen <URIPath> seperti yang ditunjukkan di bawah:

<URIPath>
  <Pattern ignoreCase="true">/a/*/{id}</Pattern>
  <Pattern ignoreCase="true">/a/**/{id}</Pattern>
</URIPath>

Pola pertama cocok dengan permintaan dengan akhiran jalur (bagian jalur URI setelah basepath) seperti "/a/b/c", "/a/foo/bar", dll. Pola kedua cocok dengan sejumlah segmen jalur setelah "/a/", seperti "/a/foo/bar/baz/c", serta "/a/b/c" dan "/a/foo/bar".

Saat menentukan pola untuk parameter kueri, header, dan parameter formulir, karakter "*" menentukan untuk mencocokkan sejumlah karakter. Misalnya, saat mencocokkan header, tentukan pola sebagai:

*;charset={encoding}

Pola ini cocok dengan nilai "text/xml;charset=UTF-16" dan "application/xml;charset=ASCII".

Jika nilai yang diteruskan ke kebijakan ExtractVariables berisi karakter khusus, seperti "{", gunakan karakter "%" untuk meng-escape-nya. Contoh berikut meng-escape karakter "{" dan "}" dalam pola karena digunakan sebagai karakter literal dalam nilai parameter kueri:

<QueryParam>
  <Pattern ignoreCase="true">%{user%} {name}</Pattern>
</QueryParam>

Dalam contoh ini, pola cocok dengan nilai "{user} Steve", tetapi tidak cocok dengan nilai "user Steve".

Mencocokkan JSON dan XML

Saat mengekstrak data dari JSON dan XML, Anda menentukan satu atau beberapa tag <Variable> dalam kebijakan. Tag <Variable> menentukan nama variabel tujuan tempat informasi yang diekstrak disimpan, dan JsonPath (JSON) atau XPATH (XML) ke informasi yang diekstrak.

Semua tag <Variable> dalam kebijakan dievaluasi, sehingga Anda dapat mengisi beberapa variabel dari satu kebijakan. Jika tag <Variable> tidak dievaluasi ke kolom yang valid dalam JSON atau XML, maka variabel yang sesuai tidak dibuat.

Contoh berikut menunjukkan kebijakan ExtractVariables yang mengisi dua variabel dari isi JSON respons:

<ExtractVariables name="ExtractVariables-3">
   <Source>response</Source>
   <JSONPayload>
      <Variable name="latitude" type="float">
         <JSONPath>$.results[0].geometry.location.lat</JSONPath>
      </Variable>
      <Variable name="longitude" type="float">
         <JSONPath>$.results[0].geometry.location.lng</JSONPath>
      </Variable>
   </JSONPayload>
   <VariablePrefix>geocoderesponse</VariablePrefix>
</ExtractVariables>

Menulis ke variabel yang sama di beberapa tempat

Berhati-hatilah saat memilih nama variabel yang akan ditetapkan. Kebijakan dijalankan secara berurutan dari pola ekstraksi pertama hingga terakhir. Jika kebijakan menulis nilai ke variabel yang sama dari beberapa tempat, penulisan terakhir dalam kebijakan menentukan nilai variabel. (Ini mungkin yang Anda inginkan.)

Misalnya, Anda ingin mengekstrak nilai token yang dapat diteruskan dalam parameter kueri atau di header, seperti yang ditunjukkan di bawah ini:

<!-- If token only in query param, the query param determines the value.
     If token is found in both the query param and header, header sets value. -->
<QueryParam name="token">
  <Pattern ignoreCase="true">{tokenValue}</Pattern>
</QueryParam>

<!-- Overwrite tokenValue even if it was found in query parameter. -->
<Header name="Token">
  <Pattern ignoreCase="true">{tokenValue}</Pattern>
</Header>

Mengontrol apa yang terjadi jika tidak ada kecocokan

Jika pola tidak cocok, variabel yang sesuai tidak akan dibuat. Oleh karena itu, jika kebijakan lain mereferensikan variabel, hal ini dapat menyebabkan error.

Salah satu opsi adalah menyetel <IgnoreUnresolvedVariables> ke benar (true) dalam kebijakan yang mereferensikan variabel untuk mengonfigurasi kebijakan agar memperlakukan variabel yang tidak dapat diselesaikan sebagai string kosong (null):

<IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>

Referensi elemen

Referensi elemen menjelaskan elemen dan atribut kebijakan ExtractVariables.

<ExtractVariables async="false" continueOnError="false" enabled="true" name="Extract-Variables-1">
   <DisplayName> 1</DisplayName>
   <Source clearPayload="true|false">request</Source>
   <VariablePrefix>myprefix</VariablePrefix>
   <IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>
   <URIPath>
      <Pattern ignoreCase="false">/accounts/{id}</Pattern>
   </URIPath>
   <QueryParam name="code">
      <Pattern ignoreCase="true">DBN{dbncode}</Pattern>
   </QueryParam>
   <Header name="Authorization">
      <Pattern ignoreCase="false">Bearer {oauthtoken}</Pattern>
   </Header>
   <FormParam name="greeting">
      <Pattern>hello {user}</Pattern>
   </FormParam>
   <Variable name="request.content">
       <Pattern>hello {user}</Pattern>
   </Variable>
   <JSONPayload>
      <Variable name="name">
         <JSONPath>{example}</JSONPath>
      </Variable>
   </JSONPayload>
   <XMLPayload stopPayloadProcessing="false">
      <Namespaces/>
      <Variable name="name" type="boolean">
         <XPath>/test/example</XPath>
      </Variable>
   </XMLPayload>
</ExtractVariables>

Atribut <ExtractVariables>

<ExtractVariables async="false" continueOnError="false" enabled="true" name="Extract-Variables-1">

Tabel berikut menjelaskan atribut yang umum untuk semua elemen induk kebijakan:

Atribut Deskripsi Default Kehadiran
name

Nama internal kebijakan. Nilai atribut name dapat berisi huruf, angka, spasi, tanda hubung, garis bawah, dan titik. Nilai ini tidak boleh melebihi 255 karakter.

Secara opsional, gunakan elemen <DisplayName> untuk memberi label pada kebijakan di editor proxy UI pengelolaan dengan nama bahasa alami yang berbeda.

 T/A Wajib
continueOnError

Tetapkan ke false untuk menampilkan error saat kebijakan gagal. Perilaku ini wajar terjadi untuk sebagian besar kebijakan.

Tetapkan ke true agar eksekusi alur berlanjut meskipun setelah kebijakan gagal. Lihat juga:

 false Opsional
enabled

Tetapkan ke true untuk menerapkan kebijakan.

Tetapkan ke false untuk menonaktifkan kebijakan. Kebijakan tidak akan diterapkan meskipun tetap terlampir ke alur.

 benar Opsional
async

Atribut ini tidak digunakan lagi.

 false Tidak digunakan lagi

Elemen <DisplayName>

Gunakan selain atribut name untuk melabeli kebijakan di editor proxy UI pengelolaan dengan nama bahasa alami yang berbeda.

<DisplayName>Policy Display Name</DisplayName>
Default

T/A

Jika Anda menghapus elemen ini, nilai atribut name kebijakan akan digunakan.
Kehadiran Opsional
Jenis String

Elemen <Source>

(Opsional) Menentukan variabel yang akan diuraikan. Nilai <Source> secara default adalah message. Nilai message peka konteks. Dalam alur permintaan, message diselesaikan ke pesan permintaan. Dalam alur respons, message diselesaikan ke pesan respons.

Meskipun Anda sering menggunakan kebijakan ini untuk mengekstrak informasi dari pesan permintaan atau respons, Anda dapat menggunakannya untuk mengekstrak informasi dari variabel apa pun. Misalnya, Anda dapat menggunakannya untuk mengekstrak informasi dari entitas yang dibuat oleh kebijakan AccessEntity, dari data yang ditampilkan oleh kebijakan ServiceCallout, atau mengekstrak informasi dari objek XML atau JSON.

Jika <Source> tidak dapat diselesaikan, atau diselesaikan ke jenis non-pesan, kebijakan tidak akan merespons.

<Source clearPayload="true|false">request</Source>
Default: pesan
Kehadiran: Opsional
Jenis: String

Atribut

Atribut Deskripsi Default Kehadiran Jenis
clearPayload

Setel ke benar jika Anda ingin menghapus payload yang ditentukan dalam <Source> setelah mengekstrak data darinya.

Gunakan opsi <clearPayload> hanya jika pesan sumber tidak diperlukan setelah ExtractVariables dijalankan. Menyetel ke true akan membebaskan memori yang digunakan oleh pesan.

false

 Opsional Boolean

Elemen <VariablePrefix>

(Opsional) Nama variabel lengkap dibuat dengan menggabungkan <VariablePrefix>, titik, dan nama yang Anda tentukan dalam {kurung kurawal} di elemen <Pattern> atau elemen <Variable>. Misalnya: myprefix.id, myprefix.dbncode, atau myprefix.oauthtoken.

<VariablePrefix>myprefix</VariablePrefix>

Misalnya, nilai nama adalah "user".

  • Jika <VariablePrefix> tidak ditentukan, nilai yang diekstrak akan ditetapkan ke variabel bernama user.
  • Jika <VariablePrefix> ditentukan sebagai myprefix, nilai yang diekstrak akan ditetapkan ke variabel bernama myprefix.user.
Default: T/A
Kehadiran: Opsional
Jenis: String

Elemen <IgnoreUnresolvedVariables>

(Opsional) Tetapkan ke true untuk memperlakukan variabel yang tidak dapat diselesaikan sebagai string kosong (null). Setel ke false jika Anda ingin kebijakan menampilkan error saat ada variabel yang dirujuk dan tidak dapat diselesaikan.

<IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
Default: Salah
Kehadiran: Opsional
Jenis: Boolean

Elemen <URIPath>

(Opsional, tetapi lihat baris Kehadiran dalam tabel di bawah untuk mengetahui informasi selengkapnya.) Mengekstrak nilai dari proxy.pathsuffix pesan sumber request. Jalur yang diterapkan ke pola adalah proxy.pathsuffix, yang tidak menyertakan basepath untuk Proxy API. Jika pesan sumber di-resolve ke jenis pesan response, maka elemen ini tidak melakukan apa pun.

<URIPath>
   <Pattern ignoreCase="false">/accounts/{id}</Pattern>
</URIPath>

Anda dapat menggunakan beberapa elemen <Pattern>:

<URIPath>
   <Pattern ignoreCase="false">/accounts/{id}</Pattern>
   <Pattern ignoreCase="false">/accounts/{id}/transactions/{index}</Pattern>
</URIPath>
Default: T/A
Kehadiran: Opsional. Namun, Anda harus menyertakan setidaknya salah satu dari berikut ini: <URIPath>, <QueryParam>, <Header>, <FormParam>, <JSONPayload>, atau <XMLPayload>.
Jenis: T/A

Atribut

Atribut Deskripsi Default Kehadiran Jenis
ignoreCase Menentukan untuk mengabaikan huruf besar/kecil saat mencocokkan pola.

false

 Opsional Boolean

Elemen <QueryParam>

(Opsional, tetapi lihat baris Kehadiran dalam tabel di bawah untuk mengetahui informasi selengkapnya.) Mengekstrak nilai dari parameter kueri yang ditentukan dari pesan sumber request. Jika pesan sumber di-resolve ke jenis pesan response, maka elemen ini tidak melakukan apa pun.

<QueryParam name="code">
   <Pattern ignoreCase="true">DBN{dbncode}</Pattern>
</QueryParam>

Jika beberapa parameter kueri memiliki nama yang sama, gunakan indeks untuk merujuk parameter:

<QueryParam name="w.2">
   <Pattern ignoreCase="true">{secondW}</Pattern>
</QueryParam>
Default: T/A
Kehadiran: Opsional. Namun, Anda harus menyertakan setidaknya salah satu dari berikut ini: <URIPath>, <QueryParam>, <Header>, <FormParam>, <JSONPayload>, atau <XMLPayload>.
Jenis: T/A

Atribut

Atribut Deskripsi Default Kehadiran Jenis
nama Menentukan nama parameter kueri. Jika beberapa parameter kueri memiliki nama yang sama, gunakan referensi berindeks, dengan instance pertama parameter kueri tidak memiliki indeks, yang kedua berada di indeks 2, yang ketiga di indeks 3, dll.

T/A

 Wajib String

Elemen <Header>

(Opsional, tetapi lihat baris Kehadiran dalam tabel di bawah untuk mengetahui informasi selengkapnya.) Mengekstrak nilai dari header HTTP yang ditentukan dari pesan request atau response yang ditentukan. Jika beberapa header memiliki nama yang sama, nilainya disimpan dalam array.

<!-- The name is the actual header name. -->
<Header name="Authorization">
<!-- Provide a name for your new custom variable here. -->
   <Pattern ignoreCase="false">Bearer {oauthtoken}</Pattern>
</Header>

Jika beberapa header memiliki nama yang sama, gunakan indeks untuk merujuk ke setiap header dalam array:

<Header name="myHeader.2">
   <Pattern ignoreCase="true">{secondHeader}</Pattern>
</Header>

Atau yang berikut untuk mencantumkan semua header dalam array:

<Header name="myHeader.values">
   <Pattern ignoreCase="true">{myHeaders}</Pattern>
</Header>
Default: T/A
Kehadiran: Opsional. Namun, Anda harus menyertakan setidaknya salah satu dari berikut ini: <URIPath>, <QueryParam>, <Header>, <FormParam>, <JSONPayload>, atau <XMLPayload>.
Jenis: T/A

Atribut

Atribut Deskripsi Default Kehadiran Jenis
nama Menentukan nama header tempat Anda mengekstrak nilai. Jika beberapa header memiliki nama yang sama, gunakan referensi berindeks, dengan instance pertama header tidak memiliki indeks, yang kedua berada di indeks 2, yang ketiga di indeks 3, dll. Gunakan .values untuk mendapatkan semua header dalam array.

T/A

 Wajib String

Elemen <FormParam>

(Opsional, tetapi lihat baris Kehadiran dalam tabel di bawah untuk mengetahui informasi selengkapnya.) Mengekstrak nilai dari parameter formulir tertentu dari pesan request atau response tertentu. Parameter formulir hanya dapat diekstrak jika header Content-Type dari pesan yang ditentukan adalah application/x-www-form-urlencoded.

<FormParam name="greeting">
    <Pattern>hello {user}</Pattern>
</FormParam>
Default: T/A
Kehadiran: Opsional. Namun, Anda harus menyertakan setidaknya salah satu dari berikut ini: <URIPath>, <QueryParam>, <Header>, <FormParam>, <JSONPayload>, atau <XMLPayload>.
Jenis: T/A

Atribut

Atribut Deskripsi Default Kehadiran Jenis
nama Nama parameter formulir tempat Anda mengekstrak nilai.

T/A

 Wajib String

Elemen <Variable>

(Opsional, tetapi lihat baris Kehadiran dalam tabel di bawah untuk mengetahui informasi selengkapnya.) Menentukan nama variabel yang akan diekstrak nilainya. 

<Variable name="myVar">
    <Pattern>hello {user}</Pattern>
</Variable>

Untuk mengekstrak dua nilai dari variabel:

<Variable name="myVar">
   <Pattern>hello {firstName} {lastName}</Pattern>
</Variable>
Default: T/A
Kehadiran: Opsional. Namun, Anda harus menyertakan setidaknya salah satu dari berikut ini: <URIPath>, <QueryParam>, <Header>, <FormParam>, <JSONPayload>, atau <XMLPayload>.
Jenis: T/A

Atribut

Atribut Deskripsi Default Kehadiran Jenis
nama Nama variabel yang akan diekstrak nilainya.

T/A

 Wajib String

Elemen <JSONPayload>

(Opsional, tetapi lihat baris Kehadiran dalam tabel di bawah untuk mengetahui informasi selengkapnya.) Menentukan pesan berformat JSON yang akan digunakan untuk mengekstrak nilai variabel. Ekstraksi JSON hanya dilakukan jika header Content-Type pesan adalah application/json.

<JSONPayload>
   <Variable name="name" type="string">
      <JSONPath>{example}</JSONPath>
   </Variable>
</JSONPayload>
Default: T/A
Kehadiran: Opsional. Namun, Anda harus menyertakan setidaknya salah satu dari berikut ini: <URIPath>, <QueryParam>, <Header>, <FormParam>, <JSONPayload>, atau <XMLPayload>.
Jenis: T/A

Elemen <JSONPayload>/<Variable>

(Wajib dalam elemen JSONPayload.) Menentukan variabel tempat nilai yang diekstrak ditetapkan. Anda dapat menyertakan beberapa tag <Variable> dalam elemen <JSONPayload> untuk mengisi beberapa variabel.

<Variable name="name" type="string">
   <JSONPath>{example}</JSONPath>
</Variable>
Default: T/A
Kehadiran: Wajib ada dalam elemen JSONPayload.
Jenis: T/A

Atribut

Atribut Deskripsi Default Kehadiran Jenis
nama

Menentukan nama variabel yang akan diberi nilai yang diekstrak.

nama

 Wajib String
jenis Menentukan jenis data nilai variabel. T/A Opsional

String. Pilih dari:

  • string
  • boolean
  • bilangan bulat
  • long
  • float
  • double
  • nodeset (mengembalikan fragmen JSON)

Elemen <JSONPayload>/<Variable>/<JSONPath>

(Wajib dalam elemen JSONPayload:Variable.) Menentukan jalur JSON yang digunakan untuk mengekstrak nilai dari pesan berformat JSON. 

<Variable name="name">
  <JSONPath>$.rss.channel.title</JSONPath>
</Variable>
Default: T/A
Kehadiran: Wajib
Jenis: String

Elemen <XMLPayload>

(Opsional, tetapi lihat baris Kehadiran dalam tabel di bawah untuk mengetahui informasi selengkapnya.) Menentukan pesan berformat XML yang akan digunakan untuk mengekstrak nilai variabel. Payload XML hanya diekstrak jika header Content-Type pesan adalah text/xml, application/xml, atau application/*+xml.

<XMLPayload stopPayloadProcessing="false">
  <Namespaces>
    <Namespace prefix="apigee">http://www.apigee.com</Namespace>
    <Namespace prefix="gmail">http://mail.google.com</Namespace>
  </Namespaces>
  <Variable name="name" type="boolean">
    <XPath>/apigee:test/apigee:example</XPath>
  </Variable>
</XMLPayload>
Default: T/A
Kehadiran: Opsional. Namun, Anda harus menyertakan setidaknya salah satu dari berikut ini: <URIPath>, <QueryParam>, <Header>, <FormParam>, <JSONPayload>, atau <XMLPayload>.
Jenis: T/A

Atribut

Atribut Deskripsi Default Kehadiran Jenis
stopPayloadProcessing

Tetapkan ke true untuk menghentikan evaluasi XPath setelah satu variabel diisi. Artinya, hanya satu variabel yang diisi oleh kebijakan.

false

 Opsional Boolean

<XMLPayload>/<Namespaces> element

(Opsional) Menentukan namespace yang akan digunakan dalam evaluasi XPath. Jika Anda menggunakan namespace dalam ekspresi XPath, Anda harus mendeklarasikan namespace di sini, seperti yang ditunjukkan dalam contoh berikut.

<XMLPayload stopPayloadProcessing="false">
  <Namespaces>
     <Namespace prefix="apigee">http://www.apigee.com</Namespace>
     <Namespace prefix="gmail">http://mail.google.com</Namespace>
  </Namespaces>
  <Variable name="legName" type="string">
    <XPath>/apigee:Directions/apigee:route/apigee:leg/apigee:name</XPath>
  </Variable>
</XMLPayload>

Jika Anda tidak menggunakan namespace dalam ekspresi XPath, Anda dapat menghapus atau mengomentari elemen <Namespaces>, seperti yang ditunjukkan contoh berikut:

<XMLPayload stopPayloadProcessing="false">
  <!-- <Namespaces/> -->
  <Variable name="legName" type="string">
    <XPath>/Directions/route/leg/name</XPath>
  </Variable>
</XMLPayload>
Default: T/A
Kehadiran: Opsional
Jenis: String

Atribut

Atribut Deskripsi Default Kehadiran Jenis
prefix

Awalan namespace.

T/A

 Wajib String

<XMLPayload>/<Variable> element

(Opsional) Menentukan variabel yang akan diberi nilai yang diekstrak.

<Variable name="name" type="boolean">
   <XPath>/test/example</XPath>
</Variable>
Default: T/A
Kehadiran: Opsional
Jenis: T/A

Atribut

Atribut Deskripsi Default Kehadiran Jenis
nama

Menentukan nama variabel yang akan diberi nilai yang diekstrak.

nama

 Wajib String
jenis Menentukan jenis data nilai variabel. Boolean Opsional

String. Pilih dari:

  • string
  • boolean
  • bilangan bulat
  • long
  • float
  • double
  • nodeset (menampilkan fragmen XML)

Elemen <XMLPayload>/<Variable>/<XPath>

(Wajib dalam elemen XMLPayload:Variable.) Menentukan XPath yang ditentukan untuk variabel. Hanya ekspresi XPath 1.0 yang didukung.

<Variable name="name" type="boolean">
   <XPath>/test/example</XPath>
</Variable>

Contoh dengan namespace. Jika Anda menggunakan namespace dalam ekspresi XPath, Anda harus mendeklarasikan namespace dalam bagian <XMLPayload><Namespaces> kebijakan.

<Variable name="name" type="boolean">
   <XPath>/foo:test/foo:example</XPath>
</Variable>
Default: T/A
Kehadiran: Wajib
Jenis: String

Referensi error

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code HTTP status Cause Fix
steps.extractvariables.ExecutionFailed 500

This error occurs when:

  • The input payload (JSON, XML) is empty.
  • The input (JSON, XML, etc) passed to the policy is invalid or malformed.
steps.extractvariables.ImmutableVariable 500 A variable used in the policy is immutable. The policy was unable to set this variable. N/A
steps.extractvariables.InvalidJSONPath 500 This error occurs if an invalid JSON path is used in the JSONPath element of the policy. For example, if a JSON payload does not have the object Name, but you specify Name as the path in the policy, then this error occurs.
steps.extractvariables.JsonPathParsingFailure 500 This error occurs when the policy is unable to parse a JSON path and extract data from the flow variable specified in Source element. Typically this happens if the flow variable specified in the Source element does not exist in the current flow.
steps.extractvariables.SetVariableFailed 500 This error occurs if the policy could not set the value to a variable. The error generally happens if you try to assign values to multiple variables whose names start with the same words in a nested dot-separated format.
steps.extractvariables.SourceMessageNotAvailable 500 This error occurs if the message variable specified in the Source element of the policy is either:
  • Out of scope (not available in the specific flow where the policy is being executed) or
  • Can't be resolved (is not defined)
steps.extractvariables.UnableToCast 500 This error occurs if the policy was unable to cast the extracted value to a variable. Typically this happens if you attempt to set the value of one data type to a variable of another data type.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name Cause Fix
NothingToExtract If the policy does not have any of the elements URIPath, QueryParam, Header, FormParam, XMLPayload, or JSONPayload, the deployment of the API Proxy fails, because there's nothing to extract.
NONEmptyPrefixMappedToEmptyURI This error occurs if the policy has a prefix defined in the Namespace element under the XMLPayload element, but no URI is defined.
DuplicatePrefix This error occurs if the policy has the same prefix defined more than once in the Namespace element under the XMLPayload element.
NoXPathsToEvaluate If the policy does not have the XPath element within the XMLPayload element, then the deployment of the API proxy fails with this error.
EmptyXPathExpression If the policy has an empty XPath expression within the XMLPayload element, then the deployment of the API proxy fails.
NoJSONPathsToEvaluate If the policy does not have the JSONPath element within the JSONPayload element, then the deployment of the API proxy fails with this error.
EmptyJSONPathExpression If the policy has an empty XPath expression within the XMLPayload element, then the deployment of the API proxy fails.
MissingName If the policy does not have the name attribute in any of the policy elements like QueryParam, Header, FormParam or Variable, where it is required, then the deployment of the API proxy fails.
PatternWithoutVariable If the policy does not have a variable specified within the Pattern element, then the deployment of the API proxy fails. The Pattern element requires the name of the variable in which extracted data will be stored.
CannotBeConvertedToNodeset If the policy has an XPath expression where the Variable type is defined as nodeset, but the expression cannot be converted to nodeset, then the deployment of the API proxy fails.
JSONPathCompilationFailed The policy could not compile a specified JSON Path. N/A
InstantiationFailed The policy could not be instantiated. N/A
XPathCompilationFailed If the prefix or the value used in the XPath element is not part of any of the declared namespaces in the policy, then the deployment of the API proxy fails.
InvalidPattern If the Pattern element definition is invalid in any of the elements like URIPath, QueryParam, Header, FormParam, XMLPayload or JSONPayload within the policy, then the deployment of the API proxy fails.

Fault variables

These variables are set when this policy triggers an error at runtime. For more information, see What you need to know about policy errors.

Variables Where Example
fault.name="fault_name" fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. fault.name = "SourceMessageNotAvailable"
extractvariables.policy_name.failed policy_name is the user-specified name of the policy that threw the fault. extractvariables.EV-ParseJsonResponse.failed = true

Example error response

{
   "fault":{
      "detail":{
         "errorcode":"steps.extractvariables.SourceMessageNotAvailable"
      },
      "faultstring":"request message is not available for ExtractVariable: EV-ParseJsonResponse"
   }
}

Example fault rule

<FaultRule name="Extract Variable Faults">
    <Step>
        <Name>AM-CustomErrorMessage</Name>
        <Condition>(fault.name = "SourceMessageNotAvailable") </Condition>
    </Step>
    <Condition>(extractvariables.EM-ParseJsonResponse.failed = true) </Condition>
</FaultRule>

Skema

Topik terkait

Referensi variabel Flow