خط مشی ExtensionCallout

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

از سیاست ExtensionCallout برای گنجاندن یک افزونه در یک پروکسی API استفاده کنید.

یک افزونه دسترسی به یک منبع خاص خارج از Apigee Edge را فراهم می‌کند. این منبع می‌تواند سرویس‌های پلتفرم ابری گوگل مانند Cloud Storage یا Cloud Speech-to-Text باشد. اما این منبع می‌تواند هر منبع خارجی قابل دسترسی از طریق HTTP یا HTTPS باشد.

برای مرور کلی افزونه‌ها، به «افزونه‌ها چیستند؟» مراجعه کنید. برای آموزش مقدماتی، به «آموزش: افزودن و استفاده از افزونه» مراجعه کنید.

قبل از دسترسی به یک افزونه از طریق خط‌مشی 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

وقتی می‌خواهید از یک افزونه پیکربندی‌شده برای دسترسی به یک منبع خارجی از درون یک پروکسی API استفاده کنید، از سیاست ExtensionCallout استفاده کنید.

قبل از استفاده از این خط‌مشی، به موارد زیر نیاز دارید:

• چند جزئیات در مورد منبع خارجی که می‌خواهید از طریق این سیاست به آن دسترسی داشته باشید. این جزئیات مختص منبع خواهد بود. به عنوان مثال، اگر این سیاست به پایگاه داده Cloud Firestore شما دسترسی داشته باشد، باید نام مجموعه و سندی را که می‌خواهید ایجاد کنید یا به آن دسترسی داشته باشید، بدانید. معمولاً در پیکربندی مدیریت درخواست و پاسخ این سیاست، از اطلاعات مختص منبع استفاده خواهید کرد.
• افزونه‌ای اضافه، پیکربندی و در محیطی که پروکسی API شما در آن مستقر خواهد شد، مستقر شده است . به عبارت دیگر، اگر قصد دارید از این خط‌مشی برای دسترسی به یک سرویس خاص Google Cloud استفاده کنید، باید یک افزونه مستقر برای آن سرویس در محیط شما وجود داشته باشد. جزئیات پیکربندی معمولاً شامل اطلاعات لازم برای محدود کردن دسترسی به منبع، مانند شناسه پروژه یا نام حساب کاربری، است.

استفاده از سیاست ExtensionCallout در PostClientFlow

شما می‌توانید سیاست ExtensionCallout را از PostClientFlow یک پروکسی API فراخوانی کنید. PostClientFlow پس از ارسال پاسخ به کلاینت درخواست‌کننده اجرا می‌شود، که تضمین می‌کند همه معیارها برای ثبت در دسترس هستند. برای جزئیات بیشتر در مورد استفاده از PostClientFlow، به مرجع پیکربندی پروکسی API مراجعه کنید.

اگر می‌خواهید از خط‌مشی ExtensionCallout برای فراخوانی افزونه Google Cloud Logging از یک PostClientFlow استفاده کنید، مطمئن شوید که پرچم features.allowExtensionsInPostClientFlow در سازمان شما روی true تنظیم شده باشد.

• اگر شما از مشتریان Apigee Edge for Public Cloud هستید، پرچم features.allowExtensionsInPostClientFlow به طور پیش‌فرض روی true تنظیم شده است.

• اگر شما مشتری Apigee Edge برای Private Cloud هستید، از API مربوط به Update organization properties برای تنظیم flag مربوط به features.allowExtensionsInPostClientFlow روی true استفاده کنید.

تمام محدودیت‌های مربوط به فراخوانی خط‌مشی MessageLogging از PostClientFlow، در مورد خط‌مشی 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">

جدول زیر ویژگی هایی را توصیف می کند که برای همه عناصر اصلی خط مشی مشترک هستند:

عنصر <DisplayName>

علاوه بر ویژگی name برای برچسب‌گذاری خط‌مشی در ویرایشگر پروکسی رابط کاربری مدیریت با نامی متفاوت و به زبان طبیعی، از آن استفاده کنید.

<DisplayName>Policy Display Name</DisplayName>

عنصر <اکشن>

اقدام مربوط به افزونه که خط‌مشی باید آن را فراخوانی کند.

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

هر افزونه مجموعه اقدامات خاص خود را ارائه می‌دهد که دسترسی به عملکرد منبعی را که افزونه نشان می‌دهد، فراهم می‌کند. می‌توانید یک اقدام را به عنوان تابعی در نظر بگیرید که با این سیاست فراخوانی می‌کنید و از محتویات عنصر <Input> برای مشخص کردن آرگومان‌های تابع استفاده می‌کنید. پاسخ اقدام در متغیری که با عنصر <Output> مشخص می‌کنید، ذخیره می‌شود.

برای مشاهده فهرستی از عملکردهای افزونه، به مرجع افزونه‌ای که از این خط‌مشی فراخوانی می‌کنید، مراجعه کنید.

عنصر <اتصال دهنده>

نام افزونه‌ی پیکربندی‌شده برای استفاده. این نامِ در محدوده‌ی محیط است که هنگام پیکربندی افزونه برای استقرار در یک محیط، به آن داده شده است.

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

یک افزونه دارای مقادیر پیکربندی است که ممکن است با افزونه‌ی دیگری که بر اساس همان بسته‌ی افزونه پیاده‌سازی شده است، متفاوت باشد. این مقادیر پیکربندی می‌توانند تفاوت‌های مهمی را در عملکرد زمان اجرا بین افزونه‌های پیکربندی شده از همان بسته نشان دهند، بنابراین حتماً افزونه‌ی صحیح را برای فراخوانی مشخص کنید.

عنصر <ورودی>

JSON حاوی بدنه درخواست برای ارسال به افزونه.

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

این اساساً یک آرگومان برای عملی است که شما با عنصر <Action> مشخص می‌کنید. مقدار عنصر <Input> بسته به افزونه و عملی که فراخوانی می‌کنید متفاوت خواهد بود. برای جزئیات بیشتر در مورد ویژگی‌های هر عمل، به مستندات بسته افزونه مراجعه کنید.

توجه داشته باشید که اگرچه بسیاری از مقادیر عنصر <Input> بدون محصور شدن به عنوان بخش <![CDATA[]]> به درستی کار می‌کنند، اما قوانین JSON اجازه می‌دهند مقادیری که به عنوان XML تجزیه نمی‌شوند، نیز به درستی نمایش داده شوند. به عنوان یک روش بهتر، JSON را به عنوان بخش CDATA محصور کنید تا از خطاهای تجزیه در زمان اجرا جلوگیری شود.

مقدار عنصر <Input> از نوع JSON خوش‌فرم است که ویژگی‌های آن مقادیری را برای ارسال به اکشن افزونه جهت فراخوانی مشخص می‌کنند. برای مثال، اکشن log افزونه Google Cloud Logging Extension مقادیری را دریافت می‌کند که مشخص‌کننده لاگی است که باید در آن نوشته شود ( 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> به عنوان یک الگوی پیام در نظر گرفته می‌شود. این بدان معناست که نام متغیری که در داخل آکولاد قرار گرفته است، در زمان اجرا با مقدار متغیر ارجاع شده جایگزین می‌شود.

برای مثال، می‌توانید بلوک <Input> قبلی را طوری بازنویسی کنید که از متغیر جریان client.ip برای دریافت آدرس IP کلاینتی که پروکسی API را فراخوانی می‌کند، استفاده کند:

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

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

اشیاء پاسخ افزونه در قالب JSON هستند. دو گزینه برای نحوه مدیریت JSON توسط سیاست وجود دارد:

• تجزیه‌شده (پیش‌فرض): این سیاست شیء JSON را تجزیه می‌کند و به‌طور خودکار متغیرهایی با داده‌های JSON تولید می‌کند. برای مثال، اگر JSON شامل "messageId" : 12345; باشد و شما متغیر خروجی خود را extensionOutput نامگذاری کنید، می‌توانید با استفاده از متغیر {extensionOutput.messageId} به آن شناسه پیام در سایر سیاست‌ها دسترسی پیدا کنید.
• تجزیه نشده: متغیر خروجی شامل پاسخ خام و تجزیه نشده JSON از افزونه است. (اگر می‌خواستید، می‌توانید با استفاده از سیاست جاوا اسکریپت ، مقدار پاسخ را در یک مرحله جداگانه تجزیه کنید.)

ویژگی‌های <خروجی>

متغیرهای جریان

هیچ کدام.

کدهای خطا

خطاهایی که از سیاست‌های Apigee Edge بازگردانده می‌شوند، از یک قالب ثابت پیروی می‌کنند، همانطور که در مرجع خطای سیاست توضیح داده شده است.

این بخش پیام‌های خطا و متغیرهای جریانی را توضیح می‌دهد که وقتی این خط‌مشی خطا را راه‌اندازی می‌کند، تنظیم می‌شود. این اطلاعات مهم است که بدانید آیا در حال ایجاد قوانین خطا برای یک پروکسی هستید. برای کسب اطلاعات بیشتر، آنچه را که باید در مورد خطاهای خط مشی و مدیریت خطاها بدانید را ببینید.

خطاهای زمان اجرا

این خطاها ممکن است هنگام اجرای سیاست رخ دهند.

خطاهای استقرار

این خطاها ممکن است زمانی رخ دهند که یک پروکسی حاوی این خط مشی را مستقر می کنید.