সার্ভিস কলআউট নীতি

আপনি Apigee Edge-এর ডকুমেন্টেশন দেখছেন।
Apigee X ডকুমেন্টেশন .info- তে যান।

কী

সার্ভিস কলআউট পলিসি আপনাকে আপনার এপিআই প্রক্সি ফ্লো থেকে অন্য কোনো সার্ভিসে কল করার সুযোগ দেয়। আপনি কোনো বাহ্যিক সার্ভিসে (যেমন একটি এক্সটার্নাল RESTful সার্ভিস এন্ডপয়েন্ট) অথবা অভ্যন্তরীণ সার্ভিসে (যেমন একই সংস্থা ও পরিবেশে থাকা কোনো এপিআই প্রক্সি) কলআউট করতে পারেন।

• এক্সটার্নাল ইউজ কেসে, আপনি আপনার প্রক্সির বাইরের কোনো থার্ড-পার্টি এপিআই-কে কলআউট করেন। থার্ড-পার্টি এপিআই থেকে প্রাপ্ত রেসপন্সটি পার্স করে আপনার এপিআই-এর রেসপন্স মেসেজে যুক্ত করা হয়, যা অ্যাপের ব্যবহারকারীদের জন্য ডেটাকে আরও সমৃদ্ধ ও সুসংহত করে। এছাড়াও, আপনি রিকোয়েস্ট ফ্লো-তে সার্ভিস কলআউট পলিসি ব্যবহার করে একটি রিকোয়েস্ট করতে পারেন এবং তারপর রেসপন্সের তথ্য এপিআই প্রক্সির টার্গেটএন্ডপয়েন্টে পাঠিয়ে দিতে পারেন।
• আরেকটি ব্যবহারের ক্ষেত্রে, আপনি এমন একটি প্রক্সিকে কল করেন যা আপনার কল করার স্থান এবং পরিবেশের মতোই একই সংস্থা ও পরিবেশে অবস্থিত। উদাহরণস্বরূপ, এটি তখন আপনার জন্য উপযোগী হতে পারে যখন আপনার কাছে এমন একটি প্রক্সি থাকে যা কিছু স্বতন্ত্র নিম্ন-স্তরের কার্যকারিতা প্রদান করে, যা এক বা একাধিক অন্য প্রক্সি ব্যবহার করবে। যেমন, একটি প্রক্সি যা একটি ব্যাকএন্ড ডেটা স্টোরের সাথে তৈরি/পড়া/আপডেট/মুছে ফেলার অপারেশনগুলো উন্মুক্ত করে, সেটি একাধিক অন্য প্রক্সির জন্য টার্গেট প্রক্সি হতে পারে, যারা ক্লায়েন্টদের কাছে ডেটা উন্মুক্ত করে।

এই পলিসি HTTP এবং HTTPS উভয় মাধ্যমেই অনুরোধ সমর্থন করে।

নমুনা

<LocalTargetConnection>
    <APIProxy>data-manager</APIProxy>
    <ProxyEndpoint>default</ProxyEndpoint>
</LocalTargetConnection>

<HTTPTargetConnection>
    <URL>http://example.com/{request.myResourcePath}</URL>
</HTTPTargetConnection>

<ServiceCallout name="ServiceCallout-GeocodingRequest1">
    <DisplayName>Inline request message</DisplayName>
    <Request variable="authenticationRequest">
      <Set>
        <QueryParams>
          <QueryParam name="address">{request.queryparam.postalcode}</QueryParam>
          <QueryParam name="region">{request.queryparam.country}</QueryParam>
          <QueryParam name="sensor">false</QueryParam>
        </QueryParams>
      </Set>
    </Request>
    <Response>GeocodingResponse</Response>
    <Timeout>30000</Timeout>
    <HTTPTargetConnection>
      <URL>http://maps.googleapis.com/maps/api/geocode/json</URL>
    </HTTPTargetConnection>
</ServiceCallout>

<ServiceCallout name="ServiceCallout-GeocodingRequest2">
    <Request clearPayload="false" variable="GeocodingRequest"/>
    <Response>GeocodingResponse</Response>
    <Timeout>30000</Timeout>
    <HTTPTargetConnection>
      <URL>http://maps.googleapis.com/maps/api/geocode/json</URL>
    </HTTPTargetConnection>
</ServiceCallout>

<ServiceCallout async="false" continueOnError="false" enabled="true" name="service-callout">
    <DisplayName>service-callout</DisplayName>
    <Properties/>
    <Request clearPayload="true" variable="myRequest">
        <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    </Request>
    <Response>myResponse</Response>
    <HTTPTargetConnection>
        <LoadBalancer>
            <Algorithm>RoundRobin</Algorithm>
            <Server name="httpbin"/>
            <Server name="yahoo"/>
        </LoadBalancer>
        <Path>/get</Path>
    </HTTPTargetConnection>
</ServiceCallout>

সার্ভিস কলআউট নীতি সম্পর্কে

এমন অনেক পরিস্থিতি রয়েছে যেখানে আপনি আপনার এপিআই প্রক্সিতে একটি সার্ভিস কলআউট পলিসি ব্যবহার করতে পারেন। উদাহরণস্বরূপ, আপনি জিওলোকেশন ডেটা, গ্রাহক রিভিউ, কোনো পার্টনারের রিটেইল ক্যাটালগ থেকে আইটেম ইত্যাদি সরবরাহ করার জন্য একটি এপিআই প্রক্সিকে কোনো এক্সটার্নাল সার্ভিসে কল করার জন্য কনফিগার করতে পারেন।

একটি কলআউট সাধারণত আরও দুটি পলিসির সাথে ব্যবহৃত হয়: অ্যাসাইন মেসেজ এবং এক্সট্র্যাক্ট ভ্যারিয়েবলস।

• অনুরোধ : বার্তা নির্ধারণ করুন (Assign Message) রিমোট সার্ভিসে পাঠানো অনুরোধ বার্তাটি পূরণ করে।

• Response : Extract Variables রেসপন্সটি পার্স করে এবং নির্দিষ্ট কন্টেন্ট বের করে।

একটি সাধারণ সার্ভিস কলআউট পলিসির গঠনে নিম্নলিখিত বিষয়গুলো অন্তর্ভুক্ত থাকে:

1. মেসেজ পলিসি নির্ধারণ : একটি রিকোয়েস্ট মেসেজ তৈরি করে, HTTP হেডার ও কোয়েরি প্যারামিটার যোগ করে, HTTP ভার্ব সেট করে, ইত্যাদি।
2. সার্ভিস কলআউট পলিসি: এটি অ্যাসাইন মেসেজ পলিসি দ্বারা তৈরি একটি মেসেজকে রেফারেন্স করে, এক্সটার্নাল কলের জন্য একটি টার্গেট ইউআরএল নির্ধারণ করে এবং টার্গেট সার্ভিস কর্তৃক ফেরত দেওয়া রেসপন্স অবজেক্টের জন্য একটি নাম নির্ধারণ করে।
   
   উন্নত পারফরম্যান্সের জন্য, আপনি সার্ভিস কলআউট রেসপন্সগুলোও ক্যাশ করতে পারেন, যেমনটি এই Apigee কমিউনিটি থ্রেডে বর্ণনা করা হয়েছে: আমি কীভাবে সার্ভিস কলআউট পলিসির ফলাফল ক্যাশে সংরক্ষণ করতে এবং পরে ক্যাশে থেকে তা পুনরুদ্ধার করতে পারি?
3. ভেরিয়েবল নিষ্কাশন নীতি : সাধারণত একটি JSONPath বা XPath এক্সপ্রেশন নির্ধারণ করে যা সার্ভিস কলআউট দ্বারা তৈরি বার্তাটি পার্স করে। এরপর এই নীতিটি সার্ভিস কলআউট প্রতিক্রিয়া থেকে পার্স করা মান ধারণকারী ভেরিয়েবলগুলো সেট করে।

সার্ভিস কলআউট পলিসির পাশাপাশি অ্যাসাইন মেসেজ এবং এক্সট্র্যাক্ট ভ্যারিয়েবলস পলিসি ব্যবহার করে এমন একটি সম্পূর্ণ নমুনা এপিআই প্রক্সির জন্য পলিসি কম্পোজিশন ব্যবহার দেখুন।

কাস্টম ত্রুটি পরিচালনা

উপাদান রেফারেন্স

নিম্নলিখিত উপাদান এবং বৈশিষ্ট্যগুলি আপনি এই পলিসিতে কনফিগার করতে পারেন:

<ServiceCallout async="false" continueOnError="false" enabled="true" name="Service-Callout-1">
    <DisplayName>Custom label used in UI</DisplayName>
    <Request clearPayload="true" variable="myRequest">
        <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
        <Remove>
            <ReasonPhrase/>
            <StatusCode/>
            <Path/>
            <Version/>
            <Verb/>
         </Remove>
         <Copy>
            <ReasonPhrase/>
            <StatusCode/>
            <Path/>
            <Version/>
            <Verb/>
        </Copy>
        <Add>
            <Headers/>
            <QueryParams/>
            <FormParams/>
        </Add>
        <Set>
            <Headers/>
            <QueryParams/>
            <FormParams/>
            <Payload/>
            <ReasonPhrase/>
            <StatusCode/>
            <Path/>
            <Version/>
            <Verb/>
        </Set>
    </Request>
    <Response>calloutResponse</Response>
    <Timeout>30000</Timeout>
    <HTTPTargetConnection>
        <URL>http://example.com</URL>
        <LoadBalancer/>
        <SSLInfo/>
        <Properties/>
    </HTTPTargetConnection>
    <LocalTargetConnection>
        <APIProxy/>
        <ProxyEndpoint/>
        <Path/>
    </LocalTargetConnection>
</ServiceCallout>

<সার্ভিসকলআউট> অ্যাট্রিবিউট

<ServiceCallout async="false" continueOnError="false" enabled="true" name="Service-Callout-1">

নিম্নলিখিত সারণী সমস্ত নীতির মূল উপাদানগুলির জন্য সাধারণ বৈশিষ্ট্যগুলি বর্ণনা করে:

<DisplayName> উপাদান

ম্যানেজমেন্ট UI প্রক্সি এডিটরে নীতিটিকে একটি ভিন্ন, প্রাকৃতিক-ভাষা নামের সাথে লেবেল করতে name বৈশিষ্ট্য ছাড়াও ব্যবহার করুন।

<DisplayName>Policy Display Name</DisplayName>

<অনুরোধ> উপাদান

এপিআই প্রক্সি থেকে অন্য সার্ভিসে পাঠানো অনুরোধ বার্তা ধারণকারী ভেরিয়েবলটি নির্দিষ্ট করে। ভেরিয়েবলটি ফ্লো-এর পূর্ববর্তী কোনো পলিসি দ্বারা তৈরি করা যেতে পারে, অথবা আপনি এটি সার্ভিস কলআউট পলিসিতে ইনলাইনভাবে তৈরি করতে পারেন।

<Request clearPayload="true" variable="myRequest">
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <Remove>
        <ReasonPhrase/>
        <StatusCode/>
        <Path/>
        <Version/>
        <Verb/>
    </Remove>
    <Copy>
        <ReasonPhrase/>
        <StatusCode/>
        <Path/>
        <Version/>
        <Verb/>
    </Copy>
    <Add>
        <Headers/>
        <QueryParams/>
        <FormParams/>
    </Add>
    <Set>
        <Headers/>
        <QueryParams/>
        <FormParams/>
        <Payload/>
        <ReasonPhrase/>
        <StatusCode/>
        <Path/>
        <Version/>
        <Verb/>
    </Set>
</Request>

<Remove> , <Copy> , <Add> , এবং <Set> ট্যাগগুলোর সিনট্যাক্স 'Assign Message' পলিসির সিনট্যাক্সের মতোই।

অনুরোধ বার্তাটি সমাধান করা না গেলে অথবা এর ধরনটি অবৈধ হলে পলিসিটি একটি ত্রুটি প্রদর্শন করে।

সবচেয়ে সহজ উদাহরণে, আপনি এমন একটি ভেরিয়েবল পাস করেন যাতে অনুরোধের বার্তাটি থাকে এবং যা এপিআই প্রক্সির ফ্লো-এর শুরুতে পূরণ করা হয়েছিল:

<Request clearPayload="true" variable="myRequest"/>

অথবা আপনি সার্ভিস কলআউট পলিসির মধ্যেই এক্সটার্নাল সার্ভিসে পাঠানো রিকোয়েস্ট মেসেজটি পূরণ করতে পারেন:

<Request>
  <Set>
    <Headers>
      <Header name="Accept">application/json</Header>
    </Headers>
    <Verb>POST</Verb>
    <Payload contentType="application/json">{"message":"my test message"}</Payload>
  </Set>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</Request>

বৈশিষ্ট্য

<Request>/<IgnoreUnresolvedVariables> এলিমেন্ট

'true'- তে সেট করা হলে, পলিসিটি রিকোয়েস্টের যেকোনো অমীমাংসিত ভ্যারিয়েবল ত্রুটি উপেক্ষা করে।

<Request clearPayload="true" variable="myRequest">
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</Request>

<প্রতিক্রিয়া> উপাদান

যখন পরবর্তী প্রক্রিয়াকরণের জন্য এপিআই প্রক্সি লজিকের রিমোট কলের প্রতিক্রিয়ার প্রয়োজন হয়, তখন এই এলিমেন্টটি অন্তর্ভুক্ত করুন।

যখন এই উপাদানটি উপস্থিত থাকে, তখন এটি সেই ভেরিয়েবলের নাম নির্দিষ্ট করে যা বাহ্যিক পরিষেবা থেকে প্রাপ্ত প্রতিক্রিয়া বার্তা ধারণ করবে। টার্গেট থেকে প্রাপ্ত প্রতিক্রিয়াটি শুধুমাত্র তখনই ভেরিয়েবলে বরাদ্দ করা হয়, যখন পলিসি দ্বারা সম্পূর্ণ প্রতিক্রিয়াটি সফলভাবে পড়া হয়। যদি কোনো কারণে রিমোট কলটি ব্যর্থ হয়, তাহলে পলিসি একটি ত্রুটি ফেরত দেয়।

এই এলিমেন্টটি বাদ দেওয়া হলে, এপিআই প্রক্সি কোনো প্রতিক্রিয়ার জন্য অপেক্ষা করে না; এপিআই প্রক্সি ফ্লো এক্সিকিউশন পরবর্তী যেকোনো ফ্লো স্টেপ নিয়ে চলতে থাকে। এছাড়াও, যা স্পষ্ট তা হলো, Response এলিমেন্ট না থাকলে টার্গেট থেকে আসা প্রতিক্রিয়া পরবর্তী স্টেপগুলোর প্রক্রিয়াকরণের জন্য উপলব্ধ থাকে না, এবং প্রক্সি ফ্লো-এর পক্ষে রিমোট কলের কোনো ব্যর্থতা শনাক্ত করার কোনো উপায় থাকে না। ServiceCallout ব্যবহার করার সময় Response এলিমেন্টটি বাদ দেওয়ার একটি সাধারণ ব্যবহার হলো: কোনো বাহ্যিক সিস্টেমে মেসেজ লগ করা।

 <Response>calloutResponse</Response>

<টাইমআউট> উপাদান

টার্গেট থেকে প্রতিক্রিয়ার জন্য সার্ভিস কলআউট পলিসি যে সময়টুকু (মিলিসেকেন্ডে) অপেক্ষা করবে। আপনি রানটাইমে এই মানটি ডায়নামিকভাবে সেট করতে পারবেন না। যদি সার্ভিস কলআউট টাইমআউটে পৌঁছায়, তাহলে একটি HTTP 500 রিটার্ন করা হয়, পলিসিটি ব্যর্থ হয় এবং এপিআই প্রক্সি একটি এরর স্টেটে চলে যায়, যেমনটি 'হ্যান্ডলিং ফল্টস' অংশে বর্ণনা করা হয়েছে।

<Timeout>30000</Timeout>

<HTTPTargetConnection> উপাদান

URL, TLS/SSL, এবং HTTP প্রোপার্টির মতো ট্রান্সপোর্টের বিবরণ প্রদান করে। <TargetEndpoint> কনফিগারেশন রেফারেন্সটি দেখুন।

<HTTPTargetConnection>
    <URL>http://example.com</URL>
    <LoadBalancer/>
    <SSLInfo/>
    <Properties/>
</HTTPTargetConnection>

<HTTPTargetConnection>/<URL> উপাদান

যে সার্ভিসটি কল করা হচ্ছে তার URL:

<HTTPTargetConnection>
    <URL>http://example.com</URL>
</HTTPTargetConnection>

আপনি একটি ভেরিয়েবলের সাহায্যে URL-এর অংশবিশেষ ডায়নামিকভাবে সরবরাহ করতে পারেন। তবে, URL-এর প্রোটোকল অংশ, যেমন নিচের http:// , কোনো ভেরিয়েবল দ্বারা নির্দিষ্ট করা যায় না। পরবর্তী উদাহরণে, আপনি একটি কোয়েরি প্যারামিটারের মান নির্দিষ্ট করতে একটি ভেরিয়েবল ব্যবহার করবেন:

<URL>http://example.com/forecastrss?w=${request.header.woeid}</URL>

অথবা, URL পাথের একটি অংশ ভেরিয়েবল দিয়ে সেট করুন:

<URL>http://example.com/{request.resourcePath}?w=${request.header.woeid}</URL>

যদি আপনি URL-এর ডোমেইন এবং পোর্ট নির্দিষ্ট করার জন্য একটি ভেরিয়েবল ব্যবহার করতে চান, তাহলে শুধুমাত্র ডোমেইন এবং পোর্টের জন্য একটি ভেরিয়েবল এবং URL-এর অন্য যেকোনো অংশের জন্য দ্বিতীয় একটি ভেরিয়েবল ব্যবহার করুন:

<URL>http://{request.dom_port}/{request.resourcePath}</URL>

<HTTPTargetConnection>/<SSLInfo> উপাদান

ব্যাকএন্ড সার্ভিসের জন্য TLS/SSL কনফিগারেশন। TLS/SSL কনফিগারেশন সম্পর্কে সাহায্যের জন্য, API প্রক্সি কনফিগারেশন রেফারেন্স -এ "Configuring TLS from Edge to the backend (Cloud and Private Cloud)" এবং "TLS/SSL TargetEndpoint Configuration" দেখুন।