API การเดินทางและการนำส่งแบบออนดีมานด์ของ Fleet Engine ช่วยให้คุณจัดการการเดินทางและสถานะของยานพาหนะสำหรับแอปพลิเคชันการเดินทางและความคืบหน้าของคำสั่งซื้อได้ โดยจะจัดการธุรกรรมระหว่าง Driver SDK, Consumer SDK และบริการแบ็กเอนด์ของคุณ ซึ่งสื่อสารกับ Fleet Engine ได้โดยการเรียกใช้ gRPC หรือ REST
สิ่งที่ต้องดำเนินการก่อน
สำหรับการพัฒนา ให้ตรวจสอบว่าคุณติดตั้ง Cloud SDK (gcloud) และได้รับการตรวจสอบสิทธิ์สำหรับโปรเจ็กต์แล้ว
Shell
gcloud auth login
คุณควรเห็นข้อความดำเนินการสำเร็จ เช่น
You are now logged in as [my-user@example.com].
Your current project is [project-id]. You ...
ตรวจสอบว่าได้กำหนดค่า API ของโซลูชัน Fleet Engine สำหรับเรียกรถและการนำส่งแบบออนดีมานด์อย่างเหมาะสม
Shell
gcloud --project=project-id services enable fleetengine.googleapis.com
หากคำสั่งนี้ทำให้เกิดข้อผิดพลาด โปรดตรวจสอบกับผู้ดูแลระบบโปรเจ็กต์และตัวแทนทีมสนับสนุนของ Google เพื่อขอสิทธิ์เข้าถึง
Logging
Fleet Engine จะเขียนข้อความบันทึกเกี่ยวกับการเรียก API ที่ได้รับลงใน บันทึกของ Google Cloud Platform ได้ ดูภาพรวมเกี่ยวกับวิธีอ่านและวิเคราะห์บันทึกในเอกสาร Cloud Logging
โปรเจ็กต์ที่สร้างก่อนวันที่ 10 ก.พ. 2022 อาจไม่ได้เปิดใช้การบันทึกโดยค่าเริ่มต้น ดูรายละเอียดเพิ่มเติมได้ในเอกสารการบันทึก
ไลบรารีไคลเอ็นต์
เราเผยแพร่ไลบรารีของไคลเอ็นต์ในภาษาโปรแกรมทั่วไปหลายภาษา ไลบรารีเหล่านี้จะช่วยให้นักพัฒนาแอปได้รับประสบการณ์การใช้งานที่ดีขึ้นผ่าน REST หรือ gRPC แบบข้อมูลดิบ โปรดดูวิธีการรับไลบรารีของไคลเอ็นต์สำหรับแอปพลิเคชันเซิร์ฟเวอร์ที่หัวข้อไลบรารีของไคลเอ็นต์
ตัวอย่าง Java ในเอกสารประกอบนี้จะถือว่าคุ้นเคยกับ gRPC อยู่แล้ว
การตรวจสอบสิทธิ์และการให้สิทธิ์
คุณสามารถกำหนดค่าความสามารถที่ให้บริการโดย "การเดินทางและความคืบหน้าในการสั่งซื้อ" ผ่าน Google Cloud Console API และ SDK เหล่านี้ต้องใช้ JSON Web Token ที่ลงนามแล้วโดยใช้บัญชีบริการที่สร้างขึ้นจาก Cloud Console
ตั้งค่าโปรเจ็กต์ที่อยู่ในระบบคลาวด์
หากต้องการตั้งค่าโปรเจ็กต์ระบบคลาวด์ ให้สร้างโปรเจ็กต์ก่อนแล้วจึงสร้างบัญชีบริการ
วิธีสร้างโปรเจ็กต์ Google Cloud
- สร้างโปรเจ็กต์ Google Cloud โดยใช้ Google Cloud Console
- เปิดใช้ API และแดชบอร์ดบริการเพื่อเปิดใช้ Local Rides and Deliveries API
บัญชีบริการเชื่อมโยงกับบทบาทอย่างน้อย 1 บทบาท โดยใช้เพื่อสร้างเว็บโทเค็น JSON ที่ให้สิทธิ์ชุดต่างๆ โดยขึ้นอยู่กับบทบาท โดยปกติแล้ว เพื่อลดความเสี่ยงจากการละเมิด คุณสามารถสร้างบัญชีบริการหลายบัญชีโดยให้แต่ละบัญชีมีชุดบทบาทขั้นต่ำที่จำเป็น
ความคืบหน้าการเดินทางและคําสั่งซื้อใช้บทบาทต่อไปนี้
บทบาท | คำอธิบาย |
---|---|
ผู้ใช้ Fleet Engine Consumer SDK
roles/fleetengine.consumerSdkUser |
ให้สิทธิ์ในการค้นหายานพาหนะและเรียกข้อมูลเกี่ยวกับยานพาหนะและการเดินทาง โดยทั่วไปแล้ว โทเค็นที่สร้างโดยบัญชีบริการที่มีบทบาทนี้จะนำไปใช้จากอุปกรณ์เคลื่อนที่ของแอปบริการร่วมเดินทางหรือบริการจัดส่งสำหรับผู้ใช้ทั่วไป |
ผู้ใช้ Fleet Engine Driver SDK
roles/fleetengine.driverSdkUser |
ให้สิทธิ์อัปเดตตำแหน่งและเส้นทางของยานพาหนะ รวมถึงเรียกข้อมูลเกี่ยวกับยานพาหนะและการเดินทาง โดยทั่วไปแล้ว โทเค็นที่สร้างโดยบัญชีบริการที่มีบทบาทนี้จะมาจากอุปกรณ์เคลื่อนที่ แอปบริการร่วมเดินทางหรือคนขับรถส่งของ |
ผู้ดูแลระบบตามคำขอของ Fleet Engine
roles/fleetengine.ondemandAdmin |
มอบสิทธิ์การอ่านและเขียนทรัพยากรยานพาหนะและการเดินทางทั้งหมด ผู้ใช้หลักที่มีบทบาทนี้ไม่จำเป็นต้องใช้ JWT และควรใช้ข้อมูลเข้าสู่ระบบเริ่มต้นของแอปพลิเคชันแทน ระบบจะไม่พิจารณาการอ้างสิทธิ์ JWT ที่กำหนดเอง บทบาทนี้ควรจำกัดเฉพาะสภาพแวดล้อมที่เชื่อถือได้ (แบ็กเอนด์ของลูกค้า) |
roles/fleetengine.serviceSuperUser |
ให้สิทธิ์แก่ API ของยานพาหนะและการเดินทางทั้งหมด โดยทั่วไปจะใช้โทเค็นที่สร้างโดยบัญชีบริการที่มีบทบาทนี้จากเซิร์ฟเวอร์แบ็กเอนด์ของคุณ บทบาทนี้เลิกใช้งานแล้ว โปรดใช้ roles/fleetengine.ondemandAdmin แทน |
ตัวอย่างเช่น สร้างบัญชีบริการให้กับแต่ละบทบาททั้ง 3 บทบาท และมอบหมายบทบาทที่เกี่ยวข้อง
gcloud --project=project-id iam service-accounts create fleet-engine-consumer-sdk gcloud projects add-iam-policy-binding project-id \ --member=serviceAccount:fleet-engine-consumer-sdk@project-id.iam.gserviceaccount.com \ --role=roles/fleetengine.consumerSdkUser gcloud --project=project-id iam service-accounts create fleet-engine-driver-sdk gcloud projects add-iam-policy-binding project-id \ --member=serviceAccount:fleet-engine-driver-sdk@project-id.iam.gserviceaccount.com \ --role=roles/fleetengine.driverSdkUser gcloud --project=project-id iam service-accounts create fleet-engine-su gcloud projects add-iam-policy-binding project-id \ --member=serviceAccount:fleet-engine-su@project-id.iam.gserviceaccount.com \ --role=roles/fleetengine.serviceSuperUser
Driver และ Consumer SDK สร้างขึ้นตามบทบาทมาตรฐานเหล่านี้
อีกทางเลือกหนึ่งคือ คุณอาจสร้างบทบาทที่กำหนดเอง ซึ่งอนุญาตให้รวมชุดสิทธิ์ที่กำหนดเองเข้าด้วยกัน SDK ไดรเวอร์และผู้บริโภคจะแสดงข้อความแสดงข้อผิดพลาดเมื่อใดก็ตามที่ไม่มีสิทธิ์ที่จำเป็น ด้วยเหตุนี้ เราขอแนะนำอย่างยิ่งให้ใช้ชุดบทบาทมาตรฐานที่แสดงด้านบนและไม่ใช้บทบาทที่กำหนดเอง
หากจำเป็นต้องสร้างโทเค็น JWT สำหรับไคลเอ็นต์ที่ไม่น่าเชื่อถือ การเพิ่มผู้ใช้ลงในบทบาทผู้สร้างโทเค็นบัญชีบริการจะช่วยให้ผู้ใช้สร้างโทเค็นด้วยเครื่องมือบรรทัดคำสั่ง gcloud ได้
gcloud projects add-iam-policy-binding project-id \
--member=user:my-user@example.com \
--role=roles/iam.serviceAccountTokenCreator
โดยที่ my-user@example.com
คืออีเมลที่ใช้ในการตรวจสอบสิทธิ์กับ gcloud (gcloud auth list
--format='value(account)'
)
ไลบรารีการตรวจสอบสิทธิ์ Fleet Engine
Fleet Engine ใช้ JSON Web Token (JWT) เพื่อจำกัดการเข้าถึง API ของ Fleet Engine ไลบรารีการตรวจสอบสิทธิ์ Fleet Engine ใหม่มีให้ใช้ใน GitHub ช่วยลดความยุ่งยากในการก่อสร้าง Fleet Engine JWT และเซ็นชื่ออย่างปลอดภัย
ไลบรารีมีประโยชน์ดังต่อไปนี้
- ลดความซับซ้อนของกระบวนการสร้างโทเค็น Fleet Engine
- มีกลไกการรับรองโทเค็นที่นอกเหนือจากการใช้ไฟล์ข้อมูลเข้าสู่ระบบ (เช่น การแอบอ้างบัญชีบริการ)
- แนบโทเค็นที่ลงชื่อไว้กับคำขอขาออกที่ส่งจากสตับ gRPC หรือไคลเอ็นต์ GAPIC
การสร้าง JSON Web Token (JWT) สำหรับการให้สิทธิ์
เมื่อไม่ได้ใช้ไลบรารีการตรวจสอบสิทธิ์ Fleet Engine คุณจะต้องสร้าง JSON Web Token (JWT) ภายในฐานของโค้ดโดยตรง คุณจึงต้องมีความเข้าใจอย่างลึกซึ้ง เกี่ยวกับ JWT และความเกี่ยวข้องกับ Fleet Engine นี่จึงเป็นเหตุผลที่เราขอแนะนำอย่างยิ่งให้ใช้ประโยชน์จากไลบรารีการตรวจสอบสิทธิ์ Fleet Engine
ใน Fleet Engine นั้น JSON Web Token (JWT) จะมีการตรวจสอบสิทธิ์ระยะเวลาสั้นๆ และช่วยให้มั่นใจว่าอุปกรณ์จะสามารถปรับเปลี่ยนยานพาหนะ การเดินทาง หรืองานที่ได้รับอนุญาตเท่านั้น JWT มีส่วนหัวและส่วนการอ้างสิทธิ์ ส่วนหัวประกอบด้วยข้อมูล เช่น คีย์ส่วนตัวที่จะใช้ (ซึ่งได้มาจากบัญชีบริการ) และอัลกอริทึมการเข้ารหัส ส่วนการอ้างสิทธิ์จะมีข้อมูลต่างๆ เช่น เวลาที่สร้างโทเค็น, Time to Live ของโทเค็น, บริการที่อ้างสิทธิ์การเข้าถึง และข้อมูลการให้สิทธิ์อื่นๆ เพื่อกำหนดขอบเขตการเข้าถึง ตัวอย่างเช่น รหัสยานพาหนะ
ส่วนหัว JWT ประกอบด้วยฟิลด์ต่อไปนี้
ฟิลด์ | คำอธิบาย |
---|---|
alg | อัลกอริทึมที่จะใช้ "RS256" |
typ | ประเภทของโทเค็น "JWT" |
บุตรหลาน | รหัสคีย์ส่วนตัวของบัญชีบริการ คุณดูค่านี้ได้ในช่อง "private_key_id" ของไฟล์ JSON ของบัญชีบริการ ตรวจสอบว่าได้ใช้คีย์จากบัญชีบริการที่มีระดับสิทธิ์ที่ถูกต้อง |
ส่วนการอ้างสิทธิ์ JWT ประกอบด้วยฟิลด์ต่อไปนี้
ฟิลด์ | คำอธิบาย |
---|---|
คือ | อีเมลของบัญชีบริการ |
สำรอง | อีเมลของบัญชีบริการ |
Aud | SERVICE_NAME ของบัญชีบริการ ซึ่งในกรณีนี้คือ https://fleetengine.googleapis.com/ |
Iiat | การประทับเวลาเมื่อมีการสร้างโทเค็น ซึ่งระบุเป็นวินาทีที่ผ่านไปตั้งแต่เวลา 00:00:00 น. UTC ของวันที่ 1 มกราคม 1970 โปรดรอ 10 นาทีสำหรับการเอียง หากการประทับเวลาอยู่ในอดีตหรืออนาคตมากเกินไป เซิร์ฟเวอร์อาจรายงานข้อผิดพลาด |
exp | การประทับเวลาเมื่อโทเค็นหมดอายุ โดยระบุเป็นวินาทีที่ผ่านไปตั้งแต่ 00:00:00 น. UTC ของวันที่ 1 มกราคม 1970 คำขอจะล้มเหลวหากการประทับเวลานานกว่า 1 ชั่วโมงในอนาคต |
การให้สิทธิ์ | อาจมี "vehicleid" หรือ "tripid" ขึ้นอยู่กับกรณีการใช้งาน |
การสร้างโทเค็น JWT หมายถึงการลงชื่อโทเค็น ดูวิธีการและตัวอย่างโค้ดสำหรับการสร้างและการลงนาม JWT ได้ที่การให้สิทธิ์บัญชีบริการโดยไม่ใช้ OAuth จากนั้นคุณจะแนบโทเค็นที่ลงนามกับการเรียกใช้ gRPC หรือวิธีอื่นๆ ที่ใช้ในการเข้าถึง Fleet Engine ได้
การเรียกร้องสิทธิ์จาก JWT
เมื่อสร้างเพย์โหลด JWT ให้เพิ่มการอ้างสิทธิ์เพิ่มเติมในส่วนการให้สิทธิ์โดยกำหนดคีย์ vehicleid
หรือ tripid
เป็นค่าของรหัสยานพาหนะหรือรหัสการเดินทางที่จะเรียกใช้
Driver SDK จะใช้การอ้างสิทธิ์ vehicleid
เสมอ ไม่ว่าจะดำเนินการในขณะเดินทางหรือบนยานพาหนะ แบ็กเอนด์ของ Fleet Engine รับประกันว่าพาหนะเชื่อมโยงกับการเดินทางที่ขอก่อนทำการดัดแปลง
SDK ของผู้บริโภคจะใช้การอ้างสิทธิ์ tripid
เสมอ
ผู้ให้บริการเรียกรถหรือผู้ให้บริการควรใช้ vehicleid
หรือ tripid
พร้อม "*" เพื่อจับคู่ยานพาหนะและการเดินทางทั้งหมด โปรดทราบว่า JWT สามารถมีโทเค็นทั้งสองได้
แม้ว่าจะไม่จำเป็นก็ตาม ซึ่งอาจทำให้การติดตั้งใช้งานโทเค็นโทเค็นง่ายขึ้น
กรณีการใช้งานของ JWT
ต่อไปนี้เป็นตัวอย่างโทเค็นสำหรับเซิร์ฟเวอร์ผู้ให้บริการ
{
"alg": "RS256",
"typ": "JWT",
"kid": "private_key_id_of_provider_service_account"
}
.
{
"iss": "provider@yourgcpproject.iam.gserviceaccount.com",
"sub": "provider@yourgcpproject.iam.gserviceaccount.com",
"aud": "https://fleetengine.googleapis.com/",
"iat": 1511900000,
"exp": 1511903600,
"authorization": {
"vehicleid": "*",
"tripid": "*"
}
}
ข้อมูลต่อไปนี้จะแสดงโทเค็นตัวอย่างสําหรับแอปผู้บริโภค
{
"alg": "RS256",
"typ": "JWT",
"kid": "private_key_id_of_consumer_service_account"
}
.
{
"iss": "consumer@yourgcpproject.iam.gserviceaccount.com",
"sub": "consumer@yourgcpproject.iam.gserviceaccount.com",
"aud": "https://fleetengine.googleapis.com/",
"iat": 1511900000,
"exp": 1511903600,
"authorization": {
"tripid": "trip_54321"
}
}
ข้อมูลต่อไปนี้จะแสดงโทเค็นตัวอย่างสำหรับแอปไดรเวอร์
{
"alg": "RS256",
"typ": "JWT",
"kid": "private_key_id_of_driver_service_account"
}
.
{
"iss": "driver@yourgcpproject.iam.gserviceaccount.com",
"sub": "driver@yourgcpproject.iam.gserviceaccount.com",
"aud": "https://fleetengine.googleapis.com/",
"iat": 1511900000,
"exp": 1511903600,
"authorization": {
"vehicleid": "driver_12345"
}
}
- สำหรับช่อง
kid
ในส่วนหัว ให้ระบุรหัสคีย์ส่วนตัวของบัญชีบริการ คุณดูค่านี้ได้ในช่องprivate_key_id
ของไฟล์ JSON ของบัญชีบริการ - สำหรับช่อง
iss
และsub
ให้ระบุอีเมลของบัญชีบริการ คุณดูค่านี้ได้ในช่องclient_email
ของไฟล์ JSON ของบัญชีบริการ - สำหรับช่อง
aud
ให้ระบุ https://SERVICE_NAME/ - สำหรับช่อง
iat
ให้ใช้การประทับเวลาเมื่อสร้างโทเค็น ซึ่งระบุเป็นวินาทีที่ผ่านไปตั้งแต่เวลา 00:00:00 น. ตามเขตเวลา UTC ของวันที่ 1 มกราคม 1970 โปรดรอ 10 นาทีสำหรับการเอียง หากการประทับเวลาอยู่นานเกินไปในอดีตหรือในอนาคต เซิร์ฟเวอร์อาจรายงานข้อผิดพลาด - สำหรับช่อง
exp
ให้ใช้การประทับเวลาเมื่อโทเค็นหมดอายุ ซึ่งระบุเป็นวินาทีตั้งแต่ 00:00:00 น. ตามเขตเวลา UTC ของวันที่ 1 มกราคม 1970 ค่าสูงสุดที่อนุญาตคือiat
+ 3600
เมื่อลงนาม JWT เพื่อส่งไปยังอุปกรณ์เคลื่อนที่ โปรดตรวจสอบว่าได้ใช้บัญชีบริการสำหรับบทบาท Driver หรือ Consumer SDK มิเช่นนั้น อุปกรณ์เคลื่อนที่จะเปลี่ยนสถานะที่ไม่ควรจะมีได้
และในทำนองเดียวกัน เมื่อลงนามใน JWT ที่จะใช้สำหรับการโทรที่มีสิทธิ์ ให้ใช้บัญชีบริการที่มีบทบาทผู้ใช้ระดับสูง มิฉะนั้นการดำเนินการจะไม่สำเร็จ
การสร้าง JWT สำหรับการทดสอบ
การสร้างโทเค็นจากเทอร์มินัลอาจมีประโยชน์เมื่อทำการทดสอบ
บัญชีผู้ใช้ของคุณต้องมีบทบาทผู้สร้างโทเค็นบัญชีบริการจึงจะทำตามขั้นตอนเหล่านี้ได้
gcloud projects add-iam-policy-binding project-id \
--member=user:my-user@example.com \
--role=roles/iam.serviceAccountTokenCreator
สร้างไฟล์ใหม่ชื่อ unsigned_token.json
ที่มีเนื้อหาด้านล่าง พร็อพเพอร์ตี้ iat
คือเวลาปัจจุบันโดยมีหน่วยเป็นวินาทีหลังจาก Epoch ซึ่งดึงข้อมูลได้โดยการเรียกใช้ date +%s
ในเทอร์มินัล พร็อพเพอร์ตี้ exp
คือเวลาหมดอายุในหน่วยวินาทีหลังจากเหตุการณ์ Epoch ซึ่งคํานวณได้โดยการเพิ่ม 3600 ลงใน iat
เวลาหมดอายุต้องไม่เกิน 1 ชั่วโมงในอนาคต
{ "aud": "https://fleetengine.googleapis.com/", "iss": "super-user-service-account@project-id.iam.gserviceaccount.com", "sub": "super-user-service-account@project-id.iam.gserviceaccount.com", "iat": iat, "exp": exp, "authorization": { "vehicleid": "*", "tripid": "*" } }
จากนั้นเรียกใช้คำสั่ง gcloud ต่อไปนี้เพื่อลงนามโทเค็นในนามของบัญชีบริการผู้ใช้ขั้นสูง
gcloud beta iam service-accounts sign-jwt --iam-account=super-user-service-account@project-id.iam.gserviceaccount.com unsigned_token.json signed_token.jwt
ตอนนี้ระบบควรจัดเก็บ JWT ที่เข้ารหัส Base64 ที่มีการรับรองไว้ในไฟล์ signed_token.jwt
แล้ว โทเค็นจะใช้ได้เป็นเวลา 1 ชั่วโมง
ตอนนี้คุณทดสอบโทเค็นได้โดยการเรียกใช้คำสั่ง curl
กับปลายทาง REST ของรายการยานพาหนะ:
curl -X GET "https://fleetengine.googleapis.com/v1/providers/project-id/vehicles" -H "Authorization: Bearer $(cat signed_token.jwt)"
ยานพาหนะและวงจร
ยานพาหนะคือเอนทิตีที่แสดงถึงคู่คนขับกับพาหนะ ปัจจุบันระบบไม่สามารถติดตามคนขับและยานพาหนะแยกกันได้ Rideshare หรือผู้ให้บริการนำส่งจะสร้างยานพาหนะโดยใช้รหัสผู้ให้บริการ (ซึ่งต้องเหมือนกับรหัสโปรเจ็กต์ของโปรเจ็กต์ Google Cloud ที่มีบัญชีบริการที่ใช้เรียก Fleet Engine API) และรหัสยานพาหนะที่ผู้บริการนำส่งรถหรือผู้ให้บริการนำส่งเป็นเจ้าของ
ระบบจะลบยานพาหนะที่ไม่ได้รับการอัปเดตผ่าน UpdateVehicle
หลังจากผ่านไป 7 วันโดยอัตโนมัติ และจะทำเครื่องหมายการเดินทางที่กำหนด (หากมี) เป็น "ยังไม่ได้มอบหมาย" วิธีที่แนะนำสำหรับการทำให้ยานพาหนะพร้อมใช้งานใน Fleet Engine อยู่เสมอคือการอัปเดตตำแหน่งในช่วงเวลาที่สม่ำเสมอ การอัปเดตช่องอื่นๆ ส่วนใหญ่ในเอนทิตี Vehicle
จะยืดอายุการใช้งานด้วย หากค่าในช่องใหม่แตกต่างจากช่องที่มีอยู่
หมายเหตุ: ช่องบางช่องในเอนทิตี Vehicle
เช่น device_settings
เป็นเพียงข้อมูลการแก้ไขข้อบกพร่องเท่านั้นซึ่งไม่มีอยู่ใน Fleet Engine การอัปเดตหน้าเหล่านั้นไม่ได้ช่วยยืดอายุการใช้งานของเอนทิตี Vehicle
มีข้อผิดพลาดเกิดขึ้นในการเรียก CreateVehicle
ด้วยคู่รหัสผู้ให้บริการ/รหัสยานพาหนะที่มีอยู่แล้ว กรณีของยานพาหนะที่ไม่ได้อัปเดตบ่อยคุณสามารถจัดการได้ 2 วิธี ได้แก่ การเรียกใช้ CreateVehicle
ด้วยการจับคู่รหัสผู้ให้บริการกับรหัสยานพาหนะที่คาดไว้ และทิ้งข้อผิดพลาดหากมียานพาหนะอยู่แล้ว หรือการเรียกใช้ CreateVehicle
หลังจาก UpdateVehicle
ส่งคืนพร้อมข้อผิดพลาด NOT_FOUND
การอัปเดตตำแหน่งของรถ
เพื่อประสิทธิภาพที่ดีที่สุดเมื่อใช้ Fleet Engine ให้สตรีมการอัปเดตตำแหน่งของรถ ใช้วิธีใดวิธีหนึ่งต่อไปนี้เพื่อแจ้งการอัปเดต
- ใช้ Driver SDK - Android, iOS -- ตัวเลือกที่ง่ายที่สุด
- ใช้โค้ดที่กำหนดเอง ซึ่งมีประโยชน์หากมีการส่งต่อตำแหน่งผ่านแบ็กเอนด์ของคุณ หรือหากคุณใช้อุปกรณ์อื่นที่ไม่ใช่ Android หรือ iOS
ประเภทยานพาหนะ
เอนทิตียานพาหนะมีช่องที่ต้องกรอก VehicleType
ซึ่งมี enum ของ Category
ซึ่งระบุได้เป็น AUTO
, TAXI
, TRUCK
,
TWO_WHEELER
, BICYCLE
หรือ PEDESTRIAN
ประเภทยานพาหนะเป็นเกณฑ์ตัวกรองใน SearchVehicles
และ ListVehicles
ได้
การกำหนดเส้นทางทั้งหมดสำหรับยานพาหนะจะใช้ RouteTravelMode
ที่เกี่ยวข้องหากตั้งค่าหมวดหมู่เป็น AUTO
, TWO_WHEELER
, BICYCLE
หรือ PEDESTRIAN
หากตั้งค่าหมวดหมู่เป็น TAXI
หรือ TRUCK
ระบบจะถือว่าการกำหนดเส้นทางเหมือนกับโหมด AUTO
แอตทริบิวต์ของยานพาหนะ
เอนทิตียานพาหนะมีช่องที่ซ้ำของ VehicleAttribute
Fleet Engine ไม่ได้ตีความแอตทริบิวต์เหล่านี้ SearchVehicles
API มีฟิลด์ที่กำหนดให้ Vehicles
ที่ตรงกันต้องมีแอตทริบิวต์ที่รวมอยู่ทั้งหมดซึ่งตั้งเป็นค่าที่ระบุ
โปรดทราบว่าช่องแอตทริบิวต์เป็นส่วนเพิ่มเติมจากช่องอื่นๆ ที่รองรับในข้อความ Vehicle
เช่น vehicle_type
และ supported_trip_types
จุดอ้างอิงที่เหลืออยู่ของยานพาหนะ
เอนทิตียานพาหนะมีช่องที่ซ้ำของ TripWaypoint
(RPC | REST)
ซึ่งเรียกว่า waypoints
(RPC | REST)
ฟิลด์นี้จะรวมจุดอ้างอิงที่เหลือในเส้นทาง ตามลำดับที่พาหนะไปถึงจุดเหล่านั้น Fleet Engine จะคำนวณช่องนี้เมื่อมีการกำหนดการเดินทางให้กับรถ และอัปเดตการเดินทางดังกล่าวเมื่อการเดินทางเปลี่ยนสถานะ
จุดอ้างอิงเหล่านี้สามารถระบุได้จากฟิลด์ TripId
และฟิลด์ WaypointType
การขยายเกณฑ์การมีสิทธิ์ของยานพาหนะสำหรับการจับคู่
โดยปกติแล้ว บริการของบริการเรียกรถหรือผู้ให้บริการจัดส่งจะรับผิดชอบในการจับคู่คำขอเดินทางไปยังยานพาหนะ บริการนี้สามารถใช้แอตทริบิวต์ยานพาหนะ
เพื่อรวมยานพาหนะในการค้นหาจำนวนมาก ตัวอย่างเช่น ผู้ให้บริการสามารถใช้ชุดแอตทริบิวต์ที่สอดคล้องกับระดับของสิทธิพิเศษหรือความสามารถที่ยานพาหนะมีให้ ตัวอย่างเช่น ระดับ 3 อาจเป็นชุดแอตทริบิวต์ที่มีค่าบูลีน ได้แก่ is_bronze_level
, is_silver_level
และ is_gold_level
ยานพาหนะ
มีสิทธิ์แสดงบนทั้ง 3 ประเภท เมื่อ Fleet Engine ได้รับคำขอสำหรับการเดินทางที่ต้องใช้ความสามารถระดับเงิน การค้นหาจะรวมยานพาหนะดังกล่าวไว้ด้วย
การใช้แอตทริบิวต์ลักษณะนี้รวมถึงยานพาหนะที่มีความสามารถที่หลากหลาย
อัปเดตแอตทริบิวต์ยานพาหนะได้ 2 วิธี วิธีแรกคือ API UpdateVehicle
เมื่อใช้ API นี้ แอตทริบิวต์ของยานพาหนะทั้งชุดจะได้รับการตั้งค่าเป็นค่า เป็นไปไม่ได้ที่จะอัปเดตเพียงแอตทริบิวต์เดียว
อีกวิธีหนึ่งคือ API ของ UpdateVehicleAttributes
วิธีนี้จะทำให้ระบบอัปเดตเฉพาะแอตทริบิวต์เท่านั้น ระบบจะกำหนดแอตทริบิวต์ที่รวมอยู่ในคำขอเป็นค่าใหม่ หรือมีการเพิ่มแอตทริบิวต์ที่ไม่ระบุ จะไม่มีการเปลี่ยนแปลง
วิธีการ: สร้างยานพาหนะ
คุณต้องสร้างเอนทิตี Vehicle
สำหรับยานพาหนะแต่ละคันที่จะติดตามภายในกลุ่ม
ใช้ปลายทาง CreateVehicle
กับ CreateVehicleRequest
เพื่อสร้างยานพาหนะ
provider_id
ของ Vehicle
ต้องเป็นรหัสโปรเจ็กต์ (เช่น my-on-demand-project) ของโปรเจ็กต์ Google Cloud ที่มีบัญชีบริการที่จะใช้เรียก Fleet Engine โปรดทราบว่าแม้บัญชีบริการหลายบัญชีอาจเข้าถึง Fleet Engine สำหรับ Rideshare หรือผู้ให้บริการนำส่งรายเดียว แต่ขณะนี้ Fleet Engine ยังไม่รองรับบัญชีบริการจากโปรเจ็กต์ Google Cloud หลายโปรเจ็กต์ที่เข้าถึง Vehicles
เดียวกัน
คุณสร้าง Vehicle
ได้ในสถานะ OFFLINE
หรือ ONLINE
หากสร้าง ONLINE
ระบบอาจแสดงผล URL นั้นทันทีตามคำค้นหา SearchVehicles
ระบบอาจรวม last_location
เริ่มต้นในการโทร CreateVehicle
แม้ว่าได้รับอนุญาต คุณไม่ควรสร้าง Vehicle
ในสถานะ ONLINE
โดยไม่มี last_location
ดูรายละเอียดเกี่ยวกับช่องประเภทยานพาหนะได้ที่ประเภทยานพาหนะ
ดูรายละเอียดเกี่ยวกับ ช่องแอตทริบิวต์ได้ที่แอตทริบิวต์ยานพาหนะ
ค่าที่แสดงผลจาก CreateVehicle
คือเอนทิตี Vehicle
ที่สร้างขึ้น
ตัวอย่าง
Shell
curl -X POST \
"https://fleetengine.googleapis.com/v1/providers/project-id/vehicles?vehicleId=vid-8241890" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
--data-binary @- << EOM
{
"vehicleState": "OFFLINE",
"supportedTripTypes": ["EXCLUSIVE"],
"maximumCapacity": 4,
"vehicleType": {"category": "AUTO"},
"attributes": [{"key": "on_trip", "value": "false"}]
}
EOM
ดูข้อมูลอ้างอิง providers.vehicles.create
Java
static final String PROJECT_ID = "project-id";
VehicleServiceBlockingStub vehicleService =
VehicleService.newBlockingStub(channel);
String parent = "providers/" + PROJECT_ID;
Vehicle vehicle = Vehicle.newBuilder()
.setVehicleState(VehicleState.OFFLINE) // Initial state
.addSupportedTripTypes(TripType.EXCLUSIVE)
.setMaximumCapacity(4)
.setVehicleType(VehicleType.newBuilder().setCategory(VehicleType.Category.AUTO))
.addAttributes(VehicleAttribute.newBuilder()
.setKey("on_trip").setValue("false")) // Opaque to the Fleet Engine
// Add .setBackToBackEnabled(true) to make this vehicle eligible for trip
// matching while even if it is on a trip. By default this is disabled.
.build();
CreateVehicleRequest createVehicleRequest =
CreateVehicleRequest.newBuilder() // no need for the header
.setParent(parent)
.setVehicleId("vid-8241890") // Vehicle ID assigned by Rideshare or Delivery Provider
.setVehicle(vehicle) // Initial state
.build();
// In this case, the Vehicle is being created in the OFFLINE state and
// no initial position is being provided. When the Driver App checks
// in with the Rideshare or Delivery Provider, the state can be set to ONLINE and
// the Driver App will update the Vehicle Location.
try {
Vehicle createdVehicle =
vehicleService.createVehicle(createVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case ALREADY_EXISTS:
break;
case PERMISSION_DENIED:
break;
}
return;
}
// If no Exception, Vehicle created successfully.
บันทึก Google Cloud Platform สำหรับการสร้างยานพาหนะ
Fleet Engine API จะเขียนรายการบันทึกผ่านบันทึกของ Google Cloud Platform เมื่อได้รับการเรียกใช้ไปยังปลายทาง CreateVehicle
รายการบันทึกจะมีข้อมูลเกี่ยวกับค่าในคำขอ CreateVehicle
หากการโทรประสบความสำเร็จ จะมีข้อมูลเกี่ยวกับ Vehicle
ที่ส่งคืนด้วย
Shell
gcloud --project=project-id logging read --freshness=1h '
jsonPayload.request.vehicleId="vid-8241890"
jsonPayload.@type="type.googleapis.com/maps.fleetengine.v1.CreateVehicleLog"
'
ควรพิมพ์ระเบียนในลักษณะต่อไปนี้
---
insertId: c2cf4d3a180251c1bdb892137c14f022
jsonPayload:
'@type': type.googleapis.com/maps.fleetengine.v1.CreateVehicleLog
request:
vehicle:
attributes:
- key: on_trip
value: 'false'
maximumCapacity: 4
state: VEHICLE_STATE_OFFLINE
supportedTrips:
- EXCLUSIVE_TRIP
vehicleType:
vehicleCategory: AUTO
vehicleId: vid-8241890
response:
attributes:
- key: on_trip
value: 'false'
availableCapacity: 4
currentRouteSegmentHandle: AdSiwAwCO9gZ7Pw5UZZimOXOo41cJTjg/r3SuwVPQmuuaV0sU3+3UCY+z53Cl9i6mWHLoCKbBt9Vsj5PMRgOJ8zX
maximumCapacity: 4
name: providers/project-id/vehicles/vid-8241890
state: VEHICLE_STATE_OFFLINE
supportedTrips:
- EXCLUSIVE_TRIP
vehicleType:
vehicleCategory: AUTO
labels:
vehicle_id: vid-8241890
logName: projects/project-id/logs/fleetengine.googleapis.com%2Fcreate_vehicle
receiveTimestamp: '2021-09-22T03:25:16.361159871Z'
resource:
labels:
location: global
resource_container: projects/project-id
type: fleetengine.googleapis.com/Fleet
timestamp: '2021-09-22T03:25:15.724998Z'
การแจ้งเตือน Cloud Pub/Sub สำหรับการสร้างยานพาหนะ
Fleet Engine API จะเผยแพร่การแจ้งเตือนผ่าน Cloud Pub/Sub เมื่อมีการสร้างยานพาหนะใหม่ หากต้องการรับการแจ้งเตือนเหล่านี้ โปรดทำตามวิธีการที่นี่
วิธีการ: อัปเดตตำแหน่งของรถ
หากไม่ได้ใช้ Driver SDK เพื่ออัปเดตตำแหน่งของรถ คุณโทรหา Fleet Engine ได้โดยตรงพร้อมระบุตำแหน่งของรถ สำหรับยานพาหนะที่ใช้งานอยู่ Fleet Engine คาดว่าจะอัปเดตตำแหน่งอย่างน้อย 1 ครั้งทุกนาทีและสูงสุด 1 ครั้งทุก 5 วินาที การอัปเดตเหล่านี้ต้องการเฉพาะผู้ใช้ Fleet Engine Driver SDK
ตัวอย่าง
Shell
curl -X PUT \
"https://fleetengine.googleapis.com/v1/providers/project-id/vehicles/vid-8241890?updateMask=last_location" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
--data-binary @- << EOM
{
"supplementalLocation": {"latitude": 12.1, "longitude": 14.5},
"supplementalLocationTime": "$(date -u --iso-8601=seconds)",
"supplementalLocationSensor": "CUSTOMER_SUPPLIED_LOCATION",
"supplementalLocationAccuracy": 15
}
EOM
ดูข้อมูลอ้างอิง providers.vehicles.update
Java
static final String PROJECT_ID = "project-id";
static final String VEHICLE_ID = "vid-8241890";
VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);
String vehicleName = "providers/" + PROJECT_ID + "/vehicles/" + VEHICLE_ID;
Vehicle updatedVehicle = Vehicle.newBuilder()
.setLastLocation(VehicleLocation.newBuilder()
.setSupplementalLocation(LatLng.newBuilder()
.setLatitude(37.3382)
.setLongitude(121.8863))
.setSupplementalLocationTime(now())
.setSupplementalLocationSensor(LocationSensor.CUSTOMER_SUPPLIED_LOCATION)
.setSupplementalLocationAccuracy(DoubleValue.of(15.0))) // Optional)
.build();
UpdateVehicleRequest updateVehicleRequest = UpdateVehicleRequest.newBuilder()
.setName(vehicleName)
.setVehicle(updatedVehicle)
.setUpdateMask(FieldMask.newBuilder()
.addPaths("last_location"))
.build();
try {
Vehicle updatedVehicle =
vehicleService.updateVehicle(updateVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
// Most implementations will call CreateVehicle in this case
break;
case PERMISSION_DENIED:
break;
}
return;
}
// If no Exception, Vehicle updated successfully.
วิธีการ: อัปเดตช่องยานพาหนะอื่นๆ
การอัปเดตแอตทริบิวต์อื่นๆ ของสถานะของยานพาหนะจะเกิดขึ้นน้อยกว่าการอัปเดตตำแหน่ง การอัปเดตแอตทริบิวต์อื่นที่ไม่ใช่ last_location
ต้องใช้สิทธิ์ของผู้ใช้ขั้นสูงของ Fleet Engine
UpdateVehicleRequest
จะมี update_mask
เพื่อระบุว่าควรอัปเดตช่องใด ลักษณะการทำงานของช่องนี้เหมือนกับในเอกสาร Protobuf สำหรับมาสก์ฟิลด์
ตามที่ระบุไว้ในแอตทริบิวต์ยานพาหนะ การอัปเดตช่อง attributes
จะต้องมีการเขียนแอตทริบิวต์ทั้งหมดไว้ คุณจะอัปเดตค่าของคู่คีย์-ค่าเพียงคู่เดียวในการเรียกใช้ UpdateVehicle
ไม่ได้ หากต้องการอัปเดตค่าของแอตทริบิวต์ที่เจาะจง ให้ใช้ API ของ UpdateVehicleAttributes
ตัวอย่าง
ตัวอย่างนี้เปิดใช้ back_to_back
Shell
curl -X PUT \
"https://fleetengine.googleapis.com/v1/providers/project-id/vehicles/vid-8241890?updateMask=vehicle_state,attributes,back_to_back_enabled" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
--data-binary @- << EOM
{
"vehicleState": "ONLINE",
"attributes": [
{"key": "on_trip", "value": "true"},
{"key": "cash_only", "value": "false"}
],
"backToBackEnabled": true
}
EOM
ดูข้อมูลอ้างอิง providers.vehicles.update
Java
static final String PROJECT_ID = "project-id";
static final String VEHICLE_ID = "vid-8241890";
VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);
String vehicleName = "providers/" + PROJECT_ID + "/vehicles/" + VEHICLE_ID;
Vehicle updatedVehicle = Vehicle.newBuilder()
.setVehicleState(VehicleState.ONLINE)
.addAllAttributes(ImmutableList.of(
VehicleAttribute.newBuilder().setKey("on_trip").setValue("true").build(),
VehicleAttribute.newBuilder().setKey("cash_only").setValue("false").build()))
.setBackToBackEnabled(true)
.build();
UpdateVehicleRequest updateVehicleRequest = UpdateVehicleRequest.newBuilder()
.setName(vehicleName)
.setVehicle(updatedVehicle)
.setUpdateMask(FieldMask.newBuilder()
.addPaths("vehicle_state")
.addPaths("attributes")
.addPaths("back_to_back_enabled"))
.build();
// Attributes and vehicle state are being updated, so both are
// included in the field mask. Note that of on_trip were
// not being updated, but rather cash_only was being changed,
// the desired value of "on_trip" would still need to be written
// as the attributes are completely replaced in an update operation.
try {
Vehicle updatedVehicle =
vehicleService.updateVehicle(updateVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
// Most implementations will call CreateVehicle in this case
break;
case PERMISSION_DENIED:
break;
}
return;
}
// If no Exception, Vehicle updated successfully.
บันทึกของ Google Cloud Platform สำหรับการอัปเดตยานพาหนะ
Fleet Engine API จะเขียนรายการบันทึกผ่านบันทึกของ Google Cloud Platform เมื่อได้รับการเรียกใช้ไปยังปลายทาง UpdateVehicle
รายการบันทึกจะมีข้อมูลเกี่ยวกับค่าในคำขอ UpdateVehicle
หากการโทรประสบความสำเร็จ จะมีข้อมูลเกี่ยวกับ Vehicle
ที่ส่งคืนด้วย
Shell
gcloud --project=project-id logging read --freshness=1h '
jsonPayload.request.vehicleId="vid-8241890"
jsonPayload.@type="type.googleapis.com/maps.fleetengine.v1.UpdateVehicleLog"
'
การแจ้งเตือน Cloud Pub/Sub สำหรับการอัปเดตยานพาหนะ
Fleet Engine API เผยแพร่การแจ้งเตือนผ่าน Cloud Pub/Sub เมื่อมีการอัปเดตยานพาหนะที่มีอยู่ หากต้องการรับการแจ้งเตือนเหล่านี้ โปรดทำตามวิธีการที่นี่
วิธีการ: ค้นหายานพาหนะ
Fleet Engine รองรับการค้นหายานพาหนะ SearchVehicles
API ช่วยคุณค้นหาคนขับรถในบริเวณใกล้เคียงที่เหมาะที่สุดกับงาน เช่น การให้บริการเรียกรถหรือคำขอส่งรถ SearchVehicles
API จะแสดงรายการนักขับที่ได้รับการจัดอันดับที่ตรงกับแอตทริบิวต์ของงานกับแอตทริบิวต์ของยานพาหนะในกองยานพาหนะของคุณ ดูข้อมูลเพิ่มเติมได้ที่การค้นหาผู้ขับขี่ที่อยู่ใกล้เคียง
ตัวอย่าง
เมื่อค้นหายานพาหนะที่ใช้ได้ Fleet Engine จะยกเว้นยานพาหนะในการเดินทางที่ดำเนินอยู่โดยค่าเริ่มต้น บริการของบริการเรียกรถหรือผู้ให้บริการจัดส่งต้องรวมบริการเหล่านั้นไว้ในคำขอการค้นหาอย่างชัดเจน ตัวอย่างต่อไปนี้แสดงวิธีรวมยานพาหนะเหล่านั้นในการค้นหายานพาหนะที่ตรงกับการเดินทางจากศูนย์การค้า Grand Indonesia East Mall ไปยังศูนย์ประชุม Balai Sidang Jakarta Convention Center
Shell
ก่อนอื่นให้อัปเดตตำแหน่งของยานพาหนะที่เราสร้างในขั้นตอนก่อนหน้าเพื่อให้มีสิทธิ์ ในความเป็นจริง จะเป็นการใช้ Driver SDK ที่ทำงานบนอุปกรณ์ Android หรือ iOS ในรถ
curl -X PUT \
"https://fleetengine.googleapis.com/v1/providers/project-id/vehicles/vid-8241890?updateMask=last_location,attributes" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
--data-binary @- << EOM
{
"lastLocation": {
"updateTime": "$( date -u +"%Y-%m-%dT%H:%M:%SZ" )",
"location": {
"latitude": "-6.195139",
"longitude": "106.820826"
}
},
"attributes": [{"key": "on_trip", "value": "false"}]
}
EOM
การค้นหาควรให้ผลลัพธ์เป็นยานพาหนะดังกล่าวเป็นอย่างน้อย
curl -X POST \
"https://fleetengine.googleapis.com/v1/providers/project-id/vehicles:search" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
--data-binary @- << EOM
{
"pickupPoint": {
"point": {"latitude": "-6.195139", "longitude": "106.820826"}
},
"dropoffPoint": {
"point": {"latitude": "-6.1275", "longitude": "106.6537"}
},
"pickupRadiusMeters": 2000,
"count": 10,
"minimumCapacity": 2,
"tripTypes": ["EXCLUSIVE"],
"vehicleTypes": [{"category": "AUTO"}],
"filter": "attributes.on_trip=\"false\"",
"orderBy": "PICKUP_POINT_ETA",
"includeBackToBack": true
}
EOM
ดูข้อมูลอ้างอิง providers.vehicles.search
Java
static final String PROJECT_ID = "project-id";
VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);
String parent = "providers/" + PROJECT_ID;
SearchVehiclesRequest searchVehiclesRequest = SearchVehiclesRequest.newBuilder()
.setParent(parent)
.setPickupPoint( // Grand Indonesia East Mall
TerminalLocation.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
.setDropoffPoint( // Balai Sidang Jakarta Convention Center
TerminalLocation.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.213796).setLongitude(106.807195)))
.setPickupRadiusMeters(2000)
.setCount(10)
.setMinimumCapacity(2)
.addTripTypes(TripType.EXCLUSIVE)
.addVehicleTypes(VehicleType.newBuilder().setCategory(VehicleType.Category.AUTO))
.setFilter("attributes.on_trip=\"false\"")
.setOrderBy(VehicleMatchOrder.PICKUP_POINT_ETA)
.setIncludeBackToBack(true) // Fleet Engine includes vehicles that are en route.
.build();
// Error handling
// If matches are returned and the authentication passed, the request completed
// successfully
try {
SearchVehiclesResponse searchVehiclesResponse =
vehicleService.searchVehicles(searchVehiclesRequest);
// Search results: Each vehicle match contains a vehicle entity and information
// about the distance and ETA to the pickup point and dropoff point.
List<VehicleMatch> vehicleMatches = searchVehiclesResponse.getMatchesList();
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
การค้นหาการกรองยานพาหนะ
SearchVehicles
และ ListVehicles
รองรับการกรองในแอตทริบิวต์ยานพาหนะ
โดยใช้คำค้นหาตัวกรอง ดูตัวอย่างไวยากรณ์การค้นหาตัวกรองได้ที่ AIP-160
โปรดทราบว่าการค้นหาตัวกรองรองรับเฉพาะการกรองแอตทริบิวต์ยานพาหนะเท่านั้น และใช้กับฟิลด์อื่นๆ ไม่ได้ การค้นหาของตัวกรองทำหน้าที่เป็นอนุประโยค AND
ที่มีข้อจำกัดอื่นๆ เช่น minimum_capacity
หรือ vehicle_types
ใน SearchVehiclesRequest
วิธีการ: แสดงรายการยานพาหนะ
SearchVehicles
ได้รับการเพิ่มประสิทธิภาพให้การค้นหายานพาหนะไม่กี่คันที่อยู่ในลำดับสูงได้อย่างรวดเร็วมาก และจะใช้เพื่อค้นหาผู้ขับขี่ที่อยู่ใกล้เคียงที่เหมาะกับงานมากที่สุด อย่างไรก็ตาม บางครั้งคุณอาจต้องค้นหายานพาหนะทั้งหมดที่เป็นไปตามเกณฑ์ แม้ว่าจะจำเป็นต้องดูหน้าผลลัพธ์ก็ตาม ListVehicles
ออกแบบมาสำหรับกรณีการใช้งานดังกล่าว
ListVehicles
API ช่วยให้คุณค้นหายานพาหนะทั้งหมดที่เป็นไปตามตัวเลือกคำขอบางรายการได้ ListVehicles
API จะแสดงรายการยานพาหนะในโปรเจ็กต์ที่มีเลขหน้าซึ่งตรงกับข้อกำหนดบางรายการ
หากต้องการกรองแอตทริบิวต์ยานพาหนะ โปรดดูคำค้นหาการกรองยานพาหนะ
ตัวอย่าง
ตัวอย่างนี้จะทำการกรอง vehicle_type
และแอตทริบิวต์โดยใช้สตริง filter
Shell
curl -X POST \
"https://fleetengine.googleapis.com/v1/providers/project-id/vehicles:list" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
--data-binary @- << EOM
{
"vehicleTypes": [{"category": "AUTO"}],
"filter": "attributes.on_trip=\"false\"",
}
EOM
ดูข้อมูลอ้างอิง providers.vehicles.list
Java
static final String PROJECT_ID = "project-id";
VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);
String parent = "providers/" + PROJECT_ID;
ListVehiclesRequest listVehiclesRequest = ListVehiclesRequest.newBuilder()
.setParent(parent)
.addTripTypes(TripType.EXCLUSIVE)
.addVehicleTypes(VehicleType.newBuilder().setCategory(VehicleType.Category.AUTO))
.setFilter("attributes.on_trip=\"false\"")
.setIncludeBackToBack(true) // Fleet Engine includes vehicles that are en route.
.build();
// Error handling
// If matches are returned and the authentication passed, the request completed
// successfully
try {
ListVehiclesResponse listVehiclesResponse =
vehicleService.listVehicles(listVehiclesRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
การเดินทางและวงจรชีวิต
Trip API และวงจรคล้ายกับยานพาหนะ API และวงจร
ผู้ให้บริการ Rideshare มีหน้าที่สร้างการเดินทางโดยใช้อินเทอร์เฟซ Fleet Engine Fleet Engine มีทั้งบริการ RPC,
TripService
และทรัพยากร REST provider.trips
อินเทอร์เฟซเหล่านี้ช่วยให้สร้างเอนทิตี Trip คำขอข้อมูล ฟังก์ชันการค้นหา และความสามารถในการอัปเดต
Trip
มีช่องสถานะสำหรับติดตามความคืบหน้าในวงจร
ค่าจะย้ายจาก NEW
ไปยัง COMPLETE
บวก CANCELED
และ UNKNOWN_TRIP_STATUS
โปรดดู trip_status
สำหรับ RPC
หรือ TripStatus สำหรับ REST
NEW
ENROUTE_TO_PICKUP
ARRIVED_AT_PICKUP
ENROUTE_TO_INTERMEDIATE_DESTINATION
ARRIVED_AT_INTERMEDIATE_DESTINATION
ENROUTE_TO_DROPOFF
COMPLETE
บริการของคุณสามารถอัปเดตการเดินทางไปยัง CANCELED
จากสถานะใดก็ได้เหล่านี้
เมื่อบริการสร้างการเดินทาง เครื่องมือจะตั้งค่าสถานะเป็น NEW
คุณจะป้อน vehicle_id
หรือไม่ก็ได้ เช่นเดียวกับยานพาหนะ บริการจะลบการเดินทางที่ยังไม่มีการมอบหมายโดยอัตโนมัติหลังจาก 7 วันโดยไม่มีการอัปเดต หากบริการพยายามสร้างการเดินทางด้วยรหัสที่มีอยู่แล้ว ระบบจะแสดงข้อผิดพลาด การเดินทางจะถือว่า "ใช้งานอยู่"
หากการเดินทางอยู่ในสถานะอื่นที่ไม่ใช่ COMPLETE
หรือ CANCELED
ความแตกต่างนี้สําคัญในช่อง active_trips
ในเอนทิตียานพาหนะและ SearchTripsRequest
บริการจะเปลี่ยน vehicle_id
ที่กำหนดให้กับการเดินทางได้เท่านั้นเมื่อการเดินทางทำงานอยู่ ตัวอย่างเช่น คุณจะดำเนินการนี้เมื่อคนขับยกเลิกการเดินทางในระหว่าง
เส้นทางและมีการเปลี่ยนการเดินทางไปยังรถคันอื่น
สถานะมีความสำคัญเมื่อใช้การสนับสนุนการเดินทางกลับไป การรองรับนี้จะช่วยให้ผู้ให้บริการกำหนดเส้นทางใหม่ไปยังยานพาหนะในขณะที่ยานพาหนะนั้นอยู่ระหว่างการเดินทางได้ รหัสสำหรับการสร้างการเดินทางขากลับจะเหมือนกับการเดินทางครั้งเดียว และใช้รหัสพาหนะเดียวกัน Fleet Engine จะเพิ่มต้นทางและจุดหมายของการเดินทางใหม่ไปยังจุดอ้างอิงของยานพาหนะ ดูข้อมูลเพิ่มเติมเกี่ยวกับการเดินทางไป-กลับได้ที่สร้างการเดินทางหลายจุดระหว่างทาง
จุดอ้างอิงที่เหลือของการเดินทาง
เอนทิตีการเดินทางมีช่อง TripWaypoint
ที่ซ้ำ (RPC | REST) ซึ่งเรียกว่า remainingWaypoints
(RPC | REST)
ช่องนี้ระบุจุดอ้างอิงทั้งหมดที่ยานพาหนะจะต้องเดินทางตามลำดับก่อนถึงจุดลงจอดสุดท้ายของการเดินทางนี้ ระบบจะคำนวณจาก
จุดอ้างอิงที่เหลือของยานพาหนะ
ในกรณีการใช้งาน "กลับไปขาไป" และ "การโดยสารรถร่วมกัน" รายการนี้มีจุดอ้างอิงจากการเดินทางอื่นๆ ที่จะข้ามผ่านก่อนการเดินทางนี้ แต่ไม่รวมจุดอ้างอิงหลังจากการเดินทางครั้งนี้ จุดอ้างอิงในรายการระบุได้ด้วย TripId
และ WaypointType
ความสัมพันธ์ระหว่างสถานะการเดินทางกับจุดอ้างอิงที่เหลืออยู่ของยานพาหนะ
ระบบจะอัปเดตจุดอ้างอิงที่เหลือของยานพาหนะ (RPC | REST) เมื่อ Fleet Engine ได้รับคำขอเปลี่ยนสถานะการเดินทาง ระบบจะนำจุดอ้างอิงก่อนหน้าออกจากรายการจุดอ้างอิงที่เหลือของยานพาหนะเมื่อ tripStatus
(RPC | REST) เปลี่ยนจากสถานะอื่นเป็น ENROUTE_TO_XXX นั่นก็คือ เมื่อสถานะการเดินทางเปลี่ยนจาก ENROUTE_TO_PICKUP เป็น ARRIVED_AT_PICKUP จุดรับของการเดินทางจะยังคงอยู่ในรายการจุดอ้างอิงที่เหลืออยู่ของยานพาหนะ แต่เมื่อสถานะการเดินทางเปลี่ยนเป็น ENROUTE_TO_INTERMEDIATE_DESTINATION หรือ ENROUTE_TO_DROPOFF จุดรับของการเดินทางจะถูกนำออกจากจุดหมายที่เหลืออยู่ของรถ
คือเหมือนกันสำหรับ ARRIVED_AT_INTERMEDIATE_DESTINATION และ ENROUTE_TO_INTERMDEDIATE_DESTINATION เมื่อ ARRIVED_AT_INTERMEDIATE_DESTINATION จุดหมายกลางปัจจุบันจะไม่ถูกนำออกจากรายการจุดอ้างอิงที่เหลืออยู่ของ ยานพาหนะ จนกว่ายานพาหนะจะรายงานว่ามีการเปลี่ยนเส้นทางไปยังจุดอ้างอิงถัดไป
เมื่อสถานะการเดินทางเปลี่ยนเป็น COMPLETED
จะไม่มีจุดอ้างอิงจากการเดินทางนี้ในรายการจุดอ้างอิงที่เหลืออยู่ของยานพาหนะ
วิธีการ: สร้างการเดินทาง
ต้องสร้างเอนทิตี Trip
เพื่อให้ระบบติดตามคำขอการเดินทางแต่ละรายการและจับคู่กับยานพาหนะในกองยาน ใช้ปลายทาง CreateTrip
กับ CreateTripRequest
เพื่อสร้างการเดินทาง
โดยต้องมีแอตทริบิวต์ต่อไปนี้เพื่อสร้างการเดินทาง
parent
- สตริงที่มีรหัสผู้ให้บริการซึ่งสร้างขึ้นเมื่อสร้างโปรเจ็กต์ Google Cloudtrip_id
- สตริงที่สร้างโดยผู้ให้บริการบริการร่วมเดินทางtrip
- คอนเทนเนอร์ที่มีข้อมูลเมตาพื้นฐานที่อธิบายการเดินทางtrip_type
- enum เพื่อบอกว่าการเดินทางอาจมีผู้โดยสารคนอื่นๆ จากต้นทางและจุดหมายอื่นในยานพาหนะเดียวกัน (SHARED
) หรือผู้โดยสารคนเดียว (EXCLUSIVE
) หรือไม่pickup_point
- TerminalLocation แสดงถึงต้นทางของการเดินทาง โปรดดูข้อมูลอ้างอิงของ RPC หรือข้อมูลอ้างอิงของ REST
เมื่อสร้างการเดินทาง ให้ระบุ number_of_passengers
, dropoff_point
และ vehicle_id
แม้ว่าจะไม่จำเป็นต้องกรอกข้อมูลในช่องเหล่านี้ แต่หากคุณระบุ ช่องดังกล่าวจะเก็บไว้ ระบบจะไม่พิจารณาช่อง Trip อื่นๆ ทั้งหมด ตัวอย่างเช่น การเดินทางทั้งหมดจะเริ่มต้นด้วย trip_status
เป็น NEW
แม้ว่าคุณจะส่งผ่านใน trip_status
ของ CANCELED
ในคำขอสร้าง
ตัวอย่าง
ตัวอย่างต่อไปนี้ทำให้เกิดการเดินทางไปยังศูนย์การค้า Grand Indonesia East Mall การเดินทางนี้สำหรับผู้โดยสาร 2 คนและเป็นราคาพิเศษ provider_id
ของ Trip
ต้องเป็นรหัสเดียวกับรหัสโปรเจ็กต์ ในตัวอย่างนี้ ผู้ให้บริการ Rideshare ได้สร้าง
โปรเจ็กต์ Google Cloud ซึ่งก็คือ project-id โปรเจ็กต์นี้ต้องมีบัญชีบริการที่ใช้เรียกใช้ Fleet Engine สถานะของการเดินทางคือNEW
หลังจากนั้น หลังจากที่บริการตรงกับการเดินทางไปยังรถแล้ว บริการจะโทรหา UpdateTrip
และเปลี่ยน vehicle_id
เมื่อมีการเดินทางให้กับยานพาหนะได้
Shell
curl -X POST \
"https://fleetengine.googleapis.com/v1/providers/project-id/trips?tripId=tid-1f97" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
--data-binary @- << EOM
{
"tripType": "EXCLUSIVE",
"numberOfPassengers": 2,
"pickupPoint": {
"point": {"latitude": "-6.195139", "longitude": "106.820826"}
},
"dropoffPoint": {
"point": {"latitude": "-6.1275", "longitude": "106.6537"}
}
}
EOM
ดูข้อมูลอ้างอิง providers.trips.create
Java
static final String PROJECT_ID = "project-id";
TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);
String parent = "providers/" + PROJECT_ID;
Trip trip = Trip.newBuilder()
.setTripType(TripType.EXCLUSIVE) // Use TripType.SHARED for carpooling
.setPickupPoint( // Grand Indonesia East Mall
TerminalLocation.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
// Provide the number of passengers if available.
.setNumberOfPassengers(2)
// Provide the drop-off point if available.
.setDropoffPoint(
TerminalLocation.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.1275).setLongitude(106.6537)))
.build();
CreateTripRequest createTripRequest =
CreateTripRequest.newBuilder() // no need for the header
.setParent(parent)
.setTripId("tid-1f97") // Trip ID assigned by the Provider
.setTrip(trip) // Initial state
.build();
// Error handling
// If Fleet Engine does not have trip with that id and the credentials of the
// requestor pass, the service creates the trip successfully.
try {
Trip createdTrip =
tripService.createTrip(createTripRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case ALREADY_EXISTS:
break;
case PERMISSION_DENIED:
break;
}
return;
}
บันทึกของ Google Cloud Platform สำหรับการสร้างการเดินทาง
Fleet Engine API จะเขียนรายการบันทึกโดยใช้บันทึกของ Google Cloud Platform เมื่อได้รับการเรียกใช้ไปยังปลายทาง CreateTrip
รายการบันทึกจะมีข้อมูลเกี่ยวกับค่าในคำขอ CreateTrip
หากการเรียกสำเร็จ จะมีข้อมูลเกี่ยวกับ Trip
ที่ส่งกลับด้วย
วิธีการ: อัปเดตการเดินทาง
เอนทิตีการเดินทางมีช่องที่เปิดใช้การติดตามโดยบริการและการรายงานความคืบหน้าของการเดินทางโดย SDK ไดรเวอร์และไปยัง Consumer SDK หากต้องการอัปเดตพร็อพเพอร์ตี้ ให้ใช้ข้อความ UpdateTripRequest
การดำเนินการนี้จะอัปเดตช่องการเดินทางตาม field_mask
ของคำขอ
โปรดดู UpdateTripRequest
ผู้ให้บริการบริการเรียกรถมีหน้าที่อัปเดตแอตทริบิวต์ต่อไปนี้
- สถานะการเดินทาง
- รหัสยานพาหนะ โดยอาจเป็น ณ เวลาที่สร้าง หรือหลังจากจับคู่ยานพาหนะกับการเดินทาง
- เปลี่ยนเป็นจุดรับ ส่งของ และจุดอ้างอิง
Fleet Engine จะอัปเดตช่องต่อไปนี้โดยอัตโนมัติเมื่อใช้ฟีเจอร์การแชร์เส้นทางผ่าน Driver SDK หรือ Consumer SDK
- เส้นทาง
- ETA
- ระยะทางที่เหลือ
- ตำแหน่งของรถ
- จุดอ้างอิงที่เหลือ
โปรดดู Trip
ใน RPC หรือ Resource.Trip
ใน REST
บันทึกของ Google Cloud Platform สำหรับข้อมูลอัปเดตการเดินทาง
Fleet Engine API จะเขียนรายการบันทึกโดยใช้บันทึกของ Google Cloud Platform เมื่อได้รับการเรียกใช้ไปยังปลายทาง UpdateTrip
รายการบันทึกจะมีข้อมูลเกี่ยวกับค่าในคำขอ UpdateTrip
หากเรียกใช้สำเร็จ
จะมีข้อมูลเกี่ยวกับ Trip
ที่แสดงผลด้วย
HOW-TO: ค้นหาการเดินทาง
Fleet Engine รองรับการค้นหาการเดินทาง ตามที่ได้แจ้งไว้ก่อนหน้านี้ ระบบจะลบทริปโดยอัตโนมัติหลังจากผ่านไป 7 วัน ดังนั้น SearchTrips
จะไม่แสดงประวัติทั้งหมดของทริป
แม้ว่า SearchTrips
จะเป็น API ที่ยืดหยุ่น แต่รายการด้านล่างจะพิจารณากรณีการใช้งาน 2 กรณี
การกำหนดการเดินทางที่ใช้งานอยู่ของยานพาหนะ -- ผู้ให้บริการสามารถระบุการเดินทางที่ใช้งานอยู่ในปัจจุบันของยานพาหนะได้ ภายใน
SearchTripsRequest
ต้องตั้งค่าvehicle_id
เป็นยานพาหนะที่อยู่ระหว่างการพิจารณา และควรตั้งค่าactive_trips_only
เป็นtrue
การปรับยอดผู้ให้บริการกับสถานะของ Fleet Engine -- ผู้ให้บริการใช้
SearchTrips
เพื่อให้แน่ใจว่าสถานะของการเดินทางและสถานะของ Fleet Engine ตรงกันได้ ซึ่งสำคัญมากสำหรับ TripStatus หากสถานะของการเดินทางที่กำหนดให้กับยานพาหนะไม่ได้ตั้งค่าเป็นCOMPLETE
หรือCANCELED
อย่างถูกต้องSearchVehicles
จะไม่รวมยานพาหนะดังกล่าว
หากต้องการใช้ SearchTrips
ในลักษณะนี้ ให้ปล่อย vehicle_id
ว่างไว้ ตั้งค่า active_trips_only
เป็น true
และตั้งค่า minimum_staleness
ให้นานกว่าระยะเวลาการเดินทางส่วนใหญ่
ตัวอย่างเช่น คุณอาจใช้ 1 ชั่วโมง ผลลัพธ์ประกอบด้วยการเดินทางที่ไม่สมบูรณ์หรือยกเลิก และไม่มีการอัปเดตในกว่า 1 ชั่วโมง ผู้ให้บริการควรตรวจสอบทริปเหล่านี้เพื่อให้แน่ใจว่าสถานะใน Fleet Engine ได้รับการอัปเดตอย่างถูกต้อง
การแก้ปัญหา
ในกรณีที่เกิดข้อผิดพลาด DEADLINE_EXCEEDED
ระบบจะไม่ทราบสถานะของ Fleet Engine ผู้ให้บริการควรเรียกใช้ CreateTrip
อีกครั้ง ซึ่งจะแสดง 201 (CREATED) หรือ 409 (CONFLICT) ในกรณีหลัง คำขอก่อนหน้าประสบความสำเร็จก่อนวันที่ DEADLINE_EXCEEDED
ดูคู่มือ Consumer API สำหรับข้อมูลเพิ่มเติม
เกี่ยวกับการจัดการข้อผิดพลาดในการเดินทางได้ที่ Android
หรือ iOS
ความช่วยเหลือในการโดยสารรถร่วมกัน
คุณกำหนดการเดินทางSHARED
ได้หลายครั้งให้กับยานพาหนะที่รองรับ TripType.SHARED
คุณต้องระบุลำดับของจุดอ้างอิงที่ไม่ผ่านทั้งหมดสำหรับการเดินทางทั้งหมดที่กำหนดให้กับรถในการเดินทางร่วมนี้ผ่าน Trip.vehicle_waypoints
เมื่อคุณกำหนด vehicle_id
สำหรับการเดินทางที่แชร์ร่วมกัน (ในคำขอ CreateTrip
หรือ UpdateTrip
)
โปรดดู vehicle_waypoints
สำหรับ RPC
หรือ vehicleWaypoints
สำหรับ REST
การรองรับปลายทางหลายแห่ง
ระบุปลายทางตัวกลาง
ระบบได้รวมช่อง intermediateDestinations
และช่อง intermediateDestinationIndex
ในการเดินทาง (RPC | REST) เข้าด้วยกันเพื่อใช้ระบุจุดหมาย
อัปเดตปลายทางระดับกลาง
คุณอัปเดตปลายทางขั้นกลางได้ผ่าน UpdateTrip
เมื่ออัปเดตปลายทางขั้นกลาง คุณต้องระบุรายการจุดหมายระดับกลางทั้งหมด รวมถึงปลายทางที่เคยเข้าชม ไม่ใช่แค่เพียงแห่งเดียวที่เพิ่มใหม่หรือที่ต้องแก้ไข
เมื่อ intermediateDestinationIndex
ชี้ไปยังดัชนีหลังตำแหน่งปลายทางขั้นกลางที่เพิ่ม/แก้ไขใหม่ ระบบจะไม่เพิ่มปลายทางขั้นกลางใหม่/ที่อัปเดตไปยัง waypoints
หรือ remainingWaypoints
ของการเดินทาง
สาเหตุก็คือปลายทางขั้นกลางใดๆ ที่อยู่ก่อน intermediateDestinationIndex
จะถือว่าเป็นการเข้าชมแล้ว
การเปลี่ยนแปลงสถานะการเดินทาง
ต้องระบุช่อง intermediateDestinationsVersion
ใน (RPC | REST)
ในคำขออัปเดตสถานะการเดินทางที่ส่งไปยัง Fleet Engine เพื่อระบุว่าปลายทางระดับกลางได้ผ่านไปแล้ว ปลายทางระดับกลางที่กำหนดเป้าหมาย
จะมีการระบุผ่านช่อง intermediateDestinationIndex
เมื่อ tripStatus
(RPC | REST) คือ ENROUTE_TO_INTERMEDIATE_DESTINATION ตัวเลขระหว่าง
[0..N-1] บ่งชี้ถึงจุดหมายกลางที่ยานพาหนะจะขับต่อไป
เมื่อ tripStatus
คือ ARRIVED_AT_INTERMEDIATE_DESTINATION ตัวเลขระหว่าง
[0..N-1] บ่งชี้ถึงจุดหมายระดับกลางที่ยานพาหนะอยู่
ตัวอย่าง
ตัวอย่างโค้ดต่อไปนี้แสดงวิธีอัปเดตสถานะของการเดินทางเพื่อเปลี่ยนเส้นทางไปยังปลายทางกลางแรก โดยสมมติว่าคุณได้สร้างการเดินทางแบบหลายจุดหมาย และการเดินทางผ่านจุดรับสินค้าไปแล้ว
Java
static final String PROJECT_ID = "project-id";
static final String TRIP_ID = "multi-destination-trip-A";
String tripName = "providers/" + PROJECT_ID + "/trips/" + TRIP_ID;
Trip trip = …; // Fetch trip object from FleetEngine or your storage.
TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);
// Trip settings to update.
Trip trip = Trip.newBuilder()
// Trip status cannot go back to a previous status once it is passed
.setTripStatus(TripStatus.ENROUTE_TO_INTERMEDIATE_DESTINATION)
// Enrouting to the first intermediate destination.
.setIntermediateDestinationIndex(0)
// intermediate_destinations_version MUST be provided to ensure you
// have the same picture on intermediate destinations list as FleetEngine has.
.setIntermediateDestinationsVersion(
trip.getIntermediateDestinationsVersion())
.build();
// Trip update request
UpdateTripRequest updateTripRequest =
UpdateTripRequest.newBuilder()
.setName(tripName)
.setTrip(trip)
.setUpdateMask(
FieldMask.newBuilder()
.addPaths("trip_status")
.addPaths("intermediate_destination_index")
// intermediate_destinations_version must not be in the
// update mask.
.build())
.build();
// Error handling
try {
Trip updatedTrip = tripService.updateTrip(updateTripRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND: // Trip does not exist.
break;
case FAILED_PRECONDITION: // The given trip status is invalid, or the
// intermediate_destinations_version
// doesn’t match FleetEngine’s.
break;
case PERMISSION_DENIED:
break;
}
return;
}
วิธีการ: สมัครรับข้อความแจ้งเตือนจาก Fleet Engine API
Fleet Engine API ใช้ Google Cloud Pub/Sub เพื่อเผยแพร่การแจ้งเตือนในหัวข้อที่สร้างโดยโปรเจ็กต์ Google Cloud สำหรับผู้บริโภค Pub/Sub ไม่ได้เปิดใช้โดยค่าเริ่มต้นสำหรับ Fleet Engine ในโปรเจ็กต์ Google Cloud ของคุณ โปรดส่งเคสขอรับความช่วยเหลือหรือติดต่อวิศวกรลูกค้าเพื่อเปิดใช้ Pub/Sub
หากต้องการสร้างหัวข้อในโปรเจ็กต์ที่อยู่ในระบบคลาวด์ ให้ทำตามวิธีการเหล่านี้ รหัสหัวข้อต้องเป็น "fleet_engine_notifications"
คุณต้องสร้างหัวข้อในโปรเจ็กต์ Cloud เดียวกับที่เรียกใช้ API ของ Fleet Engine
เมื่อสร้างหัวข้อแล้ว คุณจะต้องให้สิทธิ์ Fleet Engine API เพื่อเผยแพร่ในหัวข้อดังกล่าว วิธีการคือคลิกหัวข้อ
ที่คุณเพิ่งสร้างขึ้น แล้วเพิ่มสิทธิ์ใหม่ คุณอาจต้องคลิกแสดงแผงข้อมูลเพื่อเปิดเครื่องมือแก้ไขสิทธิ์
ผู้ใช้หลักควรเป็น geo-fleet-engine@system.gserviceaccount.com
และบทบาทควรเป็น Pub/Sub publisher
หากต้องการตั้งค่าโปรเจ็กต์ที่อยู่ในระบบคลาวด์ให้สมัครรับการแจ้งเตือน โปรดทำตามวิธีการเหล่านี้
Fleet Engine API จะเผยแพร่การแจ้งเตือนแต่ละรายการในรูปแบบข้อมูลที่แตกต่างกัน 2 รูปแบบ ได้แก่ protobuf
และ json
รูปแบบข้อมูลสำหรับการแจ้งเตือนแต่ละรายการจะแสดงอยู่ในแอตทริบิวต์ PubsubMessage โดยมีคีย์เป็น data_format
และค่าเป็น protobuf
หรือ json
สคีมาการแจ้งเตือน:
โปรโตคอล
// A batch of notifications that is published by the Fleet Engine service using
// Cloud Pub/Sub in a single PubsubMessage.
message BatchNotification {
// Required. At least one notification must exist.
// List of notifications containing information related to changes in
// Fleet Engine data.
repeated Notification notifications = 1;
}
// A notification related to changes in Fleet Engine data.
// The data provides additional information specific to the type of the
// notification.
message Notification {
// Required. At least one type must exist.
// Type of notification.
oneof type {
// Notification related to changes in vehicle data.
VehicleNotification vehicle_notification = 1;
}
}
// Notification sent when a new vehicle was created.
message CreateVehicleNotification {
// Required.
// Vehicle must contain all fields that were set when it was created.
Vehicle vehicle = 1;
}
// Notification sent when an existing vehicle is updated.
message UpdateVehicleNotification {
// Required.
// Vehicle must only contain name and fields that are present in the
// field_mask field below.
Vehicle vehicle = 1;
// Required.
// Contains vehicle field paths that were specifically requested
// by the Provider.
google.protobuf.FieldMask field_mask = 2;
}
// Notification related to changes in vehicle data.
message VehicleNotification {
// Required. At least one type must be set.
// Type of notification.
oneof type {
// Notification sent when a new vehicle was created.
CreateVehicleNotification create_notification = 1;
// Notification sent when an existing vehicle is updated.
UpdateVehicleNotification update_notification = 2;
}
}
JSON
BatchNotification: {
"description": "A batch of notifications that is published by the Fleet Engine service using Cloud Pub/Sub in a single PubsubMessage.",
"type": "object",
"required": ["notifications"],
"properties": {
"notifications": {
"description": "At least one notification must exist. List of notifications containing information related to changes in Fleet Engine data.",
"type": "Notification[]"
}
}
}
Notification: {
"description": "A notification related to changes in Fleet Engine data. The data provides additional information specific to the type of the notification.",
"type": "object",
"properties": {
"vehicleNotification": {
"description": "Notification related to changes in vehicle data.",
"type": "VehicleNotification"
}
}
}
VehicleNotification: {
"description": "Notification related to changes in vehicle data.",
"type": "object",
"properties": {
"createNotification": {
"description": "Notification sent when a new vehicle was created.",
"type": "CreateVehicleNotification"
},
"updateNotification": {
"description": "Notification sent when an existing vehicle is updated.",
"type": "UpdateVehicleNotification"
}
}
}
CreateVehicleNotification: {
"description": "Notification sent when a new vehicle was created.",
"type": "object",
"required": ["vehicle"],
"properties": {
"vehicle": {
"description": "Vehicle must contain all fields that were set when it was created.",
"type": "Vehicle"
}
}
}
UpdateVehicleNotification: {
"description": "Notification sent when an existing vehicle is updated.",
"type": "object",
"required": ["vehicle", "fieldMask"],
"properties": {
"vehicle": {
"description": "Vehicle must only contain name and fields that are present in the fieldMask field below.",
"type": "Vehicle"
},
"fieldMask": {
"description": "Contains vehicle field paths that were specifically requested by the Provider.",
"type": "FieldMask"
}
}
}