خط مشی ExtensionCallout

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

از خط مشی ExtensionCallout برای ترکیب یک برنامه افزودنی در یک پراکسی API استفاده کنید.

یک برنامه افزودنی دسترسی به یک منبع خاص خارج از Apigee Edge را فراهم می کند. منبع می تواند خدمات پلتفرم Google Cloud مانند فضای ذخیره سازی ابری یا تبدیل گفتار به متن ابری باشد. اما منبع می تواند هر منبع خارجی قابل دسترسی از طریق 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 برای Public Cloud هستید، پرچم features.allowExtensionsInPostClientFlow به طور پیش‌فرض روی true تنظیم شده است.

• اگر مشتری Apigee Edge برای Private Cloud هستید، از API ویژگی های سازمان به روز رسانی برای تنظیم پرچم 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>action-exposed-by-extension</Action>

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

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

عنصر <Connector>

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

<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 مقادیری را می‌گیرد که گزارشی را برای نوشتن در ( 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>

نام متغیری که پاسخ عملکرد برنامه افزودنی را ذخیره می کند.

<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} به شناسه پیام در سیاست های دیگر دسترسی داشته باشید.
• Unparsed: متغیر خروجی حاوی پاسخ JSON خام و تجزیه نشده از برنامه افزودنی است. (اگر می خواهید، همچنان می توانید مقدار پاسخ را در یک مرحله جداگانه با استفاده از خط مشی جاوا اسکریپت تجزیه کنید.)

<Output> ویژگی ها

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

هیچ کدام.

کدهای خطا

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

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

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

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

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

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