การเขียนโปรแกรมพร็อกซี API ด้วย JavaScript

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

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

ดาวน์โหลดและลองใช้โค้ดตัวอย่าง

เกี่ยวกับตัวอย่าง Cookbook นี้

ตัวอย่าง Cookbook นี้แสดงรูปแบบพร็อกซี API ที่คุณใช้ลักษณะการทำงานของ API ใน JavaScript ตัวอย่าง JavaScript ออกแบบมาเพื่อแสดงวิธีทำงานกับตัวแปรและเนื้อหาข้อความแบบง่าย ตัวอย่างหนึ่งจะแสดงวิธี รับ และ ตั้งค่า ตัวแปร ส่วนตัวอย่างที่ 2 จะแสดงวิธีแยกวิเคราะห์ JSON และสร้างข้อความจากผลลัพธ์

ตัวอย่าง JavaScript 2 รายการอยู่ในพร็อกซี API ดังนี้

• setHeaders.js: JavaScript นี้จะรับค่าตัวแปร 2-3 รายการที่ ตั้งค่าไว้เมื่อมีการเรียกใช้พร็อกซี API JavaScript จะเพิ่มตัวแปรเหล่านั้นลงในข้อความตอบกลับ เพื่อให้คุณเห็นค่าของตัวแปรสำหรับคำขอแต่ละรายการที่คุณส่ง
• minimize.js: JavaScript นี้จะแสดงวิธีทำงานกับเนื้อหาข้อความ แนวคิดเบื้องหลังตัวอย่างนี้คือบริการมักจะแสดงข้อมูลมากกว่าที่จำเป็น ดังนั้น JavaScript จะแยกวิเคราะห์ข้อความตอบกลับ แยกพร็อพเพอร์ตี้ที่น่าสนใจ 2-3 รายการ แล้วใช้พร็อพเพอร์ตี้เหล่านั้นเพื่อสร้างเนื้อหาของข้อความตอบกลับ

โค้ดสำหรับ setHeader.js

context.setVariable("response.header.X-Apigee-Target", context.getVariable("target.name"));
context.setVariable("response.header.X-Apigee-ApiProxyName", context.getVariable("apiproxy.name"));
context.setVariable("response.header.X-Apigee-ProxyName", context.getVariable("proxy.name"));
context.setVariable("response.header.X-Apigee-ProxyBasePath", context.getVariable("proxy.basepath"));
context.setVariable("response.header.X-Apigee-ProxyPathSuffix", context.getVariable("proxy.pathsuffix"));
context.setVariable("response.header.X-Apigee-ProxyUrl", context.getVariable("proxy.url"));

โค้ดสำหรับ minimize.js

// Parse the respose from the target.
var res = JSON.parse(context.proxyResponse.content);

// Pull out only the information we want to see in the response.
var minimizedResponse = { city: res.root.city,
                          state: res.root.state };
          
// Set the response variable. 
context.proxyResponse.content = JSON.stringify(minimizedResponse);

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

ก่อนเริ่มต้น

ก่อนที่จะสำรวจตัวอย่าง Cookbook นี้ คุณควรทำความคุ้นเคยกับแนวคิดพื้นฐานต่อไปนี้ด้วย

• นโยบายคืออะไรและวิธีแนบนโยบายกับพร็อกซี หากต้องการดูข้อมูลเบื้องต้นเกี่ยวกับนโยบาย โปรดดูนโยบายคืออะไร
• โครงสร้างของโฟลว์พร็อกซีตามที่อธิบายไว้ในการกำหนดค่าโฟลว์ โฟลว์ช่วยให้คุณ ระบุลำดับที่พร็อกซี API จะเรียกใช้นโยบาย ในตัวอย่างนี้ เราจะสร้างและเพิ่มนโยบายหลายรายการ ลงในโฟลว์พร็อกซี API
• วิธีจัดระเบียบโปรเจ็กต์พร็อกซี API ในระบบไฟล์ตามที่อธิบายไว้ใน การอ้างอิงการกำหนดค่าพร็อกซี API
• ความรู้ความเข้าใจในการทำงานเกี่ยวกับ XML, JSON และ JavaScript ในตัวอย่างนี้ คุณจะสร้างพร็อกซี API และนโยบายของพร็อกซีด้วยไฟล์ XML ที่อยู่ในระบบไฟล์

หากคุณดาวน์โหลดโค้ดตัวอย่าง คุณจะพบไฟล์ทั้งหมดที่กล่าวถึงในหัวข้อนี้ใน โฟลเดอร์ตัวอย่าง javascript-cookbook ส่วนต่อไปนี้จะอธิบาย โค้ดตัวอย่างโดยละเอียด

ทำความเข้าใจโฟลว์พร็อกซี

หากต้องการให้ JavaScript ทำงานในพร็อกซี API คุณต้องแนบ JavaScript กับโฟลว์โดยใช้การแนบนโยบาย ที่เรียกว่า "ขั้นตอน" นโยบายประเภท JavaScript (โปรดสังเกตการใช้ตัวพิมพ์ใหญ่) จะมีเพียงการ อ้างอิงชื่อไฟล์ JavaScript คุณชี้ให้นโยบายไปยังไฟล์ JavaScript ได้โดยใช้ องค์ประกอบ ResourceURL

ตัวอย่างเช่น นโยบายต่อไปนี้อ้างอิงไฟล์ JavaScript ที่ชื่อว่า setHeader.js

<Javascript name='setHeaders' timeLimit='200'>
    <ResourceURL>setHeaders.js</ResourceURL>
</Javascript>

คุณแนบนโยบายนี้กับโฟลว์พร็อกซี API ได้เช่นเดียวกับนโยบายประเภทอื่นๆ การแนบนโยบายกับโฟลว์พร็อกซี API จะเป็นการระบุตำแหน่งที่ควรเรียกใช้ JavaScript ซึ่งจะช่วยให้คุณเรียกใช้ JavaScript ที่โต้ตอบกับข้อความคำขอหรือข้อความตอบกลับ เมื่อข้อความเหล่านั้น "ไหล" ผ่านพร็อกซี API ในตัวอย่างนี้ JavaScript ทั้ง 2 รายการจะทำงานใน โฟลว์การตอบกลับ เนื่องจากนโยบายทำ 2 สิ่ง ได้แก่ ตั้งค่าส่วนหัว HTTP ในข้อความตอบกลับ และ 'ลด' ข้อความตอบกลับที่ Apigee Edge ส่งกลับไปยังแอปที่ส่งคำขอ

หากคุณเปิดการกำหนดค่าโฟลว์นี้ใน UI การจัดการ คุณจะเห็นการกำหนดค่าโฟลว์ ด้านล่าง

เลือกปลายทางพร็อกซี > ค่าเริ่มต้น > PostFlow ในแผงการนำทาง

การกำหนดค่า XML ที่เกี่ยวข้องสำหรับ ProxyEndpoint ที่ชื่อว่า "ค่าเริ่มต้น" จะแสดงอยู่ด้านล่าง

<ProxyEndpoint name="default">
  <PostFlow>
    <Response>
      <!-- Steps reference policies under /apiproxy/policies -->
      <!-- First, set a few HTTP headers with variables for this transaction. -->
      <Step><Name>setHeaders</Name></Step>
      <!-- Next, transform the response from XML to JSON for easier parsing with JavaScript -->
      <Step><Name>transform</Name></Step>
      <!-- Finally, use JavaScript to create minimized response with just city and state. -->
      <Step><Name>minimize</Name></Step>
    </Response>
  </PostFlow>
  <HTTPProxyConnection>
        <!-- BasePath defines the network address for this API proxy. See the script 'invoke.sh' to see how the complete URL for this API proxy is constructed.-->
    <BasePath>/javascript-cookbook</BasePath>
     <!-- Set VirtualHost to 'secure' to have this API proxy listen on HTTPS. -->
    <VirtualHost>default</VirtualHost>
  </HTTPProxyConnection>
  <RouteRule name="default">
    <TargetEndpoint>default</TargetEndpoint>
  </RouteRule>
</ProxyEndpoint>

สรุปองค์ประกอบของโฟลว์มีดังนี้

• <Request> - องค์ประกอบ <Request> ประกอบด้วยองค์ประกอบ <Step> หลายรายการ แต่ละขั้นตอนจะเรียกใช้นโยบายรายการใดรายการหนึ่งที่คุณสร้างขึ้นผ่านส่วนที่เหลือของ หัวข้อนี้ นโยบายเหล่านี้จะแนบ JavaScript กับโฟลว์พร็อกซี API และตำแหน่งของการแนบ นโยบายจะเป็นตัวกำหนดเวลาที่ JavaScript จะทำงาน
• <Response> - องค์ประกอบ <Response> ยังมี <Steps> ด้วย โดยขั้นตอนเหล่านี้จะเรียกใช้นโยบายที่รับผิดชอบในการประมวลผลการตอบกลับสุดท้าย จากเป้าหมาย (ซึ่งในตัวอย่างนี้คือเป้าหมายบริการจำลองของ Apigee โปรดสังเกตการตั้งค่า HTTPTargetConnection ใน /apiproxy/targets/default.xml.)
• <HTTPProxyConnection> - ระบุโฮสต์และเส้นทาง URI ที่ กำหนดที่อยู่เครือข่ายที่แอปเรียกใช้เพื่อใช้ API นี้
  
• <RouteRule> - องค์ประกอบนี้จะระบุการกำหนดค่า TargetEndpoint ที่ ProxyEndpoint เรียกใช้

การเพิ่มโค้ด JavaScript ลงในพร็อกซี

ระบบจะจัดเก็บ JavaScript (เช่น สคริปต์ Python, ไฟล์ JAR ของ Java, ไฟล์ XSLT และอื่นๆ) เป็น ทรัพยากร เมื่อเพิ่งเริ่มทำงานกับ JavaScript การจัดเก็บไฟล์ JavaScript ในพร็อกซี API จะเป็นวิธีที่ง่ายที่สุด เมื่อคุณมีความชำนาญมากขึ้น คุณควรทำให้ JavaScript เป็นแบบทั่วไปและ นำกลับมาใช้ซ้ำได้มากที่สุด จากนั้นจัดเก็บไว้ที่ระดับ สภาพแวดล้อม หรือ องค์กร วิธีนี้จะช่วยป้องกันไม่ให้คุณต้องจัดเก็บไฟล์ JavaScript เดียวกันในพร็อกซี API หลายรายการ ซึ่ง จัดการได้ยากอย่างรวดเร็ว

ดูข้อมูลเกี่ยวกับการจัดเก็บทรัพยากรที่ระดับองค์กรและสภาพแวดล้อมได้ที่ไฟล์ทรัพยากร

ลองเลย

ดูวิธีการทำให้พร็อกซีใช้งานได้และเรียกใช้พร็อกซีได้ที่ README ของ Cookbook JavaScript

การนำเข้าและทำให้พร็อกซี API ใช้งานได้

หลังจากทำการเปลี่ยนแปลงแล้ว คุณสามารถบันทึก พร็อกซี API ในเครื่องมือสร้างพร็อกซี API ใน UI การจัดการ

หรือคุณจะเรียกใช้คำสั่งต่อไปนี้ในไดเรกทอรี /api-platform-samples/doc-samples/javascript-cookbook ก็ได้

$ sh deploy.sh

การทดสอบ JavaScript

เรียกใช้คำสั่งต่อไปนี้ในไดเรกทอรี /api-platform-samples/doc-samples/javascript-cookbook

$ sh invoke.sh

เราใช้แฟล็ก -v ของ curl ในสคริปต์ของ Shell เพื่อดูส่วนหัว HTTP ในข้อความตอบกลับ ที่ JavaScript แก้ไข

คุณส่งคำขอได้โดยตรงดังนี้

$ curl -v http://{org_name}-test.apigee.net/javascript-cookbook 

หาก JavaScript ทำงานอย่างถูกต้อง คุณจะเห็นการตอบกลับลักษณะต่อไปนี้

< X-Apigee-Demo-Target: default
< X-Apigee-Demo-ApiProxyName: simple-javascript
< X-Apigee-Demo-ProxyName: default
< X-Apigee-Demo-ProxyBasePath: /javascript-cookbook
< X-Apigee-Demo-ProxyPathSuffix: /xml
< X-Apigee-Demo-ProxyUrl: http://rrt331ea.us-ea.4.apigee.com/javascript-cookbook/xml
 
{"city":"San Jose","state":"CA"}

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

ข้อผิดพลาดของสคริปต์

คุณจะเห็นข้อผิดพลาดอย่างหลีกเลี่ยงไม่ได้เมื่อเขียน JavaScript รูปแบบข้อผิดพลาด JavaScript ที่ พร็อกซี API จะแสดงมีลักษณะดังนี้

{  
   "fault":{  
      "faultstring":"Execution of rewriteTargetUrl failed with error: Javascript runtime error: \"TypeError: Cannot find function getVariable in object TARGET_REQ_FLOW. (rewriteTargetUrl_js#1). at line 1 \"",
      "detail":{  
         "errorcode":"steps.javascript.ScriptExecutionFailed"
      }
   }
}

กรณีที่ควรใช้ JavaScript

ใน Apigee Edge มักจะมีวิธีมากกว่า 1 วิธีในการใช้ฟังก์ชันการทำงานที่เฉพาะเจาะจง ใช้ ฟีเจอร์นโยบายที่มีให้มาในตัวเมื่อเป็นไปได้ และหลีกเลี่ยงการเขียนโค้ดตรรกะพร็อกซี API ทั้งหมดใน JavaScript แม้ว่า Apigee Edge จะใช้ประโยชน์จาก JavaScript ที่คอมไพล์แล้วเพื่อปรับปรุง ประสิทธิภาพ แต่ JavaScript ก็ไม่น่าจะทำงานได้ดีเท่านโยบาย JavaScript อาจดูแลรักษาและแก้ไขข้อบกพร่องได้ยากกว่า ให้ใช้ JavaScript สำหรับฟังก์ชันการทำงานที่เป็นเอกลักษณ์ตามความต้องการของคุณ

หากประสิทธิภาพเป็นเรื่องที่คุณกังวลสำหรับฟังก์ชันการทำงานที่กำหนดเอง ให้ใช้ Java เมื่อเป็นไปได้

สรุป

ในหัวข้อ Cookbook นี้ คุณได้เรียนรู้วิธีรวม JavaScript ไว้ในการกำหนดค่าพร็อกซี API เพื่อใช้ลักษณะการทำงานที่กำหนดเอง ลักษณะการทำงานที่กำหนดเองซึ่งตัวอย่างใช้ แสดงให้เห็นวิธีรับและตั้งค่าตัวแปร รวมถึงวิธีแยกวิเคราะห์ JSON และสร้างข้อความตอบกลับที่กำหนดเอง