خط‌مشی «افزونه‌تماس‌شرح‌دار»

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

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

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

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

قبل‌از دسترسی به افزونه از خط‌مشی «افزونه‌تماس»، باید افزونه را از بسته افزونه‌ای که قبلاً در سازمان 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 Firestore شما دسترسی خواهد داشت، باید نام مجموعه و سندی را که می‌خواهید ایجاد کنید یا به آن دسترسی داشته باشید بدانید. معمولاً از اطلاعات ویژه منبع در پیکربندی درخواست و مدیریت پاسخ این خط‌مشی استفاده می‌کنید.
• افزونه‌ای که اضافه، پیکربندی، و پیاده‌سازی شده است در محیطی که پراکسی API شما در آن پیاده‌سازی خواهد شد. به‌عبارت دیگر، اگر می‌خواهید از این خط‌مشی برای دسترسی به سرویس Google Cloud خاصی استفاده کنید، افزونه‌ای استقراریافته برای آن سرویس باید در محیط شما وجود داشته باشد. جزئیات پیکربندی معمولاً شامل اطلاعات موردنیاز برای محدود کردن دسترسی به منبع، مانند شناسه پروژه یا نام حساب است.

استفاده از خط‌مشی ExtensionCallout در PostClientFlow

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

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

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

• اگر مشتری Apigee Edge for Private Cloud هستید، از Update organization properties (به‌روزرسانی دارایی‌های سازمان) 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>

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

عنصر <Input>

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

نام متغیری که پاسخ کنش افزونه را ذخیره می‌کند.

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

مشخصه‌های <Output>

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

هیچ‌کدام.

کدهای خطا

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

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

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

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

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

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