นโยบายส่วนขยายไฮไลต์ของส่วนขยาย

คุณกำลังดูเอกสารประกอบ Apigee Edge
ไปที่ เอกสารประกอบเกี่ยวกับ Apigee X. ข้อมูล

ใช้นโยบาย Extensionข้อความไฮไลต์ เพื่อรวมส่วนขยายลงในพร็อกซี 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 Logging

โปรดดูตัวอย่างส่วนขยายทั้งหมดที่มีให้ที่หัวข้อภาพรวมข้อมูลอ้างอิงของส่วนขยาย

เกี่ยวกับนโยบาย ส่วนขยายไฮไลต์

ใช้นโยบาย ส่วนขยายข้อความไฮไลต์เมื่อคุณต้องการใช้ส่วนขยายที่กำหนดค่าเพื่อเข้าถึงทรัพยากรภายนอกจากภายในพร็อกซี API

ก่อนใช้นโยบายนี้ คุณจะต้องมีสิ่งต่อไปนี้

• รายละเอียดบางอย่างเกี่ยวกับทรัพยากรภายนอกที่คุณต้องการเข้าถึงจากนโยบายนี้ รายละเอียดเหล่านี้จะเฉพาะเจาะจงสำหรับแหล่งข้อมูลดังกล่าว ตัวอย่างเช่น หากนโยบายจะเข้าถึงฐานข้อมูล Cloud Firestore คุณจะต้องทราบชื่อคอลเล็กชันและเอกสารที่ต้องการสร้างหรือเข้าถึง โดยทั่วไปแล้ว คุณจะใช้ข้อมูลเฉพาะทรัพยากรในการกำหนดค่าคำขอและการจัดการการตอบกลับของนโยบายนี้
• ส่วนขยายที่เพิ่ม กำหนดค่า และทำให้ใช้งานได้ ในสภาพแวดล้อมที่จะมีการทำให้พร็อกซี API ใช้งานได้ กล่าวคือ คุณจะใช้นโยบายนี้เพื่อเข้าถึงบริการบางอย่างของ Google Cloud ส่วนขยายที่ทำให้ใช้งานได้แล้วสำหรับบริการนั้นจะต้องมีอยู่ในสภาพแวดล้อมของคุณ โดยทั่วไป รายละเอียดการกำหนดค่าจะมีข้อมูลที่จำเป็นสำหรับการจำกัดขอบเขต สิทธิ์เข้าถึงทรัพยากร เช่น รหัสโปรเจ็กต์หรือชื่อบัญชี

การใช้นโยบาย ชิ้นงานข้อความไฮไลต์ใน PostClientFlow

คุณสามารถเรียกใช้นโยบาย ส่วนขยายข้อความไฮไลต์ ได้จาก PostClientFlow ของพร็อกซี API PostClientFlow ทำงานหลังจากส่งการตอบสนองไปยังไคลเอ็นต์ที่ส่งคำขอ ซึ่งทำให้มั่นใจว่าเมตริกทั้งหมดพร้อมสำหรับการบันทึก โปรดดูรายละเอียดการใช้ PostClientFlow ที่ข้อมูลอ้างอิงการกำหนดค่าพร็อกซี API

หากต้องการใช้นโยบายส่วนขยายไฮไลต์ของส่วนขยายเพื่อเรียกใช้ส่วนขยาย Google Cloud Logging จาก PostClientFlow ให้ตรวจสอบว่าแฟล็ก features.allowExtensionsInPostClientFlow ได้รับการตั้งค่าเป็น true ในองค์กรของคุณ

• หากคุณเป็นลูกค้า Apigee Edge สำหรับ Public Cloud การตั้งค่าแฟล็ก features.allowExtensionsInPostClientFlow ได้รับการตั้งค่าเป็น true ตามค่าเริ่มต้น

• หากคุณเป็นลูกค้า Apigee Edge สำหรับ Private Cloud ให้ใช้ อัปเดตพร็อพเพอร์ตี้ขององค์กร API เพื่อตั้งค่าแฟล็ก features.allowExtensionsInPostClientFlow เป็น true

ข้อจำกัดทั้งหมดในการเรียกใช้นโยบาย MessageLนั้นๆ จาก PostClientFlow ก็มีผลกับนโยบาย ชิ้นงานข้อความไฮไลต์ ดูข้อมูลเพิ่มเติมได้ที่หมายเหตุการใช้งาน

การอ้างอิงองค์ประกอบ

<?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 เพื่อติดป้ายกำกับนโยบายใน เครื่องมือแก้ไขพร็อกซี UI การจัดการด้วยชื่อที่เป็นภาษาธรรมชาติต่างกัน

<DisplayName>Policy Display Name</DisplayName>

<Action> องค์ประกอบ

การดำเนินการแสดงส่วนขยายที่นโยบายควรเรียกใช้

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

ส่วนขยายแต่ละรายการจะแสดงชุดการดำเนินการของตนเองที่ให้สิทธิ์เข้าถึงฟังก์ชันการทำงานของทรัพยากรที่ส่วนขยายเป็นตัวแทน คุณอาจมองการดำเนินการเป็นฟังก์ชันที่เรียกใช้ด้วยนโยบายนี้ โดยใช้เนื้อหาขององค์ประกอบ <Input> เพื่อระบุอาร์กิวเมนต์ของฟังก์ชัน การตอบสนองของการดำเนินการจะจัดเก็บอยู่ในตัวแปรที่คุณระบุกับองค์ประกอบ <Output>

ดูรายการฟังก์ชันของส่วนขยายได้ที่ข้อมูลอ้างอิงของส่วนขยายที่คุณใช้เรียกใช้จากนโยบายนี้

<เครื่องมือเชื่อมต่อ> องค์ประกอบ

ชื่อของส่วนขยายที่กำหนดค่าที่จะใช้ ซึ่งเป็นชื่อที่กำหนดขอบเขตระดับสภาพแวดล้อมของส่วนขยายเมื่อมีการกำหนดค่าเพื่อทำให้ใช้งานได้กับสภาพแวดล้อม

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

ส่วนขยายหนึ่งมีค่าการกำหนดค่าที่อาจแตกต่างจากส่วนขยายอื่นที่ใช้งานโดยพิจารณาจากแพ็กเกจส่วนขยายเดียวกัน ค่าการกำหนดค่าเหล่านี้สามารถแสดงความแตกต่างที่สำคัญในฟังก์ชันการทำงานของรันไทม์ระหว่างส่วนขยายที่กำหนดค่าจากแพ็กเกจเดียวกัน ดังนั้น โปรดตรวจสอบว่าได้ระบุส่วนขยายที่ถูกต้องที่จะเรียกใช้

&lt;Input&gt; องค์ประกอบ

JSON ที่มีเนื้อหาคำขอเพื่อส่งไปยังส่วนขยาย

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

โดยพื้นฐานแล้วสิ่งนี้เป็นอาร์กิวเมนต์ของการดำเนินการที่คุณระบุด้วยเอลิเมนต์ <Action> ค่าขององค์ประกอบ <Input> จะแตกต่างกันไปตามส่วนขยายและการกระทำที่คุณเรียกใช้ ดูรายละเอียดเกี่ยวกับพร็อพเพอร์ตี้ของการดำเนินการแต่ละรายการได้ในเอกสารประกอบเกี่ยวกับแพ็กเกจส่วนขยาย

โปรดทราบว่าแม้ว่าค่าขององค์ประกอบ <Input> หลายค่าจะทำงานอย่างถูกต้องโดยไม่ต้องปิดเป็นส่วน <![CDATA[]]> แต่กฎของ JSON อนุญาตให้ใช้ค่าที่ไม่แยกวิเคราะห์เป็น XML แนวทางปฏิบัติแนะนำคือให้ใส่ 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>

การใช้ตัวแปรโฟลว์ใน JSON ของ <Input>

เนื้อหาของ <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> ต่อไปนี้มีการอ้างอิงตัวแปรโฟลว์ 2 รายการ

<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 ที่มีเครื่องหมายคำพูดอยู่ภายใน

&lt;Output&gt; องค์ประกอบ

ชื่อของตัวแปรที่จัดเก็บคำตอบของการดำเนินการของส่วนขยาย

<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 ทำได้ 2 วิธีดังนี้

• แยกวิเคราะห์ (ค่าเริ่มต้น): นโยบายจะแยกวิเคราะห์ออบเจ็กต์ JSON และสร้างตัวแปรด้วยข้อมูล JSON โดยอัตโนมัติ เช่น หาก JSON มี "messageId" : 12345; และคุณตั้งชื่อตัวแปรเอาต์พุต extensionOutput คุณสามารถเข้าถึงรหัสข้อความนั้นในนโยบายอื่นๆ โดยใช้ตัวแปร {extensionOutput.messageId} ได้
• ไม่ได้แยกวิเคราะห์: ตัวแปรเอาต์พุตมีการตอบสนอง JSON แบบข้อมูลดิบที่ไม่ได้แยกวิเคราะห์จากส่วนขยาย (หากต้องการ คุณยังแยกวิเคราะห์ค่าการตอบกลับได้ในขั้นตอนที่แยกต่างหากโดยใช้นโยบาย JavaScript)

&lt;Output&gt; ลักษณะ

ตัวแปรโฟลว์

ไม่มี

รหัสข้อผิดพลาด

ข้อผิดพลาดที่แสดงผลจากนโยบาย Apigee Edge จะมีรูปแบบที่สอดคล้องกันตามที่อธิบายไว้ในข้อมูลอ้างอิงข้อผิดพลาดของนโยบาย

This section describes the error messages and flow variables that are set when this policy triggers an error. This information is important to know if you are developing fault rules for a proxy. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.