เริ่มต้นใช้งาน Fleet Engine

API การเดินทางและการนำส่งแบบออนดีมานด์ของ Fleet Engine ช่วยให้คุณจัดการการเดินทางได้ และสถานะของพาหนะสำหรับแอปพลิเคชันการเดินทางและความคืบหน้าในการสั่งซื้อของคุณ จัดการธุรกรรมระหว่าง Driver SDK, SDK ของผู้บริโภค และ บริการแบ็กเอนด์ ซึ่งสามารถสื่อสารกับ Fleet Engine โดยทำให้ gRPC ก็ได้ หรือ REST

ข้อกำหนดเบื้องต้น

สำหรับการพัฒนา โปรดตรวจสอบว่าคุณติดตั้ง SDK (gcloud) และได้รับการตรวจสอบสิทธิ์เพื่อ โปรเจ็กต์ของคุณ

gcloud auth login

You are now logged in as [my-user@example.com].
Your current project is [project-id].  You ...

ตรวจสอบว่าได้กำหนดค่า API ของโซลูชัน Fleet Engine สำหรับเรียกรถและการนำส่งแบบออนดีมานด์อย่างเหมาะสม

gcloud --project=project-id services enable fleetengine.googleapis.com

การบันทึก

Fleet Engine เขียนข้อความบันทึกเกี่ยวกับการเรียก API ที่ได้รับได้ ลงใน บันทึกของ Google Cloud Platform โปรดดูเอกสาร Cloud Logging สำหรับ ภาพรวมเกี่ยวกับวิธีอ่านและวิเคราะห์บันทึก

โดยค่าเริ่มต้น โปรเจ็กต์ที่สร้างอาจไม่ได้เปิดใช้การบันทึก 10 ก.พ. 2022 โปรดดู เอกสารประกอบในการบันทึก เพื่อดูรายละเอียดเพิ่มเติม

ไลบรารีไคลเอ็นต์

เราเผยแพร่ไลบรารีของไคลเอ็นต์ในภาษาโปรแกรมทั่วไปหลายภาษา เหล่านี้ เพื่อช่วยให้นักพัฒนาซอฟต์แวร์ได้รับประสบการณ์ที่ดีขึ้นในการใช้งาน REST หรือ gRPC แบบข้อมูลดิบ สำหรับคำแนะนำเกี่ยวกับวิธีรับไลบรารีของไคลเอ็นต์สำหรับแอปพลิเคชันเซิร์ฟเวอร์ของคุณ ดู ไลบรารีไคลเอ็นต์

ตัวอย่าง Java ในเอกสารประกอบนี้จะถือว่าคุ้นเคยกับ gRPC อยู่แล้ว

การตรวจสอบสิทธิ์และการให้สิทธิ์

คุณสามารถกำหนดค่าความสามารถที่ให้บริการโดยการเดินทางและความคืบหน้าของคำสั่งซื้อผ่าน คอนโซล Google Cloud API และ SDK เหล่านี้ต้องใช้เว็บโทเค็น JSON ที่ ได้รับการลงนามโดยใช้บัญชีบริการที่สร้างจาก Cloud Console

ตั้งค่าโปรเจ็กต์ที่อยู่ในระบบคลาวด์

หากต้องการตั้งค่าโปรเจ็กต์ระบบคลาวด์ ให้สร้างโปรเจ็กต์ก่อนแล้วจึง สร้างบัญชีบริการ

วิธีสร้างโปรเจ็กต์ Google Cloud

1. สร้างโปรเจ็กต์ Google Cloud โดยใช้ Google Cloud Console
2. ในการใช้ API และบริการแดชบอร์ด ให้เปิดใช้ API การโดยสารและการนำส่งในท้องถิ่น

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

ความคืบหน้าการเดินทางและคําสั่งซื้อใช้บทบาทต่อไปนี้

เช่น สร้างบัญชีบริการให้กับแต่ละบทบาททั้ง 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 ประกอบด้วยฟิลด์ต่อไปนี้

ส่วนการอ้างสิทธิ์ JWT ประกอบด้วยฟิลด์ต่อไปนี้

การสร้างโทเค็น 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 ในส่วนหัว ให้ระบุคีย์ส่วนตัวของบัญชีบริการ ID คุณจะดูค่านี้ได้ในช่อง 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 เพื่อประสิทธิภาพที่ดีที่สุด การอัปเดตตำแหน่ง ใช้วิธีใดวิธีหนึ่งต่อไปนี้เพื่อแจ้งการอัปเดต

1. ใช้ Driver SDK - Android iOS -- ตัวเลือกที่ง่ายที่สุด
2. ใช้โค้ดที่กำหนดเอง -- มีประโยชน์หากสถานที่ ส่งต่อผ่านแบ็กเอนด์ของคุณ หรือหากคุณใช้อุปกรณ์อื่นที่ไม่ใช่ Android หรือ iOS

เอนทิตียานพาหนะมีช่องที่ซ้ำของ 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 ที่สร้างขึ้น

ตัวอย่าง

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

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 ที่ ส่งคืนแล้ว

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 สิทธิ์

ตัวอย่าง

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

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

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

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 ที่ ส่งคืนแล้ว

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

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

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

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

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 เมื่อมีการเดินทางให้กับยานพาหนะ

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

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] ระบุว่ารถอยู่ตรงปลายทางใด

ตัวอย่าง

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

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 ใช้ 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

• ยานพาหนะ
• FieldMask

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