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

คุณกำลังดูเอกสารประกอบ 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 จะมีรูปแบบที่สอดคล้องกันตามที่อธิบายไว้ในข้อมูลอ้างอิงข้อผิดพลาดของนโยบาย

ส่วนนี้จะอธิบายข้อความแสดงข้อผิดพลาดและตัวแปรโฟลว์ที่กําหนดให้เมื่อนโยบายนี้ทําให้เกิดข้อผิดพลาด ข้อมูลนี้เป็นสิ่งสําคัญที่คุณต้องทราบหากคุณกําลังพัฒนากฎข้อผิดพลาดสําหรับพร็อกซี หากต้องการเรียนรู้เพิ่มเติม โปรดดูที่สิ่งที่คุณจําเป็นต้องทราบเกี่ยวกับข้อผิดพลาดของนโยบายและการจัดการข้อผิดพลาด

ข้อผิดพลาดรันไทม์

ข้อผิดพลาดเหล่านี้อาจเกิดขึ้นเมื่อนโยบายทํางาน

ข้อผิดพลาดในการทําให้ใช้งานได้

ข้อผิดพลาดเหล่านี้อาจเกิดขึ้นเมื่อคุณทําให้พร็อกซีที่มีนโยบายนี้ใช้งานได้