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

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

ใช้นโยบาย Extension callout เพื่อรวมส่วนขยายลงในพร็อกซี API

ส่วนขยายให้สิทธิ์เข้าถึงทรัพยากรที่เฉพาะเจาะจงภายนอก Apigee Edge ทรัพยากรอาจเป็นบริการของ Google Cloud Platform เช่น Cloud Storage หรือ Cloud Speech-to-Text แต่ทรัพยากรดังกล่าวอาจเป็นทรัพยากรภายนอกใดๆ ก็ตามที่เข้าถึงได้ผ่าน HTTP หรือ HTTPS

หากต้องการดูภาพรวมของส่วนขยาย โปรดดูส่วนขยายคืออะไร หากต้องการดูบทแนะนำเบื้องต้น โปรดดูที่บทแนะนำ: การเพิ่มและการใช้ส่วนขยาย

ก่อนที่จะเข้าถึงส่วนขยายจากนโยบาย ExtensionExtension คุณต้องเพิ่ม กำหนดค่า และทำให้ส่วนขยายจากแพ็กเกจส่วนขยายที่ติดตั้งในองค์กร 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

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

เกี่ยวกับนโยบายขอส่วนขยายข้อความเสริม

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

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

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

การใช้นโยบาย ExtensionExtension ใน PostClientFlow

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

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

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

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

ข้อจำกัดทั้งหมดในการเรียกใช้นโยบาย MessageLoking จาก PostClientFlow จะมีผลกับนโยบาย Extensionวิส ดูข้อมูลเพิ่มเติมได้ที่หมายเหตุการใช้งาน

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

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

แอตทริบิวต์ <Connector callout>

<ConnectorCallout name="Extension-Callout-1" continueOnError="false" enabled="true" async="false">

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

แอตทริบิวต์ คำอธิบาย ค่าเริ่มต้น การมีบุคคลอยู่
name

ชื่อภายในของนโยบาย ค่าของแอตทริบิวต์ name มีตัวอักษร ตัวเลข ช่องว่าง ขีดกลาง ขีดล่าง และจุด ค่านี้ต้องมีอักขระไม่เกิน 255 ตัว

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

 ไม่มีข้อมูล จำเป็น
continueOnError

ตั้งค่าเป็น false เพื่อแสดงผลข้อผิดพลาดเมื่อนโยบายล้มเหลว ซึ่งถือเป็นเรื่องปกติสำหรับนโยบายส่วนใหญ่

ตั้งค่าเป็น true เพื่อให้การดำเนินการโฟลว์ดำเนินต่อไปได้แม้ว่านโยบายจะล้มเหลวก็ตาม

 false ไม่บังคับ
enabled

ตั้งค่าเป็น true เพื่อบังคับใช้นโยบาย

ตั้งค่าเป็น false เพื่อปิดนโยบาย ระบบจะไม่บังคับใช้นโยบายแม้ว่าจะยังแนบอยู่กับขั้นตอนก็ตาม

 จริง ไม่บังคับ
async

แอตทริบิวต์นี้เลิกใช้งานแล้ว

 false เลิกใช้

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

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

<DisplayName>Policy Display Name</DisplayName>
ค่าเริ่มต้น

ไม่มีข้อมูล

หากคุณไม่ใส่องค์ประกอบนี้ ระบบจะใช้ค่าของแอตทริบิวต์ name ของนโยบาย
การมีบุคคลอยู่ ไม่บังคับ
Type สตริง

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

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

<Action>action-exposed-by-extension</Action>
ค่าเริ่มต้น ไม่มี
การมีบุคคลอยู่ จำเป็น
Type สตริง

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

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

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

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

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

ค่าเริ่มต้น ไม่มี
การมีบุคคลอยู่ จำเป็น
Type สตริง

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

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

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

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

ค่าเริ่มต้น ไม่มี
การมีบุคคลอยู่ ไม่บังคับหรือต้องระบุ โดยขึ้นอยู่กับส่วนขยาย
Type สตริง

นี่คืออาร์กิวเมนต์ของการดำเนินการที่คุณระบุด้วยองค์ประกอบ <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>

การใช้ตัวแปรโฟลว์ใน 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 ที่มีเครื่องหมายอัญประกาศล้อมรอบ

อีลิเมนต์ <Export>

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

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

ค่าเริ่มต้น ไม่มี
การมีบุคคลอยู่ ไม่บังคับหรือต้องระบุ โดยขึ้นอยู่กับส่วนขยาย
Type ออบเจ็กต์หรือสตริงที่แยกวิเคราะห์ตามการตั้งค่าแอตทริบิวต์ parsed

เมื่อได้รับการตอบกลับแล้ว ระบบจะใส่ค่าการตอบกลับไว้ในตัวแปรที่คุณระบุที่นี่ ซึ่งคุณเข้าถึงได้จากโค้ดพร็อกซี API อื่นๆ

ออบเจ็กต์การตอบสนองของส่วนขยายอยู่ในรูปแบบ JSON วิธีการที่นโยบายจัดการกับ JSON มี 2 ตัวเลือกดังนี้

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

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

แอตทริบิวต์ คำอธิบาย ค่าเริ่มต้น การมีบุคคลอยู่
แยกวิเคราะห์แล้ว แยกวิเคราะห์ออบเจ็กต์ JSON ที่แสดงผลจากส่วนขยาย ซึ่งทำให้นโยบายอื่นๆ เข้าถึงข้อมูลในออบเจ็กต์ JSON เป็นตัวแปรได้ จริง ไม่บังคับ

ตัวแปรโฟลว์

ไม่มี

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

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

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

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

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

ชื่อข้อผิดพลาด สถานะ HTTP สาเหตุ
ดําเนินการไม่สําเร็จ 500 ส่วนขยายตอบสนองโดยมีข้อผิดพลาด

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

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

ชื่อข้อผิดพลาด เกิดขึ้นเมื่อ แก้ไข
InvalidConnectorInstance องค์ประกอบ <Connector> ว่างเปล่า
ConnectorInstanceDoesNotExists ส่วนขยายที่ระบุในองค์ประกอบ <Connector> ไม่มีอยู่ในสภาพแวดล้อม
InvalidAction องค์ประกอบ <Action> ในนโยบายส่วนขยายไฮไลต์ไม่มีหรือตั้งค่าเป็นค่าว่าง
AllowExtensionsInPostClientFlow ห้ามมีนโยบายข้อความเสริมของส่วนขยายในขั้นตอนโฟลวไคลเอ็นต์