شما در حال مشاهده مستندات Apigee Edge هستید.
به مستندات Apigee X مراجعه کنید . اطلاعات
در این مبحث، یاد خواهید گرفت که چگونه با استفاده از ترکیب سیاستها، یک ترکیب ایجاد کنید. ترکیب سیاستها یک الگوی پروکسی Apigee است که به شما امکان میدهد نتایج چندین هدف backend را با استفاده از سیاستها در یک پاسخ واحد ترکیب کنید.
برای مرور کلی ترکیب سیاست، به «الگوی ترکیب سیاست» در الگوهای کتاب آشپزی API Proxy مراجعه کنید.
کد نمونه را دانلود و امتحان کنید
درباره این نمونه کتاب آشپزی
این مثال از کتاب آشپزی، یک الگوی پروکسی API به نام ترکیب سیاست (policy composition ) را نشان میدهد. این الگو یک راه (راههای دیگری نیز وجود دارد) برای ترکیب دادهها از منابع مختلف backend ارائه میدهد. به طور کلی، این مبحث نشان میدهد که چگونه میتوان سیاستها را ترکیب و به هم زنجیر کرد تا نتیجه مطلوب حاصل شود. برای مرور کلی این الگو و سایر الگوهای مرتبط، به الگوهای API Proxy Cookbook مراجعه کنید.
مثالی که در اینجا مورد بحث قرار گرفته است، از ترکیب سیاستها برای ترکیب دادهها از این دو API عمومی جداگانه استفاده میکند:
- API مربوط به مختصات جغرافیایی گوگل : این API آدرسها (مانند "1600 Amphitheatre Parkway, Mountain View, CA") را به مختصات جغرافیایی (مانند عرض جغرافیایی 37.423021 و طول جغرافیایی -122.083739) تبدیل میکند.
- API ارتفاع گوگل (Google Elevation API) این API یک رابط کاربری ساده برای جستجوی دادههای ارتفاعی مکانها روی زمین ارائه میدهد. در این مثال، مختصات برگردانده شده از 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 Proxy مراجعه کنید.
قبل از اینکه این مثال کتاب آشپزی را بررسی کنید، باید با این مفاهیم اساسی نیز آشنا باشید:
- سیاستها چیستند و چگونه میتوان آنها را به پروکسیها متصل کرد. برای آشنایی بیشتر با سیاستها، به «سیاست چیست؟» مراجعه کنید.
- ساختار جریان یک پروکسی API، همانطور که در پیکربندی جریانها توضیح داده شده است. جریانها به شما امکان میدهند توالی اجرای سیاستها توسط یک پروکسی API را مشخص کنید. در این مثال، چندین سیاست ایجاد شده و به جریان پروکسی API اضافه میشوند.
- نحوه سازماندهی یک پروژه پروکسی API در سیستم فایل شما، همانطور که در مرجع پیکربندی پروکسی API توضیح داده شده است. این مبحث کتاب آشپزی، توسعه محلی (مبتنی بر سیستم فایل) را در مقابل توسعه مبتنی بر ابر نشان میدهد که در آن میتوانید از رابط کاربری مدیریت برای توسعه پروکسی API استفاده کنید.
- استفاده از اعتبارسنجی کلید API. این سادهترین شکل امنیت مبتنی بر برنامه است که میتوانید برای یک API پیکربندی کنید. برای اطلاعات بیشتر به کلیدهای API مراجعه کنید. همچنین میتوانید آموزش Secure an API by requireing API keys را مطالعه کنید.
- دانش کاربردی 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 Geocoding ارسال خواهد شد.

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

مانند قبل، ابتدا نگاهی به کد میاندازیم. توضیح مفصل در ادامه آمده است. میتوانید اطلاعات بیشتر در مورد این سیاست را در Service Callout policy مطالعه کنید. در نمونه دانلود، میتوانید این 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> - همانند سیاست قبلی، این سیاست نیز نامی دارد.
- <متغیر درخواست> - این متغیری است که در سیاست AssignMessage ایجاد شده است. این متغیر، درخواست ارسالی به API بکاند را کپسولهسازی میکند.
- <Response> - این عنصر متغیری را نام میبرد که پاسخ در آن ذخیره میشود. همانطور که خواهید دید، این متغیر بعداً توسط سیاست ExtractVariables قابل دسترسی خواهد بود.
- <HTTPTargetConnection> - آدرس اینترنتی (URL) هدف API بکاند را مشخص میکند. در این حالت، مشخص میکنیم که API یک پاسخ JSON برگرداند.
حالا ما دو سیاست داریم، یکی که اطلاعات درخواست مورد نیاز برای استفاده از API بکاند (API ژئوکدینگ گوگل) را مشخص میکند، و دومی که درخواست را به 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> - این عنصر دادههای پاسخ مورد نظر ما را بازیابی کرده و در متغیرهای نامگذاری شده قرار میدهد. در واقع، API ژئوکدینگ اطلاعات بسیار بیشتری از طول و عرض جغرافیایی را برمیگرداند. با این حال، اینها تنها مقادیری هستند که برای این نمونه نیاز داریم. میتوانید رندر کاملی از JSON برگردانده شده توسط API ژئوکدینگ را در مستندات API مشاهده کنید. مقادیر geometry.location.lat و geometry.location.lng صرفاً دو فیلد از فیلدهای متعدد موجود در شیء JSON برگردانده شده هستند.
شاید واضح نباشد، اما مهم است که بدانیم ExtractVariables دو متغیر تولید میکند که نام آنها شامل پیشوند متغیر (geocoderesponse) و نام واقعی متغیرها است که در سیاست مشخص شدهاند. این متغیرها در پروکسی API ذخیره میشوند و همانطور که خواهید دید، برای سایر سیاستهای درون جریان پروکسی در دسترس خواهند بود. متغیرها عبارتند از:
- geocoderesponse.latitude
- طول جغرافیایی
اکنون بیشتر کار انجام شده است. ما ترکیبی از سه سیاست ایجاد کردهایم که یک درخواست را تشکیل میدهند، یک API بکاند را فراخوانی میکنند و دادههای JSON بازگشتی را تجزیه میکنند. در مراحل پایانی، دادهها را از این بخش از جریان به یک سیاست AssignMessage دیگر وارد میکنیم، API بکاند دوم (Google Elevation API) را فراخوانی میکنیم و دادههای ترکیبشده خود را به توسعهدهنده برنامه بازمیگردانیم.
درخواست دوم را با AssignMessage ایجاد کنید
خطمشی AssignMessage زیر از متغیرهایی که از اولین backend (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> اگر API مربوط به Google Elevation را بررسی کنید، خواهید دید که دو پارامتر پرسوجو دریافت میکند. پارامتر اول locations نام دارد و مقدار آن طول و عرض جغرافیایی (مقادیر جدا شده با کاما) است. پارامتر دیگر sensor است که الزامی است و باید مقدار آن درست یا نادرست باشد. مهمترین نکتهای که در این مرحله باید به آن توجه داشت این است که پیام درخواستی که در اینجا ایجاد میکنیم نیازی به ServiceCallout ندارد. در این مرحله نیازی به فراخوانی API دوم از ServiceCallout نداریم زیرا میتوانیم API بکاند را از TargetEndpoint پروکسی فراخوانی کنیم. اگر در مورد آن فکر کنید، تمام دادههایی را که برای فراخوانی API مربوط به Google Elevations نیاز داریم، در اختیار داریم. پیام درخواست ایجاد شده در این مرحله نیازی به ServiceCallout ندارد، زیرا درخواستی است که برای خط لوله درخواست اصلی ایجاد شده است و بنابراین به سادگی توسط ProxyEndpoint به 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 proxy را دانلود کردهاید، میتوانید 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>
حالا، فقط باید پاسخ دریافتی از API مربوط به Google Elevation را پردازش کنیم و کار تمام است.
تبدیل پاسخ از XML به JSON
در این مثال، پاسخ از API مربوط به Google Elevation به صورت 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 بکاند بازیابی شده، با سیاستهای متصل به پروکسی API ترکیب شده و در یک پاسخ واحد به کلاینت بازگردانده شدهاند.
{ "country":"us", "postalcode":"08008", "elevation":{ "meters":0.5045232, "feet":1.6552599030345978 }, "location":{ "latitude":39.75007129999999, "longitude":-74.1357407 } }
خلاصه
این مبحث از کتاب آشپزی توضیح داد که چگونه از الگوی ترکیب سیاست برای ایجاد ترکیبی از دادهها از منابع پشتیبان متعدد استفاده کنید. ترکیب سیاست یک الگوی رایج است که در توسعه پروکسی API برای افزودن قابلیتهای خلاقانه به API شما استفاده میشود.