API การเดินทางและการนำส่งแบบออนดีมานด์ของ Fleet Engine ช่วยให้คุณจัดการการเดินทางได้ และสถานะของพาหนะสำหรับแอปพลิเคชันการเดินทางและความคืบหน้าในการสั่งซื้อของคุณ จัดการธุรกรรมระหว่าง Driver SDK, SDK ของผู้บริโภค และ บริการแบ็กเอนด์ ซึ่งสามารถสื่อสารกับ Fleet Engine โดยทำให้ gRPC ก็ได้ หรือ REST
ข้อกำหนดเบื้องต้น
สำหรับการพัฒนา โปรดตรวจสอบว่าคุณติดตั้ง 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 เพื่อรับสิทธิ์เข้าถึง
การบันทึก
Fleet Engine เขียนข้อความบันทึกเกี่ยวกับการเรียก API ที่ได้รับได้ ลงใน บันทึกของ Google Cloud Platform โปรดดูเอกสาร Cloud Logging สำหรับ ภาพรวมเกี่ยวกับวิธีอ่านและวิเคราะห์บันทึก
โดยค่าเริ่มต้น โปรเจ็กต์ที่สร้างอาจไม่ได้เปิดใช้การบันทึก 10 ก.พ. 2022 โปรดดู เอกสารประกอบในการบันทึก เพื่อดูรายละเอียดเพิ่มเติม
ไลบรารีไคลเอ็นต์
เราเผยแพร่ไลบรารีของไคลเอ็นต์ในภาษาโปรแกรมทั่วไปหลายภาษา เหล่านี้ เพื่อช่วยให้นักพัฒนาซอฟต์แวร์ได้รับประสบการณ์ที่ดีขึ้นในการใช้งาน REST หรือ gRPC แบบข้อมูลดิบ สำหรับคำแนะนำเกี่ยวกับวิธีรับไลบรารีของไคลเอ็นต์สำหรับแอปพลิเคชันเซิร์ฟเวอร์ของคุณ ดู ไลบรารีไคลเอ็นต์
ตัวอย่าง Java ในเอกสารประกอบนี้จะถือว่าคุ้นเคยกับ gRPC อยู่แล้ว
การตรวจสอบสิทธิ์และการให้สิทธิ์
คุณสามารถกำหนดค่าความสามารถที่ให้บริการโดยการเดินทางและความคืบหน้าของคำสั่งซื้อผ่าน คอนโซล Google Cloud API และ SDK เหล่านี้ต้องใช้เว็บโทเค็น JSON ที่ ได้รับการลงนามโดยใช้บัญชีบริการที่สร้างจาก Cloud Console
ตั้งค่าโปรเจ็กต์ที่อยู่ในระบบคลาวด์
หากต้องการตั้งค่าโปรเจ็กต์ระบบคลาวด์ ให้สร้างโปรเจ็กต์ก่อนแล้วจึง สร้างบัญชีบริการ
วิธีสร้างโปรเจ็กต์ Google Cloud
- สร้างโปรเจ็กต์ Google Cloud โดยใช้ Google Cloud Console
- ในการใช้ API และบริการแดชบอร์ด ให้เปิดใช้ API การโดยสารและการนำส่งในท้องถิ่น
บัญชีบริการเชื่อมโยงกับบทบาทอย่างน้อย 1 บทบาท โดยใช้เพื่อสร้าง JSON Web Token ที่ให้สิทธิ์ชุดต่างๆ กันโดยขึ้นอยู่กับ บทบาทใหม่ โดยทั่วไป ในการลดโอกาสเกิดการละเมิด คุณสามารถสร้าง บัญชีบริการ โดยแต่ละบัญชีจะมีชุดบทบาทขั้นต่ำที่จำเป็น
ความคืบหน้าการเดินทางและคําสั่งซื้อใช้บทบาทต่อไปนี้
บทบาท | คำอธิบาย |
---|---|
ผู้ใช้ 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 Tokens (JWT) ที่สร้างขึ้นโดยตรงภายในฐานของโค้ด ซึ่งคุณจะต้องมีทั้ง มีความเข้าใจเกี่ยวกับ JWT และความเกี่ยวข้อง กับ Fleet Engine และนี่คือเหตุผลที่เรา เราขอแนะนำให้คุณใช้ประโยชน์จากไลบรารีการตรวจสอบสิทธิ์ Fleet Engine
ภายใน Fleet Engine โทเค็นเว็บ JSON (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 นาทีสำหรับการเอียง หาก การประทับเวลาอยู่ในอดีตนานเกินไป หรือในอนาคต เซิร์ฟเวอร์อาจรายงานข้อผิดพลาด |
หมดอายุ | การประทับเวลาเมื่อโทเค็นหมดอายุ โดยระบุเป็นวินาทีที่ผ่านไป ตั้งแต่ 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 เพื่อส่งไปยังอุปกรณ์เคลื่อนที่ อย่าลืมใช้ บัญชีบริการสำหรับบทบาท 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 ต่อไปนี้เพื่อลงนามโทเค็นในนามของ Super บัญชีบริการของผู้ใช้:
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)"
ยานพาหนะและวงจร
ยานพาหนะคือเอนทิตีที่แสดงถึงคู่คนขับกับพาหนะ ปัจจุบัน ติดตามคนขับและรถยนต์แยกกันไม่ได้ บริการร่วมเดินทางหรือผู้ให้บริการนำส่ง สร้างยานพาหนะโดยใช้รหัสผู้ให้บริการ (ซึ่งต้องเหมือนกับ รหัสโปรเจ็กต์ของโปรเจ็กต์ 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 วิธี รายการที่ 1 คือ UpdateVehicle
API เมื่อใช้ 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
แล้วอาจมีการส่งคืนโดยทันทีเพื่อตอบสนองต่อ 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
สาย หากต้องการอัปเดตค่าของแอตทริบิวต์เฉพาะ
ใช้ UpdateVehicleAttributes
API ได้
ตัวอย่าง
ตัวอย่างนี้เปิดใช้ 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
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
ที่ใช้เวลาเพียง 2 นาที อินเทอร์เฟซเหล่านี้ช่วยให้สร้างเอนทิตี Trip, คำขอข้อมูล และการค้นหา
ฟังก์ชันการใช้งาน และความสามารถในการอัปเดต
Trip
มีช่องสถานะสำหรับติดตามความคืบหน้าในวงจร
ค่าจะย้ายจาก NEW
ไปยัง COMPLETE
บวก CANCELED
และ UNKNOWN_TRIP_STATUS
ที่ใช้เวลาเพียง 2 นาที โปรดดูที่ 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 | พัก)
เปลี่ยนจากสถานะอื่นๆ เป็น 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
- สตริงที่มีรหัสผู้ให้บริการซึ่งสร้างขึ้นเมื่อ สร้างโปรเจ็กต์ที่อยู่ในระบบคลาวด์แล้วtrip_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
ต้องเป็น
รหัสเดียวกับรหัสโปรเจ็กต์ ในตัวอย่างนี้ ผู้ให้บริการบริการร่วมเดินทางได้สร้าง
โปรเจ็กต์ 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
ที่ส่งกลับด้วย
วิธีการ: อัปเดตการเดินทาง
เอนทิตีการเดินทางมีช่องที่เปิดใช้การติดตามโดยบริการและสำหรับ
รายงานความคืบหน้าของการเดินทางโดย Driver SDK และ
SDK สำหรับผู้บริโภค หากต้องการอัปเดตพร็อพเพอร์ตี้ ให้ใช้ UpdateTripRequest
การดำเนินการนี้จะอัปเดตช่องการเดินทางตาม field_mask
ของคำขอ
โปรดดู UpdateTripRequest
ผู้ให้บริการบริการเรียกรถมีหน้าที่อัปเดตแอตทริบิวต์ต่อไปนี้
- สถานะการเดินทาง
- รหัสยานพาหนะ ไม่ว่าจะเป็นตอนที่สร้าง หรือหลังจากจับคู่รถยนต์กับ
- เปลี่ยนเป็นจุดรับ ส่งของ และจุดอ้างอิง
Fleet Engine จะอัปเดตฟิลด์ต่อไปนี้โดยอัตโนมัติเมื่อใช้ ฟีเจอร์ Journey Share ผ่าน 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 | พัก)
จะถูกรวมเข้าด้วยกันเพื่อใช้ระบุปลายทาง
อัปเดตปลายทางระดับกลาง
คุณอัปเดตปลายทางขั้นกลางได้ผ่าน 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 เดียวกับที่เรียกใช้ Fleet Engine API
เมื่อสร้างหัวข้อแล้ว คุณจะต้องให้สิทธิ์ 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"
}
}
}