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

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

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

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

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

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

सैंपल

यहां Cloud Logging एक्सटेंशन के साथ इस्तेमाल की जाने वाली नीति का एक उदाहरण दिया गया है:

<?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 Logging एक्सटेंशन का इस्तेमाल करने के बारे में पूरा ट्यूटोरियल देखने के लिए, ट्यूटोरियल: एक्सटेंशन का इस्तेमाल करना पर जाएं.

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

ExtensionCallout नीति के बारे में जानकारी

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

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

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

PostClientFlow में ExtensionCallout नीति का इस्तेमाल करना

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

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

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

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

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

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

<?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>

<ConnectorCallout> एट्रिब्यूट

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

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

&lt;DisplayName&gt; एलिमेंट

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

<DisplayName>Policy Display Name</DisplayName>

<Action> एलिमेंट

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

<Action>action-exposed-by-extension</Action>

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

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

<Connector> एलिमेंट

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

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

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

<Input> एलिमेंट

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

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

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

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

<Input> एलिमेंट की वैल्यू, सही फ़ॉर्मैट वाला JSON है. इसकी प्रॉपर्टी, एक्सटेंशन ऐक्शन को शुरू करने के लिए वैल्यू तय करती हैं. उदाहरण के लिए, Google Cloud Logging Extension एक्सटेंशन के 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> एलिमेंट

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

<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 -->

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

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

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

<Output> एट्रिब्यूट

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

कोई नहीं.

गड़बड़ी के कोड

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

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

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

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

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

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