استفاده از ترکیب خط مشی

شما در حال مشاهده اسناد Apigee Edge هستید.
به مستندات Apigee X بروید . اطلاعات

در این مبحث، نحوه ایجاد یک mashup با استفاده از ترکیب خط مشی را یاد خواهید گرفت. ترکیب خط مشی یک الگوی پروکسی Apigee است که به شما امکان می دهد نتایج حاصل از چندین هدف باطن را در یک پاسخ واحد با استفاده از خط مشی ها ترکیب کنید.

برای یک نمای کلی از ترکیب خط مشی، به «الگوی ترکیب خط مشی» در الگوهای کتاب آشپزی پروکسی API مراجعه کنید.

کد نمونه را دانلود و امتحان کنید

در مورد این مثال کتاب آشپزی

این مثال کتاب آشپزی یک الگوی پروکسی API به نام ترکیب خط مشی را نشان می دهد. این الگو یک راه (راه های دیگری نیز وجود دارد) را برای ترکیب کردن داده ها از چندین منبع پشتیبان فراهم می کند. به طور کلی، این موضوع نشان می دهد که چگونه می توان سیاست ها را با هم ترکیب کرد و به یک نتیجه دلخواه داد. برای یک نمای کلی از این الگو و سایر موارد مرتبط، به الگوهای کتاب آشپزی پروکسی API مراجعه کنید.

مثال مورد بحث در اینجا از ترکیب خط مشی برای ترکیب کردن داده ها از این دو API عمومی مجزا استفاده می کند:

  • Google Geocoding API : این API آدرس‌ها (مانند «1600 Amphitheatre Parkway, Mountain View, CA») را به مختصات جغرافیایی (مانند عرض جغرافیایی 37.423021 و طول جغرافیایی -122.083739) تبدیل می‌کند.
  • Google Elevation API این API یک رابط ساده برای جستجوی مکان‌های روی زمین برای داده‌های ارتفاعی فراهم می‌کند. در این مثال، مختصات بازگشتی از Geocoding API به عنوان ورودی در این API استفاده می شود.

توسعه دهندگان برنامه این پروکسی API را با دو پارامتر جستجو، یک کد پستی و یک شناسه کشور فراخوانی خواهند کرد:

$ curl "http://{myorg}-test.apigee.net/policy-mashup-cookbook?country=us&postalcode=08008"

پاسخ یک شی JSON است که شامل موقعیت جغرافیایی (طول/طول جغرافیایی) برای مرکز منطقه کد پستی ارائه شده همراه با ارتفاع در آن مکان جغرافیایی کد شده است. 

{  
   "ElevationResponse":{  
      "status":"OK",
      "result":{  
         "location":{  
            "lat":"39.7500713",
            "lng":"-74.1357407"
         },
         "elevation":"0.5045232",
         "resolution":"76.3516159"
      }
   }
}

قبل از شروع

اگر مایلید یک نمای کلی از الگوی ترکیب خط مشی بخوانید، به "الگوی ترکیب خط مشی" در الگوهای کتاب آشپزی پروکسی API مراجعه کنید.

قبل از بررسی این مثال کتاب آشپزی، باید با این مفاهیم اساسی نیز آشنا باشید:

  • سیاست ها چیست و چگونه به پروکسی ها متصل شوند. برای معرفی خوب سیاست‌ها، نگاه کنید به سیاست چیست؟ .
  • ساختار یک جریان پروکسی API، همانطور که در پیکربندی جریان ها توضیح داده شده است. جریان ها به شما امکان می دهند دنباله ای را که در آن خط مشی ها توسط یک پراکسی API اجرا می شوند، مشخص کنید. در این مثال، چندین خط مشی ایجاد شده و به جریان پروکسی API اضافه می شود.
  • چگونه یک پروژه پروکسی API در سیستم فایل شما سازماندهی می شود، همانطور که در مرجع پیکربندی پروکسی API توضیح داده شده است. این مبحث کتاب آشپزی توسعه محلی (مبتنی بر سیستم فایل) را بر خلاف توسعه مبتنی بر ابر نشان می دهد که در آن می توانید از رابط کاربری مدیریت برای توسعه پروکسی API استفاده کنید.
  • استفاده از اعتبار سنجی کلید API. این ساده ترین شکل امنیت مبتنی بر برنامه است که می توانید برای یک API پیکربندی کنید. برای اطلاعات بیشتر به کلیدهای API مراجعه کنید. همچنین می توانید با نیاز به آموزش کلیدهای API از طریق Secure an API قدم بزنید.
  • دانش کاری XML در این مثال، ما پروکسی API و خط‌مشی‌های آن را با فایل‌های XML که در سیستم فایل قرار دارند، می‌سازیم.

اگر کد نمونه را دانلود کرده اید، می توانید تمام فایل های مورد بحث در این مبحث را در پوشه نمونه mashup-policy-cookbook پیدا کنید. بخش‌های زیر به تفصیل کد نمونه را توضیح می‌دهند.

با جریان رفتن

قبل از رفتن به خط‌مشی‌ها، اجازه دهید نگاهی به جریان اصلی پروکسی API نمونه خود بیاندازیم. جریان XML، که در زیر نشان داده شده است، چیزهای زیادی در مورد این پراکسی، خط مشی هایی که استفاده می کند و محل فراخوانی آن خط مشی ها به ما می گوید.

در دانلود نمونه، می توانید این XML را در فایل doc-samples/policy-mashup-cookbook/apiproxy/proxies/default.xml بیابید.

<ProxyEndpoint name="default">
  <Flows>
    <Flow name="default">
      <Request>
            <!-- Generate request message for the Google Geocoding API -->
            <Step><Name>GenerateGeocodingRequest</Name></Step>
            <!-- Call the Google Geocoding API -->
            <Step><Name>ExecuteGeocodingRequest</Name></Step>
            <!-- Parse the response and set variables -->
            <Step><Name>ParseGeocodingResponse</Name></Step>
            <!-- Generate request message for the Google Elevation API -->
            <Step><Name>AssignElevationParameters</Name></Step>
      </Request>
      <Response>
            <!-- Parse the response message from the Elevation API -->
            <Step><Name>ParseElevationResponse</Name></Step>
            <!-- Generate the final JSON-formatted response with JavaScript -->
            <Step><Name>GenerateResponse</Name></Step>
      </Response>
    </Flow>
  </Flows>

  <HTTPProxyConnection>
    <!-- Add a base path to the ProxyEndpoint for URI pattern matching-->
    <BasePath>/policy-mashup-cookbook</BasePath>
    <!-- Listen on both HTTP and HTTPS endpoints -->
    <VirtualHost>default</VirtualHost>
    <VirtualHost>secure</VirtualHost>
  </HTTPProxyConnection>
  <RouteRule name="default">
    <!-- Connect ProxyEndpoint to named TargetEndpoint under /targets -->
    <TargetEndpoint>default</TargetEndpoint>
  </RouteRule>
</ProxyEndpoint>

در اینجا خلاصه ای از عناصر جریان آورده شده است.

  • <Request> - عنصر <Request> از چندین عنصر <Step> تشکیل شده است. هر مرحله یکی از خط‌مشی‌هایی را می‌خواند که در ادامه این مبحث ایجاد خواهیم کرد. این خط مشی ها مربوط به ایجاد یک پیام درخواست، ارسال آن و تجزیه پاسخ هستند. در پایان این مبحث، نقش هر یک از این سیاست ها را درک خواهید کرد.
  • <Response> - عنصر <Response> همچنین شامل <Steps> است. این مراحل همچنین خط‌مشی‌هایی را فراخوانی می‌کنند که مسئول پردازش پاسخ نهایی از نقطه پایانی هدف هستند (Google Elevation API).
  • <HttpProxyConnection> - این عنصر جزئیات مربوط به نحوه اتصال برنامه ها به این پراکسی API را مشخص می کند، از جمله <BasePath>، که مشخص می کند این API چگونه فراخوانی شود.
  • <RouteRule> - این عنصر مشخص می کند که بلافاصله پس از پردازش پیام های درخواست ورودی چه اتفاقی می افتد. در این حالت TargetEndpoint فراخوانی می شود. در ادامه در این مبحث درباره این مرحله مهم بیشتر بحث خواهیم کرد.

ایجاد سیاست ها

بخش‌های زیر هر یک از خط‌مشی‌هایی را که این نمونه ترکیب خط‌مشی را تشکیل می‌دهند، مورد بحث قرار می‌دهند.

اولین خط مشی AssignMessage را ایجاد کنید

اولین خط مشی AssignMessage که در زیر فهرست شده است، یک پیام درخواستی ایجاد می کند که به سرویس کدگذاری جغرافیایی Google ارسال می شود.

بیایید با کد خط مشی شروع کنیم و سپس عناصر آن را با جزئیات بیشتر توضیح خواهیم داد. در دانلود نمونه، می‌توانید این XML را در فایل doc-samples/policy-mashup-cookbook/apiproxy/policies/GenerateGeocodingRequest.xml بیابید.

<AssignMessage name="GenerateGeocodingRequest">
  <AssignTo createNew="true" type="request">GeocodingRequest</AssignTo>
  <Set>
    <QueryParams>
      <QueryParam name="address">{request.queryparam.postalcode}</QueryParam>
      <QueryParam name="region">{request.queryparam.country}</QueryParam>
      <QueryParam name="sensor">false</QueryParam>
    </QueryParams>
    <Verb>GET</Verb>
  </Set>
  <!-- Set variables for use in the final response -->
  <AssignVariable>
    <Name>PostalCode</Name>
    <Ref>request.queryparam.postalcode</Ref>
  </AssignVariable>
  <AssignVariable>
    <Name>Country</Name>
    <Ref>request.queryparam.country</Ref>
  </AssignVariable>
</AssignMessage>

در اینجا توضیح مختصری از عناصر این سیاست ارائه شده است. می‌توانید درباره این خط‌مشی در Assign Message Policy اطلاعات بیشتری کسب کنید.

  • <AssignMessage name> - به این خط مشی یک نام می دهد. این نام زمانی استفاده می شود که خط مشی در یک جریان ارجاع داده شود.
  • <AssignTo> - یک متغیر با نام به نام GeocodingRequest ایجاد می کند. این متغیر شی درخواستی را که توسط خط مشی ServiceCallout به backend ارسال می شود، محصور می کند.
  • <QueryParams> - پارامترهای پرس و جو را که برای فراخوانی API backend مورد نیاز است را تنظیم می کند. در این مورد، API Geocoding باید مکان را که با کد پستی و شناسه کشور بیان می‌شود، بداند. کاربر برنامه این اطلاعات را ارائه می کند و ما به سادگی آن را در اینجا استخراج می کنیم. پارامتر sensor توسط API مورد نیاز است، و درست یا نادرست است، و ما در اینجا فقط آن را به false تبدیل می‌کنیم.
  • <Verb> - در این مورد، ما یک درخواست GET ساده به API ارائه می کنیم.
  • <AssignVariable> - این متغیرها مقادیری را که ما به API ارسال می کنیم ذخیره می کنند. در این مثال، متغیرها بعداً در پاسخی که به مشتری بازگردانده می شود، قابل دسترسی خواهند بود.

درخواست را با ServiceCallout ارسال کنید

گام بعدی در دنباله ترکیب خط مشی، ایجاد یک خط مشی ServiceCallout است. خط‌مشی ServiceCallout، که در زیر فهرست شده است، شی درخواستی را که در خط‌مشی AssignMessage قبلی ایجاد کرده‌ایم به سرویس Google Geocoding ارسال می‌کند و نتیجه را در متغیری به نام GeocodingResponse ذخیره می‌کند.

مانند قبل، اجازه دهید ابتدا کد را بررسی کنیم. توضیح مفصل در ادامه می آید. می‌توانید درباره این خط‌مشی در خط‌مشی Callout Service بیشتر بخوانید. در دانلود نمونه، می‌توانید این XML را در فایل doc-samples/policy-mashup-cookbook/apiproxy/policies/ExecuteGeocodingRequest.xml بیابید.

<ServiceCallout name="ExecuteGeocodingRequest">
  <Request variable="GeocodingRequest"/>
  <Response>GeocodingResponse</Response>
  <HTTPTargetConnection>
    <URL>http://maps.googleapis.com/maps/api/geocode/json</URL>
  </HTTPTargetConnection>
</ServiceCallout>

در اینجا شرح مختصری از عناصر این سیاست آمده است.

  • <ServiceCallout> - مانند خط مشی قبلی، این یکی دارای نام است.
  • <Request variable> - این متغیری است که در خط مشی AssignMessage ایجاد شده است. این درخواست را به API پشتیبان کپسوله می کند.
  • <Response> - این عنصر متغیری را نامگذاری می کند که پاسخ در آن ذخیره می شود. همانطور که خواهید دید، این متغیر بعداً توسط سیاست ExtractVariables قابل دسترسی خواهد بود.
  • <HTTPTargetConnection> - نشانی اینترنتی هدف API باطن را مشخص می کند. در این مورد، ما مشخص می کنیم که API یک پاسخ JSON را برگرداند.

اکنون دو خط مشی داریم، یکی که اطلاعات درخواست مورد نیاز برای استفاده از backend API (API Google's Geocoding) را مشخص می کند و دومی که در واقع درخواست را به backend API ارسال می کند. بعد، ما پاسخ را رسیدگی می کنیم.

پاسخ را با ExtractVariables تجزیه کنید

خط مشی ExtractVariables مکانیزم ساده ای برای تجزیه محتوا از پیام پاسخ به دست آمده توسط یک خط مشی ServiceCallout فراهم می کند. ExtractVariables را می توان برای تجزیه JSON یا XML استفاده کرد، یا می توان از آن برای استخراج محتوا از مسیرهای URI، هدرهای HTTP، پارامترهای پرس و جو و پارامترهای فرم استفاده کرد.

در اینجا فهرستی از خط مشی ExtractVariables آمده است. می توانید اطلاعات بیشتری در مورد این خط مشی در Extract Variables Policy بخوانید. در دانلود نمونه، می توانید این XML را در فایل doc-samples/policy-mashup-cookbook/apiproxy/policies/ParseGeocodingResponse.xml بیابید.

<ExtractVariables name="ParseGeocodingResponse">
  <Source>GeocodingResponse</Source>
  <VariablePrefix>geocoderesponse</VariablePrefix>
  <JSONPayload>
    <Variable name="latitude">
       <JSONPath>$.results[0].geometry.location.lat</JSONPath>
    </Variable>
    <Variable name="longitude">
       <JSONPath>$.results[0].geometry.location.lng</JSONPath>
    </Variable>
  </JSONPayload>
</ExtractVariables>

عناصر کلیدی سیاست ExtractVariable عبارتند از:

  • <ExtractVariables name> - مجدداً از نام خط مشی برای اشاره به خط مشی زمانی که در یک جریان استفاده می شود استفاده می شود.
  • <Source> - متغیر پاسخی را که در خط مشی ServiceCallout ایجاد کردیم را مشخص می کند. این متغیری است که این خط مشی داده ها را از آن استخراج می کند.
  • <VariablePrefix> - پیشوند متغیر فضای نامی را برای سایر متغیرهای ایجاد شده در این خط مشی مشخص می کند. پیشوند می تواند هر نامی باشد، به جز نام های رزرو شده که توسط متغیرهای از پیش تعریف شده Edge تعریف شده اند.
  • <JSONPayload> - این عنصر داده های پاسخ مورد علاقه ما را بازیابی می کند و آن را در متغیرهای نامگذاری شده قرار می دهد. در واقع، Geocoding API اطلاعات بسیار بیشتری نسبت به طول و عرض جغرافیایی برمی گرداند. با این حال، این تنها مقادیری است که ما برای این نمونه نیاز داریم. می‌توانید یک رندر کامل از JSON که توسط Geocoding API بازگردانده شده است را در مستندات API مشاهده کنید. مقادیر geometry.location.lat و geometry.location.lng به سادگی دو فیلد از بسیاری از فیلدهای موجود در شی JSON برگشتی هستند.

ممکن است واضح نباشد، اما مهم است که ببینید ExtractVariables دو متغیر تولید می کند که نام آنها از پیشوند متغیر (geocoderesponse) و نام متغیرهای واقعی که در خط مشی مشخص شده است، تشکیل شده است. همانطور که خواهید دید، این متغیرها در پروکسی API ذخیره می‌شوند و برای سایر خط‌مشی‌ها در جریان پروکسی در دسترس خواهند بود. متغیرها عبارتند از:

  • geocoderesponse.latitude
  • geocoderesponse.طول جغرافیایی

اکثر کارها در حال حاضر انجام شده است. ما ترکیبی از سه خط‌مشی ایجاد کرده‌ایم که یک درخواست را تشکیل می‌دهند، یک API پشتیبان را فراخوانی می‌کنند و داده‌های JSON برگشتی را تجزیه می‌کنند. در مراحل پایانی، داده‌ها را از این بخش از جریان به خط‌مشی AssignMessage دیگری وارد می‌کنیم، API پشتیبان دوم (Google Elevation API) را فراخوانی می‌کنیم و داده‌های جمع‌شده خود را به توسعه‌دهنده برنامه برمی‌گردانیم.

درخواست دوم را با AssignMessage ایجاد کنید

خط‌مشی AssignMessage زیر از متغیرهایی استفاده می‌کند که از اولین پشتیبان (Google Geocoding) که ما ذخیره کرده‌ایم برگردانده شده‌اند و آنها را به درخواستی که برای API دوم (Google Elevation) ارسال می‌شود وصل می‌کند. همانطور که قبلاً ذکر شد، این متغیرها geocoderesponse.latitude و geocoderesponse.longitude هستند.

در دانلود نمونه، می‌توانید این XML را در فایل doc-samples/policy-mashup-cookbook/apiproxy/policies/AssignElevationParameters.xml بیابید.

<AssignMessage name="AssignElevationParameters">
<Remove>
    <QueryParams>
      <QueryParam name="country"/>
      <QueryParam name="postalcode"/>
    </QueryParams>
  </Remove>
  <Set>
    <QueryParams>
      <QueryParam name="locations">{geocoderesponse.latitude},{geocoderesponse.longitude}</QueryParam>
      <QueryParam name="sensor">false</QueryParam>
    </QueryParams>
  </Set>
</AssignMessage>

اگر Google Elevation API را بررسی کنید، خواهید دید که دو پارامتر پرس و جو می گیرد. اولین مورد locations نامیده می شود و مقدار آن طول و عرض جغرافیایی (مقادیر جدا شده با کاما) است. پارامتر دیگر sensor است که لازم است و باید درست یا نادرست باشد. مهمترین چیزی که در این مرحله باید به آن توجه داشت این است که پیام درخواستی که در اینجا ایجاد می کنیم نیازی به ServiceCallout ندارد. در این مرحله نیازی به فراخوانی API دوم از ServiceCallout نیست زیرا می‌توانیم API پشتیبان را از TargetEndpoint پروکسی فراخوانی کنیم. اگر در مورد آن فکر کنید، ما تمام داده‌هایی را داریم که برای فراخوانی Google Elevations API نیاز داریم. به TargetEndpoint، به دنبال RouteRule پیکربندی شده برای این پراکسی API. TargetEndpoint ارتباط با API راه دور را مدیریت می کند. (به یاد داشته باشید که URL برای elevation API در HTTPConnection برای TargetEndpoint تعریف شده است. اگر مایلید بیشتر بدانید اسناد Elevation API. QueryParam هایی که قبلاً ذخیره کرده بودیم، country و postalcode ، دیگر مورد نیاز نیستند، بنابراین آنها را در اینجا حذف می کنیم. .

مکث کوتاه: بازگشت به جریان

در این مرحله، ممکن است تعجب کنید که چرا ما خط مشی ServiceCallout دیگری ایجاد نمی کنیم. پس از همه، ما یک پیام دیگر ایجاد کردیم. چگونه آن پیام به هدف، Google Elevation API ارسال می شود؟ پاسخ در عنصر <RouteRule> جریان است. <RouteRule> مشخص می کند که پس از اجرای بخش <Request> جریان، با هر پیام درخواستی باقیمانده چه باید کرد. TargetEndpoint مشخص شده توسط این <RouteRule> به پراکسی API می گوید که پیام را به http://maps.googleapis.com/maps/api/elevation/xml برساند.

اگر نمونه پراکسی API را دانلود کرده اید، می توانید TargetProxy XML را در فایل doc-samples/policy-mashup-cookbook/apiproxy/targets/default.xml بیابید.

<TargetEndpoint name="default">
  <HTTPTargetConnection>
    <!-- This is where we define the target. For this sample we just use a simple URL. -->
    <URL>http://maps.googleapis.com/maps/api/elevation/xml</URL>
  </HTTPTargetConnection>
</TargetEndpoint>

اکنون، فقط باید پاسخ Google Elevation API را پردازش کنیم و کارمان تمام است.

پاسخ را از XML به JSON تبدیل کنید

در این مثال، پاسخ Google Elevation API به صورت XML برگردانده می شود. برای "اعتبار اضافی"، بیایید یک خط مشی دیگر به ترکیب خود اضافه کنیم تا پاسخ را از XML به JSON تبدیل کنیم.

این مثال از خط مشی جاوا اسکریپت به نام GenerateResponse با یک فایل منبع حاوی کد جاوا اسکریپت برای انجام تبدیل استفاده می کند. در زیر تعریف خط مشی GenerateResponse نشان داده شده است:

<Javascript name="GenerateResponse" timeout="10000">
  <ResourceURL>jsc://GenerateResponse.js</ResourceURL>
</Javascript>

فایل منبع GenerateResponse.js شامل جاوا اسکریپت مورد استفاده برای انجام تبدیل است. می توانید آن کد را در فایل doc-samples/policy-mashup-cookbook/apiproxy/resources/JSC/GenerateResponse.js مشاهده کنید.

Apigee همچنین یک خط مشی خارج از جعبه، XMLToJSON، برای تبدیل XML به JSON ارائه می دهد. می توانید ProxyEndpoint را ویرایش کنید تا به جای آن از خط مشی xmltojson نشان داده شده در زیر استفاده کنید.

<XMLToJSON name="xmltojson">
  <Options>
  </Options>
  <OutputVariable>response</OutputVariable>
  <Source>response</Source>
</XMLToJSON>

تست کردن مثال

اگر قبلاً این کار را نکرده‌اید، سعی کنید نمونه Policy-mashup-cookbook را دانلود، اجرا و اجرا کنید، که می‌توانید آن را در پوشه doc-samples در مخزن نمونه‌های Apigee Edge GitHub بیابید. فقط دستورالعمل های موجود در فایل README را در پوشه Policy-mashup-cookbook دنبال کنید. یا دستورالعمل‌های مختصر را در اینجا دنبال کنید: استفاده از نمونه پراکسی‌های API .

به طور خلاصه، می توانید API ترکیبی را به صورت زیر فراخوانی کنید. نام سازمان خود را جایگزین {myorg} کنید:

$ curl "http://{myorg}-test.apigee.net/policy-mashup-cookbook?country=us&postalcode=08008"

پاسخ شامل مکان جغرافیایی کد شده برای مرکز کد پستی ارائه شده توسط کاربر نهایی برنامه، همراه با ارتفاع در آن مکان جغرافیایی کد شده است. داده‌ها از دو API Backend بازیابی شدند، با خط‌مشی‌های متصل به پراکسی API ترکیب شدند و در یک پاسخ به مشتری بازگردانده شدند. 

{  
   "country":"us",
   "postalcode":"08008",
   "elevation":{  
      "meters":0.5045232,
      "feet":1.6552599030345978
   },
   "location":{  
      "latitude":39.75007129999999,
      "longitude":-74.1357407
   }
}

خلاصه

این موضوع کتاب آشپزی نحوه استفاده از الگوی ترکیب خط مشی را برای ایجاد ترکیبی از داده ها از چندین منبع پشتیبان توضیح می دهد. ترکیب خط مشی یک الگوی رایج است که در توسعه پروکسی API برای افزودن عملکرد خلاقانه به API شما استفاده می شود.