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

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

ใช้นโยบาย ExtensionCallout เพื่อรวมส่วนขยายเข้ากับพร็อกซี API

ส่วนขยายช่วยให้เข้าถึงทรัพยากรที่เฉพาะเจาะจงภายนอก Apigee Edge ได้ ซึ่งอาจเป็นบริการของ Google Cloud Platform เช่น 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

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

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

• รายละเอียดบางอย่างเกี่ยวกับทรัพยากรภายนอกที่คุณต้องการเข้าถึงจากนโยบายนี้ รายละเอียดเหล่านี้จะเฉพาะเจาะจงสำหรับทรัพยากร ตัวอย่างเช่น หากนโยบายจะเข้าถึงฐานข้อมูล 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 Update organization properties เพื่อตั้งค่าสถานะ features.allowExtensionsInPostClientFlow เป็น true

ข้อจำกัดทั้งหมดในการเรียกใช้นโยบายการบันทึกข้อความจาก 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">

ตารางต่อไปนี้อธิบายแอตทริบิวต์ทั่วไปในองค์ประกอบระดับบนสุดของนโยบายทั้งหมด

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

ใช้เพิ่มเติมจากแอตทริบิวต์ name เพื่อติดป้ายกำกับนโยบายใน เครื่องมือแก้ไขพร็อกซี UI การจัดการด้วยชื่อที่เป็นภาษาธรรมชาติต่างกัน

<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> ตัวอย่างต่อไปนี้มีการอ้างอิงตัวแปรโฟลว์ 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 พร้อมเครื่องหมายคำพูดที่ครอบ

องค์ประกอบ <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 นโยบายมี 2 ตัวเลือกในการจัดการ JSON ดังนี้

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

แอตทริบิวต์ <Output>

ตัวแปรโฟลว์

ไม่มี

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

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

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

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

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

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

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