laravel api handler
v0.7.3
แพ็คเกจตัวช่วยนี้มีฟังก์ชันสำหรับการแยกวิเคราะห์ URL ของคำขอ REST-API
หมายเหตุ: เวอร์ชันนี้ใช้สำหรับ Laravel 5 เมื่อใช้ Laravel 4 คุณต้องใช้เวอร์ชัน 0.4.x
ติดตั้งแพ็คเกจผ่านผู้แต่งโดยการรัน
composer require marcelgwerder/laravel-api-handler
เมื่อผู้แต่งเสร็จแล้วให้เพิ่มผู้ให้บริการไปยังอาร์เรย์ providers ใน app/config/app.php :
MarcelgwerderApiHandlerApiHandlerServiceProvider::class,
ตอนนี้นำเข้าส่วนหน้าของ ApiHandler ไปยังคลาสของคุณ:
use Marcelgwerder ApiHandler Facades ApiHandler ; หรือตั้งนามแฝงใน app.php :
'ApiHandler' => MarcelgwerderApiHandlerFacadesApiHandler::class,
แค่นั้นแหละ!
วิธีการสร้างความสัมพันธ์ตอนนี้จำเป็นต้องมีคำอธิบายประกอบ @Relation เพื่อพิสูจน์ว่าเป็นวิธีการสร้างความสัมพันธ์ ไม่ใช่วิธีอื่นใด (ดูประเด็นที่ 11)
/**
* @Relation
*/
public function author () {
return $ this -> belongsTo ( ' Author ' );
} หากคุณส่งอาร์เรย์เป็นพารามิเตอร์ตัวที่สองเพื่อ parseSingle ตอนนี้จะต้องมีคู่คอลัมน์/ค่า สิ่งนี้ทำให้เราสามารถผ่านเงื่อนไขหลายประการได้ เช่น:
ApiHandler :: parseSingle ( $ books , array ( ' id_origin ' => ' Random Bookstore Ltd ' , ' id ' => 1337 )); หากต้องการแทนที่การกำหนดค่า ให้สร้างไฟล์ชื่อ apihandler.php ในโฟลเดอร์กำหนดค่าของแอปของคุณ
ตรวจสอบไฟล์ปรับแต่งในแหล่งแพ็คเกจเพื่อดูว่ามีตัวเลือกใดบ้าง
ขณะนี้การแยกวิเคราะห์ URL รองรับ:
มีทรัพยากร API อยู่สองประเภทที่รองรับ ได้แก่ ออบเจ็กต์เดี่ยวและคอลเลกชั่นออบเจ็กต์
หากคุณจัดการคำขอ GET บนทรัพยากรที่เป็นตัวแทนของออบเจ็กต์เดียว เช่น /api/books/1 ให้ใช้เมธอด parseSingle
parseSingle($queryBuilder, $identification, [$queryParams]):
id หรือคอลัมน์อาร์เรย์/คู่ค่า ( array('isbn' => '1234') ) ใช้เป็นตัวระบุเฉพาะของวัตถุ ApiHandler :: parseSingle ( $ book , 1 ); หากคุณจัดการคำขอ GET บนทรัพยากรที่แสดงถึงออบเจ็กต์หลายรายการ เช่น /api/books ให้ใช้เมธอด parseMultiple
parseMultiple($queryBuilder, $fullTextSearchColumns, [$queryParams]):
ApiHandler :: parseMultiple ( $ book , array ( ' title ' , ' isbn ' , ' description ' )); ทั้ง parseSingle และ parseMultiple ส่งคืนวัตถุ Result ด้วยวิธีต่อไปนี้:
getBuilder(): ส่งคืน $queryBuilder ดั้งเดิมพร้อมฟังก์ชันทั้งหมดที่นำไปใช้กับมัน
getResult(): ส่งคืนวัตถุผลลัพธ์ที่ส่งคืนโดยฟังก์ชัน get() หรือ first() ของ Laravel
getResultOrFail() : ส่งคืนวัตถุผลลัพธ์ที่ส่งคืนโดยฟังก์ชัน get() ของ Laravel หากคุณคาดหวังหลายวัตถุหรือ firstOrFail() หากคุณคาดหวังวัตถุเดียว
getResponse($resultOrFail = false): ส่งคืนอ็อบเจ็กต์ Laravel Response รวมถึงเนื้อหา ส่วนหัว และโค้ดสถานะ HTTP หาก $resultOrFail เป็นจริง เมธอด getResultOrFail() จะถูกใช้เป็นการภายในแทน getResult()
getHeaders(): ส่งกลับอาร์เรย์ของส่วนหัวที่เตรียมไว้
getMetaProviders(): ส่งคืนอาร์เรย์ของวัตถุผู้ให้บริการเมตา แต่ละออบเจ็กต์เหล่านี้ให้ข้อมูลเมตาประเภทเฉพาะผ่านเมธอด get()
cleanup($cleanup): หากเป็นจริง อาเรย์ผลลัพธ์จะถูกล้างออกจากความสัมพันธ์ที่เพิ่มเข้ามาโดยไม่ได้ตั้งใจ ความสัมพันธ์ดังกล่าวสามารถเพิ่มได้โดยอัตโนมัติหากเข้าถึงเป็นคุณสมบัติในตัวเข้าถึงโมเดล ค่าเริ่มต้นส่วนกลางสำหรับการล้างข้อมูลสามารถกำหนดได้โดยใช้ตัวเลือกการกำหนดค่า cleanup_relations ซึ่งมีค่าเริ่มต้นเป็น false
ApiHandler :: parseSingle ( $ books , 42 )-> cleanup ( true )-> getResponse (); พารามิเตอร์การสืบค้นทุกรายการ ยกเว้นฟังก์ชันที่กำหนดไว้ล่วงหน้า _fields , _with , _sort , _limit , _offset , _config และ _q จะถูกตีความว่าเป็นตัวกรอง อย่าลืมลบพารามิเตอร์เพิ่มเติมที่ไม่ได้มีไว้สำหรับการกรองก่อนที่จะส่งต่อไปยัง parseMultiple
/api/books?title=The Lord of the Rings
ตัวกรองทั้งหมดจะรวมกับตัวดำเนินการ AND
/api/books?title-lk=The Lord*&created_at-min=2014-03-14 12:55:02
ตัวอย่างข้างต้นจะส่งผลให้ SQL ต่อไปนี้โดยที่:
WHERE ` title ` LIKE " The Lord% " AND ` created_at ` >= " 2014-03-14 12:55:02 " นอกจากนี้ยังสามารถใช้หลายค่าสำหรับตัวกรองเดียวได้อีกด้วย ค่าหลายค่าจะถูกคั่นด้วยไปป์ | - ค่าหลายค่าจะถูกรวมเข้ากับ OR ยกเว้นเมื่อมี -not ส่วนต่อท้าย ค่าเหล่านั้นจะรวมกับ AND ตัวอย่างเช่น หนังสือทั้งหมดที่มีรหัส 5 หรือ 6:
/api/books?id=5|6
หรือหนังสือทั้งหมดยกเว้นหนังสือที่มีรหัส 5 หรือ 6:
/api/books?id-not=5|6
เช่นเดียวกันสามารถทำได้โดยใช้คำต่อท้าย -in :
/api/books?id-in=5,6
ตามลำดับส่วนต่อท้าย not-in :
/api/books?id-not-in=5,6
| คำต่อท้าย | ผู้ดำเนินการ | ความหมาย |
|---|---|---|
| -ล | ชอบ | เหมือนกับตัวดำเนินการ SQL LIKE |
| -ไม่ใช่-lk | ไม่ชอบ | เช่นเดียวกับตัวดำเนินการ SQL NOT LIKE |
| -ใน | ใน | เหมือนกับตัวดำเนินการ SQL IN |
| -ไม่เข้า | ไม่เข้า | เช่นเดียวกับตัวดำเนินการ SQL NOT IN |
| -นาที | - | มากกว่าหรือเท่ากับ |
| -สูงสุด | - | เล็กกว่าหรือเท่ากับ |
| -เซนต์ | - | เล็กกว่า |
| -gt | - | มากกว่า |
| -ไม่ | - | ไม่เท่ากับ |
การเรียงลำดับสองวิธีจากน้อยไปหามากและจากมากไปน้อย ทุกคอลัมน์ที่ควรเรียงลำดับจากมากไปหาน้อยจะขึ้นต้นด้วย - เสมอ
/api/books?_sort=-title,created_at
รองรับการใช้งานการค้นหาข้อความแบบเต็มสองแบบ คุณสามารถเลือกได้ว่าจะใช้อันไหนโดยเปลี่ยนตัวเลือก fulltext ในไฟล์กำหนดค่าเป็น default หรือ native
หมายเหตุ: เมื่อใช้พารามิเตอร์ _q ว่างเปล่า การค้นหาจะส่งกลับผลลัพธ์ที่ว่างเปล่าเสมอ
การใช้งานที่กำหนดเองแบบจำกัด (ค่าเริ่มต้น)
ข้อความที่กำหนดจะถูกแบ่งออกเป็นคำหลักซึ่งจะถูกค้นหาในฐานข้อมูลแล้ว เมื่อใดก็ตามที่มีคำหลักคำใดคำหนึ่งอยู่ แถวที่เกี่ยวข้องจะรวมอยู่ในชุดผลลัพธ์
/api/books?_q=The Lord of the Rings
ตัวอย่างข้างต้นส่งคืนทุกแถวที่มีหนึ่งในคำหลัก The , Lord , of , the , Rings ในคอลัมน์ใดคอลัมน์หนึ่ง คอลัมน์ที่ต้องพิจารณาในการค้นหาข้อความแบบเต็มจะถูกส่งผ่านไปยัง parseMultiple
การใช้งาน MySQL ดั้งเดิม
หากเวอร์ชัน MySQL ของคุณรองรับการค้นหาข้อความแบบเต็มสำหรับเอ็นจิ้นที่คุณใช้ คุณสามารถใช้การค้นหาขั้นสูงนี้ในตัวจัดการ API
เพียงเปลี่ยนตัวเลือกการกำหนดค่า fulltext เป็น native และตรวจสอบให้แน่ใจว่ามีดัชนีข้อความแบบเต็มที่เหมาะสมในคอลัมน์ที่คุณส่งไปยัง parseMultiple
ผลลัพธ์แต่ละรายการจะมีคอลัมน์ _score ซึ่งช่วยให้คุณสามารถจัดเรียงผลลัพธ์ตามความเหมาะสมที่ตรงกับข้อความค้นหา เช่น
/api/books?_q=The Lord of the Rings&_sort=-_score
คุณสามารถปรับเปลี่ยนชื่อของคอลัมน์นี้ได้โดยแก้ไขการตั้งค่า fulltext_score_column ในไฟล์กำหนดค่า
หากต้องการกำหนดจำนวนชุดข้อมูลสูงสุดในผลลัพธ์ ให้ใช้ _limit
/api/books?_limit=50
หากต้องการกำหนดออฟเซ็ตของชุดข้อมูลในผลลัพธ์ ให้ใช้ _offset
/api/books?_offset=20&_limit=50
โปรดทราบว่าในการใช้ offset คุณจะต้องระบุ limit ด้วยเสมอ MySQL ส่งข้อผิดพลาดสำหรับคำจำกัดความออฟเซ็ตโดยไม่มีขีดจำกัด
ตัวจัดการ api ยังรองรับความสัมพันธ์แบบ Eloquent อีกด้วย ดังนั้น หากคุณต้องการรับหนังสือทั้งหมดที่มีผู้แต่ง เพียงเพิ่มผู้แต่งลงในพารามิเตอร์ _with
/api/books?_with=author
ความสัมพันธ์สามารถซ้อนกันได้:
/api/books?_with=author.awards
เพื่อให้สิ่งนี้ใช้งานได้ คุณต้องเพิ่มคำอธิบายประกอบ @Relation ให้กับวิธีความสัมพันธ์แต่ละวิธีของคุณ เช่น:
/**
* @Relation
*/
public function author () {
return $ this -> belongsTo ( ' Author ' );
} นี่เป็นสิ่งจำเป็นด้วยเหตุผลด้านความปลอดภัย เพื่อให้สามารถเรียกใช้เฉพาะวิธีความสัมพันธ์จริงเท่านั้นโดยใช้ _with
หมายเหตุ: เมื่อใดก็ตามที่คุณจำกัดฟิลด์ด้วย _fields ร่วมกับ _with ภายใต้ประทุน ฟิลด์ต่างๆ จะถูกขยายออกไปพร้อมกับคีย์หลัก/คีย์ต่างประเทศของความสัมพันธ์ Eloquent ต้องการคีย์การเชื่อมโยงเพื่อรับโมเดลที่เกี่ยวข้อง
คุณสามารถเพิ่มข้อมูลเพิ่มเติมในการตอบกลับได้ ขณะนี้มีการนับสองประเภทที่สามารถเพิ่มลงในส่วนหัวการตอบกลับได้
total-count ซึ่งแสดงถึงจำนวนองค์ประกอบทั้งหมดของทรัพยากรหรือเพื่อให้เฉพาะเจาะจงมากขึ้น การนับบนอินสแตนซ์ตัวสร้างแบบสอบถามที่ส่งผ่านครั้งแรก filter-count ที่นำตัวกรองมาพิจารณาเพิ่มเติม ตัวอย่างเช่นอาจมีประโยชน์ในการใช้การแบ่งหน้า
/api/books?id-gt=5&_config=meta-total-count,meta-filter-count
ฟิลด์เมตาทั้งหมดมีอยู่ในส่วนหัวการตอบกลับตามค่าเริ่มต้น มีการใช้ส่วนหัวแบบกำหนดเองต่อไปนี้:
| การกำหนดค่า | ส่วนหัว |
|---|---|
| เมตารวมนับ | Meta-Total-นับ |
| เมตากรองนับ | Meta-Filter-นับ |
ตามค่าเริ่มต้นข้อมูลเมตาจะรวมอยู่ในส่วนหัวการตอบกลับ หากคุณต้องการรวมทุกอย่างไว้ด้วยกันในเนื้อหาการตอบกลับ คุณสามารถขอสิ่งที่เรียกว่า "envelope" ได้โดยการรวม response-envelope ในพารามิเตอร์ _config หรือโดยการแทนที่ config.php เริ่มต้นของแพ็คเกจ
ซองจดหมายมีโครงสร้างดังต่อไปนี้:
{
"meta" : {
},
"data" : [
]
}
