एक्सटेंशन की कॉल आउट नीति

Apigee Edge दस्तावेज़ देखा जा रहा है.
Apigee X दस्तावेज़ पर जाएं. जानकारी

एपीआई प्रॉक्सी में किसी एक्सटेंशन को शामिल करने के लिए, एक्सटेंशन कॉलआउट की नीति का इस्तेमाल करें.

एक्सटेंशन, Apigee Edge के बाहर मौजूद खास संसाधन को ऐक्सेस करने की सुविधा देता है. संसाधन, Google Cloud Platform की सेवाएं हो सकती हैं. जैसे, Cloud Storage या Cloud Speech-to-Text. हालांकि, वह संसाधन कोई ऐसा बाहरी संसाधन हो सकता है जिसे एचटीटीपी या एचटीटीपीएस से ऐक्सेस किया जा सकता हो.

एक्सटेंशन की खास जानकारी के लिए, एक्सटेंशन क्या होते हैं? देखें शुरुआती ट्यूटोरियल के लिए, ट्यूटोरियल: एक्सटेंशन जोड़ना और उसका इस्तेमाल करना देखें.

एक्सटेंशन कॉलआउट नीति से किसी एक्सटेंशन को ऐक्सेस करने से पहले, आपको उस एक्सटेंशन पैकेज से एक्सटेंशन जोड़ना, कॉन्फ़िगर करना, और डिप्लॉय करना होगा जो आपके Apigee Edge संगठन में पहले से इंस्टॉल है.

सैंपल

नीचे क्लाउड लॉगिंग एक्सटेंशन के साथ इस्तेमाल की नीति का एक उदाहरण दिया गया है:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ConnectorCallout async="false" continueOnError="false" enabled="true" name="Logging-Extension">
        <DisplayName>Logging Extension</DisplayName>
        <Connector>cloud-extension-sample</Connector>
        <Action>log</Action>
        <Input>{
                "logName" : "example-log",
                "metadata" : "test-metadata",
                "message" : "This is a test"
        }</Input>
    <Output>cloud-extension-example-log</Output>
</ConnectorCallout>

क्लाउड लॉगिंग एक्सटेंशन का इस्तेमाल करके पूरा ट्यूटोरियल देखने के लिए, ट्यूटोरियल: एक्सटेंशन का इस्तेमाल करना देखें.

सभी उपलब्ध एक्सटेंशन के उदाहरणों के लिए, एक्सटेंशन रेफ़रंस की खास जानकारी देखें.

एक्सटेंशन कॉलआउट की नीति के बारे में जानकारी

जब आपको एपीआई प्रॉक्सी में से बाहरी संसाधन को ऐक्सेस करने के लिए, कॉन्फ़िगर किए गए एक्सटेंशन का इस्तेमाल करना हो, तो एक्सटेंशन कॉलआउट की नीति का इस्तेमाल करें.

इस नीति का इस्तेमाल करने से पहले, आपको इनकी ज़रूरत होगी:

  • इस नीति से, आपको जिस बाहरी संसाधन को ऐक्सेस करना है उसके बारे में कुछ जानकारी. यह जानकारी खास तौर पर संसाधन के हिसाब से होगी. उदाहरण के लिए, अगर नीति आपके Cloud Firestore डेटाबेस को ऐक्सेस करेगी, तो आपको उस कलेक्शन और दस्तावेज़ का नाम पता होना चाहिए जिसे आपको बनाना या ऐक्सेस करना है. आम तौर पर, इस नीति के अनुरोध और रिस्पॉन्स हैंडलिंग को कॉन्फ़िगर करने के लिए, आपको संसाधन की खास जानकारी का इस्तेमाल करना होगा.
  • उस एनवायरमेंट में जोड़ा गया, कॉन्फ़िगर किया गया, और डिप्लॉय किया गया एक्सटेंशन जहां आपके एपीआई प्रॉक्सी को डिप्लॉय किया जाएगा. दूसरे शब्दों में, अगर किसी खास Google Cloud सेवा को ऐक्सेस करने के लिए इस नीति का इस्तेमाल करना है, तो आपके एनवायरमेंट में उस सेवा के लिए डिप्लॉय किया गया एक्सटेंशन मौजूद होना चाहिए. आम तौर पर, कॉन्फ़िगरेशन की जानकारी में संसाधन के ऐक्सेस को सीमित करने के लिए ज़रूरी जानकारी शामिल होती है, जैसे कि प्रोजेक्ट आईडी या खाते का नाम.

PostClientFlow में एक्सटेंशन कॉलआउट की नीति का इस्तेमाल करना

एपीआई प्रॉक्सी के PostClientFlow से, एक्सटेंशन कॉलआउट की नीति शुरू की जा सकती है. PostClientFlow, अनुरोध करने वाले क्लाइंट को जवाब भेजे जाने के बाद काम करता है, जो पक्का करता है कि लॉग करने के लिए सभी मेट्रिक उपलब्ध हैं. PostClientFlow का इस्तेमाल करने के बारे में जानकारी के लिए, एपीआई प्रॉक्सी कॉन्फ़िगरेशन रेफ़रंस देखें.

अगर आपको PostClientFlow से Google Cloud लॉगिंग एक्सटेंशन को कॉल करने के लिए एक्सटेंशन कॉलआउट नीति का इस्तेमाल करना है, तो पक्का करें कि आपके संगठन में features.allowExtensionsInPostClientFlow फ़्लैग true पर सेट हो.

  • अगर आप Public Cloud के ग्राहक के लिए Apigee Edge हैं, तो features.allowExtensionsInPostClientFlow फ़्लैग, डिफ़ॉल्ट रूप से true पर सेट होता है.

  • अगर आप Private Cloud के ग्राहक के लिए Apigee Edge हैं, तो संगठन की प्रॉपर्टी अपडेट करें एपीआई का इस्तेमाल करके, features.allowExtensionsInPostClientFlow फ़्लैग को true पर सेट करें.

PostClientFlow से MessageLogging नीति को कॉल करने के लिए सभी पाबंदियां, एक्सटेंशनकॉलआउट नीति पर भी लागू होती हैं. ज़्यादा जानकारी के लिए, इस्तेमाल से जुड़ी जानकारी देखें.

एलिमेंट का रेफ़रंस

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ConnectorCallout async="false" continueOnError="false" enabled="true" name="Extension-Callout-1">
    <DisplayName/>
    <Connector/>
    <Action/>
    <Input/>
    <Output/>
</ConnectorCallout>

<Connector callout> एट्रिब्यूट

<ConnectorCallout name="Extension-Callout-1" continueOnError="false" enabled="true" async="false">

इस टेबल में उन एट्रिब्यूट के बारे में बताया गया है जो नीति के सभी पैरंट एलिमेंट के लिए एक जैसे होते हैं:

एट्रिब्यूट ब्यौरा डिफ़ॉल्ट मौजूदगी
name

नीति का अंदरूनी नाम. name एट्रिब्यूट की वैल्यू में अक्षर, संख्याएं, स्पेस, हाइफ़न, अंडरस्कोर, और पीरियड शामिल किए जा सकते हैं. इस वैल्यू में 255 से ज़्यादा वर्ण नहीं हो सकते.

इसके अलावा, मैनेजमेंट यूज़र इंटरफ़ेस (यूआई) प्रॉक्सी एडिटर में नीति को आम भाषा में अलग नाम से लेबल करने के लिए, <DisplayName> एलिमेंट का इस्तेमाल करें.

 लागू नहीं ज़रूरी है
continueOnError

इस नीति को false पर सेट करें, ताकि नीति के काम न करने पर गड़बड़ी का मैसेज दिखे. ज़्यादातर नीतियों में, ऐसा आम तौर पर किया जाता है.

किसी नीति के काम न करने पर भी फ़्लो एक्ज़ीक्यूट करने की प्रोसेस को जारी रखने के लिए, true पर सेट करें.

 false ज़रूरी नहीं
enabled

नीति लागू करने के लिए, true पर सेट करें.

नीति को बंद करने के लिए, false पर सेट करें. अगर यह नीति किसी फ़्लो से जुड़ी हुई है, तब भी उसे लागू नहीं किया जाएगा.

 सही ज़रूरी नहीं
async

यह एट्रिब्यूट अब काम नहीं करता.

 false बहिष्कृत

<DisplayName> एलिमेंट

मैनेजमेंट यूज़र इंटरफ़ेस (यूआई) प्रॉक्सी एडिटर में, आम भाषा के अलग नाम से नीति को लेबल करने के लिए, name एट्रिब्यूट का इस्तेमाल करें.

<DisplayName>Policy Display Name</DisplayName>
डिफ़ॉल्ट

लागू नहीं

अगर इस एलिमेंट को छोड़ दिया जाता है, तो नीति के name एट्रिब्यूट की वैल्यू का इस्तेमाल किया जाता है.
मौजूदगी ज़रूरी नहीं
Type String

<कार्रवाई> एलिमेंट

एक्सटेंशन के ज़रिए बताई गई वह कार्रवाई जिसे नीति को शुरू करना चाहिए.

<Action>action-exposed-by-extension</Action>
डिफ़ॉल्ट कभी नहीं
मौजूदगी ज़रूरी है
Type String

हर एक्सटेंशन, कार्रवाइयों के अपने सेट की जानकारी देता है. इससे एक्सटेंशन के संसाधन के फ़ंक्शन का ऐक्सेस मिलता है. फ़ंक्शन के तर्कों की जानकारी देने के लिए, <Input> एलिमेंट के कॉन्टेंट का इस्तेमाल करके, किसी कार्रवाई को इस नीति के साथ कॉल किया जा सकता है. कार्रवाई का रिस्पॉन्स, <Output> एलिमेंट के साथ तय किए गए वैरिएबल में सेव किया जाता है.

एक्सटेंशन के फ़ंक्शन की सूची देखने के लिए, उस एक्सटेंशन का रेफ़रंस देखें जिसे आपने इस नीति का इस्तेमाल करके कॉल किया है.

<कनेक्टर> एलिमेंट

कॉन्फ़िगर किए गए एक्सटेंशन का नाम. यह एनवायरमेंट के स्कोप वाला नाम होता है. इसे एनवायरमेंट में डिप्लॉयमेंट के लिए कॉन्फ़िगर करते समय एक्सटेंशन को दिया गया था.

<Connector>name-of-configured-extension</Connector>

डिफ़ॉल्ट कभी नहीं
मौजूदगी ज़रूरी है
Type String

एक एक्सटेंशन में ऐसी कॉन्फ़िगरेशन वैल्यू होती हैं जो उसी एक्सटेंशन पैकेज के आधार पर, डिप्लॉय किए गए किसी दूसरे एक्सटेंशन से अलग हो सकती हैं. ये कॉन्फ़िगरेशन वैल्यू, एक ही पैकेज से कॉन्फ़िगर किए गए एक्सटेंशन के बीच रनटाइम फ़ंक्शन के बीच के अहम अंतर दिखा सकती हैं. इसलिए, यह पक्का कर लें कि शुरू करने के लिए सही एक्सटेंशन डाला गया हो.

<Input> एलिमेंट

वह JSON जिसमें अनुरोध का मुख्य हिस्सा शामिल है और जिसे एक्सटेंशन को भेजना है.

<Input><![CDATA[ JSON-containing-input-values ]]></Input>

डिफ़ॉल्ट कभी नहीं
मौजूदगी एक्सटेंशन के आधार पर, ज़रूरी नहीं या ज़रूरी नहीं.
Type String

यह मुख्य तौर पर, <Action> एलिमेंट के साथ तय की गई कार्रवाई का तर्क है. <Input> एलिमेंट की वैल्यू, एक्सटेंशन और उस कार्रवाई के आधार पर अलग-अलग होगी जिसे शुरू किया जा रहा है. हर कार्रवाई की प्रॉपर्टी के बारे में जानने के लिए, एक्सटेंशन पैकेज का दस्तावेज़ देखें.

ध्यान दें कि कई <Input> एलिमेंट वैल्यू, <![CDATA[]]> सेक्शन में शामिल किए बिना भी सही तरीके से काम करेंगी. हालांकि, JSON के नियम में उन वैल्यू की अनुमति दी गई है जो एक्सएमएल के तौर पर पार्स नहीं होंगी. रनटाइम पार्स की गड़बड़ियों से बचने के लिए, सबसे सही तरीका यह है कि JSON को CDATA सेक्शन के तौर पर बंद करें.

<Input> एलिमेंट की वैल्यू अच्छी तरह से बनाया गया JSON है, जिसकी प्रॉपर्टी ऐसी वैल्यू तय करती हैं जिन्हें एक्सटेंशन ऐक्शन को शुरू करने के लिए भेजना है. उदाहरण के लिए, Google Cloud Logging एक्सटेंशन एक्सटेंशन की log कार्रवाई, लॉग में बताई जाने वाली वैल्यू तय करती है (logName), एंट्री (metadata), और लॉग मैसेज (data) के साथ शामिल किया जाने वाला मेटाडेटा. यहां एक उदाहरण दिया गया है:

<Input><![CDATA[{
    "logName" : "example-log",
    "metadata" : {
        "resource": {
            "type": "global",
            "labels": {
                "project_id": "my-test"
            }
        }
    },
    "message" : "This is a test"
}]]></Input>

<Input> JSON में फ़्लो वैरिएबल का इस्तेमाल करना

<Input> के कॉन्टेंट को मैसेज टेंप्लेट के तौर पर माना जाता है. इसका मतलब है कि कर्ली ब्रैकेट में रैप किए गए वैरिएबल के नाम को, रनटाइम के दौरान रेफ़र किए गए वैरिएबल की वैल्यू से बदल दिया जाएगा.

उदाहरण के लिए, एपीआई प्रॉक्सी को कॉल करने वाले क्लाइंट का आईपी पता पाने के लिए, client.ip फ़्लो वैरिएबल का इस्तेमाल करने के लिए, पिछले <Input> ब्लॉक को फिर से लिखा जा सकता है:

<Input><![CDATA[{
    "logName" : "example-log",
    "metadata" : {
        "resource": {
            "type": "global",
            "labels": {
                "project_id": "my-test"
            }
        }
    },
    "message" : "{client.ip}"
}]]></Input>

अगर आपको रनटाइम के दौरान, JSON में किसी प्रॉपर्टी की वैल्यू को कोटेशन मार्क के अंदर रखना है, तो अपने JSON कोड में कोटेशन मार्क का इस्तेमाल करना न भूलें. यह तब भी लागू होता है, जब किसी फ़्लो वैरिएबल को JSON प्रॉपर्टी की वैल्यू के तौर पर तय किया जाता है, ताकि रनटाइम के दौरान इस वैरिएबल को रिज़ॉल्व किया जा सके.

नीचे दिए गए <Input> उदाहरण में दो फ़्लो वैरिएबल रेफ़रंस शामिल हैं:

<Input><![CDATA[{
  "logName" : "example-log",
  "metadata" : {my.log.entry.metadata},
  "message" : "{client.ip}"
}]]></Input>

रनटाइम के दौरान, JSON प्रॉपर्टी की वैल्यू इस तरह से चलेंगी:

  • logName प्रॉपर्टी का मान -- स्ट्रिंग की लिटरल वैल्यू example-log.
  • metadata प्रॉपर्टी की वैल्यू -- my.log.entry.metadata फ़्लो वैरिएबल की वैल्यू, कोटेशन मार्क को बंद किए बिना. अगर वैरिएबल की वैल्यू ही किसी ऑब्जेक्ट को दिखाने वाला JSON है, तो यह काम का हो सकता है.
  • message प्रॉपर्टी की वैल्यू -- client.ip फ़्लो वैरिएबल की वैल्यू, जिसमें कोटेशन मार्क शामिल हैं.

<आउटपुट> एलिमेंट

उस वैरिएबल का नाम जो एक्सटेंशन ऐक्शन के रिस्पॉन्स को स्टोर करता है.

<Output>variable-name</Output> <!-- The JSON object inside the variable is parsed -->

या

<Output parsed="false">variable-name</Output>  <!-- The JSON object inside the variable is raw, unparsed -->

डिफ़ॉल्ट कभी नहीं
मौजूदगी एक्सटेंशन के आधार पर, ज़रूरी नहीं या ज़रूरी नहीं.
Type parsed एट्रिब्यूट की सेटिंग के आधार पर, पार्स किया गया ऑब्जेक्ट या स्ट्रिंग.

रिस्पॉन्स मिलने पर, रिस्पॉन्स वैल्यू यहां बताए गए वैरिएबल में डाल दी जाती है. यहां से, किसी अन्य एपीआई प्रॉक्सी कोड से इस वैरिएबल को ऐक्सेस किया जा सकता है.

एक्सटेंशन रिस्पॉन्स ऑब्जेक्ट, JSON फ़ॉर्मैट में होते हैं. नीति, JSON को कैसे हैंडल करती है, इसके दो विकल्प हैं:

  • पार्स किया गया (डिफ़ॉल्ट): नीति, JSON ऑब्जेक्ट को पार्स करती है और JSON डेटा की मदद से वैरिएबल अपने-आप जनरेट करती है. उदाहरण के लिए, अगर JSON में "messageId" : 12345; है और अपने आउटपुट वैरिएबल extensionOutput को नाम देते हैं, तो आपके पास उस मैसेज आईडी को अन्य नीतियों में ऐक्सेस करने का विकल्प है. इसके लिए, {extensionOutput.messageId} वैरिएबल का इस्तेमाल करें.
  • पार्स नहीं किया गया: आउटपुट वैरिएबल में, एक्सटेंशन का रॉ, पार्स नहीं किया गया JSON रिस्पॉन्स होता है. अगर आप चाहें, तो JavaScript की नीति का इस्तेमाल करके, रिस्पॉन्स वैल्यू को अब भी एक अलग चरण में पार्स किया जा सकता है.

<आउटपुट> एट्रिब्यूट

एट्रिब्यूट ब्यौरा डिफ़ॉल्ट मौजूदगी
पार्स किया गया एक्सटेंशन से मिले JSON ऑब्जेक्ट को पार्स करता है. इससे JSON ऑब्जेक्ट के डेटा को दूसरी नीतियों के वैरिएबल के तौर पर ऐक्सेस किया जा सकता है. सही ज़रूरी नहीं

फ़्लो वैरिएबल

कोई नहीं.

गड़बड़ी कोड

Apigee Edge की नीतियों से मिली गड़बड़ियां, एक जैसे फ़ॉर्मैट का इस्तेमाल करती हैं. इसके बारे में नीति से जुड़ी गड़बड़ी के रेफ़रंस में बताया गया है.

इस सेक्शन में उन गड़बड़ी के मैसेज और फ़्लो वैरिएबल के बारे में बताया गया है जो किसी नीति के ट्रिगर होने पर सेट किए जाते हैं. यह जानकारी जानना ज़रूरी है कि क्या आप प्रॉक्सी के लिए गड़बड़ी के नियम बना रहे हैं. ज़्यादा जानने के लिए, नीति से जुड़ी गड़बड़ियों के बारे में आपको क्या पता होना चाहिए और गड़बड़ियों को ठीक करना देखें.

रनटाइम से जुड़ी गड़बड़ियां

नीति के लागू होने पर ये गड़बड़ियां हो सकती हैं.

गड़बड़ी का नाम एचटीटीपी कोड स्थिति वजह
एक्ज़ीक्यूशन नहीं हो सका 500 एक्सटेंशन गड़बड़ी के साथ जवाब देता है.

डिप्लॉयमेंट से जुड़ी गड़बड़ियां

ये गड़बड़ियां तब हो सकती हैं, जब इस नीति वाला प्रॉक्सी डिप्लॉय किया जाता है.

गड़बड़ी का नाम कब होता है समाधान
InvalidConnectorInstance <Connector> एलिमेंट खाली है.
ConnectorInstanceDoesNotExists <Connector> एलिमेंट में बताया गया एक्सटेंशन, एनवायरमेंट में मौजूद नहीं है.
InvalidAction एक्सटेंशन कॉलआउट नीति में <Action> एलिमेंट मौजूद नहीं है या उसकी वैल्यू खाली है.
AllowExtensionsInPostClientFlow पोस्ट क्लाइंट फ़्लो में ExtensionCallout नीति का इस्तेमाल नहीं किया जा सकता है.