फ़्लीट इंजन का इस्तेमाल शुरू करना

फ़्लीट इंजन की मांग पर राइड और डिलीवरी करने वाले एपीआई की मदद से, यात्रा और ऑर्डर की प्रोग्रेस से जुड़े ऐप्लिकेशन के लिए, यात्राओं और वाहन की स्थिति को मैनेज किया जा सकता है. यह ड्राइवर SDK टूल, उपभोक्ता SDK, और आपकी बैकएंड सेवा के बीच लेन-देन को मैनेज करता है. ये डिवाइस gRPC या REST कॉल करके, फ़्लीट इंजन से संपर्क कर सकते हैं.

ज़रूरी शर्तें

डेवलपमेंट के लिए, पक्का करें कि आपने Cloud SDK टूल (gcloud) इंस्टॉल किया हो और आपके प्रोजेक्ट की पुष्टि हो चुकी हो.

शेल

gcloud auth login

आपको सफल होने का मैसेज दिखना चाहिए, जैसे:

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

पक्का करें कि मांग पर राइड और डिलीवरी सॉल्यूशन फ़्लीट इंजन के एपीआई सही तरीके से कॉन्फ़िगर किए गए हों.

शेल

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

अगर इस निर्देश की वजह से कोई गड़बड़ी होती है, तो ऐक्सेस पाने के लिए अपने प्रोजेक्ट एडमिन और Google सहायता प्रतिनिधि से संपर्क करें.

लॉगिंग

Fleet Engine उसे मिलने वाले एपीआई कॉल के बारे में लॉग मैसेज Google Cloud Platform के लॉग में लिख सकता है. लॉग पढ़ने और उनका विश्लेषण करने के तरीके के बारे में खास जानकारी पाने के लिए, Cloud Logging से जुड़ा दस्तावेज़ देखें.

ऐसा हो सकता है कि 10 फ़रवरी, 2022 से पहले बनाए गए प्रोजेक्ट के लिए, लॉग इन करने की सुविधा डिफ़ॉल्ट रूप से चालू न हो. ज़्यादा जानकारी के लिए, लॉग इन करने का दस्तावेज़ देखें.

क्लाइंट लाइब्रेरी

हम क्लाइंट लाइब्रेरी को कई सामान्य प्रोग्रामिंग भाषाओं में पब्लिश करते हैं. ये लाइब्रेरी, REST या gRPC के रॉ वर्शन पर डेवलपर के अनुभव को बेहतर बनाने में मदद करेंगी. अपने सर्वर ऐप्लिकेशन के लिए क्लाइंट लाइब्रेरी पाने का तरीका जानने के लिए, क्लाइंट लाइब्रेरी देखें.

इस दस्तावेज़ में दिए गए Java के उदाहरणों को लगता है कि gRPC के बारे में आपको अच्छी तरह पता है.

पुष्टि करना और अनुमति देना

Google Cloud Console की मदद से, यात्रा और ऑर्डर की प्रोग्रेस से मिलने वाली सुविधाओं को कॉन्फ़िगर किया जा सकता है. इन एपीआई और SDK टूल के लिए, JSON वेब टोकन का इस्तेमाल करना ज़रूरी होता है. इन टोकन को Cloud Console से बनाए गए सेवा खातों का इस्तेमाल करके साइन किया जाता है.

Cloud प्रोजेक्ट का सेटअप

अपना क्लाउड प्रोजेक्ट सेट अप करने के लिए, पहले अपना प्रोजेक्ट बनाएं और फिर सेवा खाते बनाएं.

Google Cloud प्रोजेक्ट बनाने के लिए:

  1. Google Cloud Console का इस्तेमाल करके, Google Cloud प्रोजेक्ट बनाएं.
  2. एपीआई और सेवाएं डैशबोर्ड का इस्तेमाल करके, Local Rides and Deliveryies API को चालू करें.

सेवा खाते, एक या उससे ज़्यादा भूमिकाओं से जुड़े हैं. इनका इस्तेमाल, JSON वेब टोकन बनाने के लिए किया जाता है. ये टोकन, भूमिकाओं के हिसाब से अलग-अलग तरह की अनुमतियां देते हैं. आम तौर पर, गलत इस्तेमाल को कम करने के लिए, कई सेवा खाते बनाए जा सकते हैं. हर खाते में कम से कम भूमिकाएं दी जाती हैं.

यात्रा और ऑर्डर की प्रोग्रेस, इन भूमिकाओं का इस्तेमाल करती है:

भूमिकाकंपनी का ब्यौरा
फ़्लीट इंजन उपभोक्ता SDK टूल का उपयोगकर्ता

roles/fleetengine.consumerSdkUser		 वाहन खोजने और वाहनों और यात्राओं की जानकारी पाने की अनुमति देता है. इस भूमिका वाले सेवा खाते के बनाए गए टोकन, आम तौर पर राइडशेयरिंग या डिलीवरी के लिए चुने गए उपभोक्ता ऐप्लिकेशन के मोबाइल डिवाइसों से इस्तेमाल किए जाते हैं.
फ़्लीट इंजन ड्राइवर SDK टूल का उपयोगकर्ता

roles/fleetengine.driverSdkUser		 वाहन की जगह और रास्ते की जानकारी अपडेट करने और वाहनों और यात्राओं की जानकारी हासिल करने की अनुमति देता है. इस भूमिका वाले सेवा खाते के बनाए गए टोकन, आम तौर पर राइडशेयरिंग या डिलीवरी ड्राइवर ऐप्लिकेशन के मोबाइल डिवाइसों से इस्तेमाल किए जाते हैं.
फ़्लीट इंजन की मांग पर एडमिन

roles/fleetengine.ondemandAdmin		 वाहन और यात्रा से जुड़े सभी संसाधनों के लिए, पढ़ने और लिखने की अनुमति दें. इस भूमिका वाले मुख्य खातों को JWT का इस्तेमाल करने की ज़रूरत नहीं होती. इसके बजाय, उन्हें ऐप्लिकेशन के डिफ़ॉल्ट क्रेडेंशियल का इस्तेमाल करना चाहिए. कस्टम JWT दावों को अनदेखा किया जाता है. यह भूमिका, भरोसेमंद प्लैटफ़ॉर्म (ग्राहक बैकएंड) तक सीमित होनी चाहिए.
FleetEngine सेवा का सुपर उपयोगकर्ता **(बहिष्कृत)**

roles/fleetengine.serviceSuperUser		 वाहन और यात्रा से जुड़े सभी एपीआई को अनुमति देता है. इस भूमिका वाले सेवा खाते से चुने गए टोकन, आम तौर पर बैकएंड सर्वर से इस्तेमाल किए जाते हैं. यह भूमिका अब काम नहीं करती. इसके बजाय, roles/fleetengine.ondemandAdmin को प्राथमिकता दें.

उदाहरण के लिए, तीनों भूमिकाओं में से हर एक के लिए सेवा खाता बनाएं और उनके लिए अलग-अलग भूमिकाएं असाइन करें.

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

ड्राइवर और उपभोक्ता SDK टूल, इन स्टैंडर्ड भूमिकाओं के आधार पर बनाए जाते हैं.

इसके अलावा, ऐसी कस्टम भूमिकाएं बनाई जा सकती हैं जो अनुमतियों के आर्बिट्रेरी सेट को एक साथ बंडल करने की अनुमति देती हैं. किसी ज़रूरी अनुमति के न होने पर, ड्राइवर और उपभोक्ता SDK टूल गड़बड़ी के मैसेज दिखाएंगे. इसी वजह से, हम strong का सुझाव देते हैं कि आप ऊपर बताई गई भूमिकाओं के स्टैंडर्ड सेट का इस्तेमाल करें, न कि कस्टम भूमिकाओं का इस्तेमाल करें.

अगर आपको गैर-भरोसेमंद क्लाइंट के लिए 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)') से पुष्टि करने के लिए किया जाता है.

फ़्लीट इंजन ऑथ लाइब्रेरी

फ़्लीट इंजन, फ़्लीट इंजन एपीआई के ऐक्सेस को प्रतिबंधित करने के लिए, JSON वेब टोकन (जेडब्ल्यूटी) का इस्तेमाल करता है. नई फ़्लीट इंजन ऑथेंट लाइब्रेरी, GitHub पर उपलब्ध है. यह फ़्लीट इंजन जेडब्ल्यूटी को आसान तरीके से बनाती है और उन्हें सुरक्षित तरीके से साइन करती है.

इस लाइब्रेरी से ये फ़ायदे मिलते हैं:

  • यह फ़्लीट इंजन टोकन बनाने की प्रोसेस को आसान बनाता है.
  • क्रेडेंशियल फ़ाइलों का इस्तेमाल करने के अलावा, टोकन पर हस्ताक्षर करने के तरीके उपलब्ध कराता है. जैसे, सेवा खाते के नाम पर हस्ताक्षर करना.
  • किसी gRPC स्टब या GAPIC क्लाइंट से किए गए आउटबाउंड अनुरोधों पर साइन किए गए टोकन अटैच करता है.

अनुमति पाने के लिए JSON वेब टोकन (JWT) बनाना

जब फ़्लीट इंजन ऑथ लाइब्रेरी का इस्तेमाल न किया जा रहा हो, तब JSON Web Tokens (JWT) सीधे आपके कोड बेस में बनाया जाना चाहिए. इसके लिए ज़रूरी है कि आपको JWT के बारे में अच्छी तरह जानकारी होनी चाहिए. साथ ही, यह भी समझना ज़रूरी है कि ये Fleet Engine से कैसे जुड़े हैं. इसलिए, हम आपको फ़्लीट इंजन ऑथ लाइब्रेरी का इस्तेमाल करने का सुझाव देते हैं.

फ़्लीट इंजन में, JSON वेब टोकन (जेडब्ल्यूटी) कुछ समय तक पुष्टि करने की सुविधा देते हैं. इनसे यह भी पक्का किया जाता है कि डिवाइस सिर्फ़ उन वाहनों, ट्रिप या टास्क में बदलाव करें जिनके लिए उन्हें अनुमति मिली है. JWT में एक हेडर और एक दावा सेक्शन होता है. हेडर सेक्शन में, इस्तेमाल करने के लिए निजी पासकोड (सेवा खातों से लिया गया) और एन्क्रिप्ट (सुरक्षित) करने का एल्गोरिदम जैसी जानकारी होती है. 'दावा' सेक्शन में कई तरह की जानकारी होती है. जैसे, टोकन बनाने का समय, लाइव रहने के लिए टोकन, वे सेवाएं जिनके लिए ऐक्सेस का दावा किया गया है, और ऐक्सेस को कम करने के लिए अनुमति देने से जुड़ी दूसरी जानकारी, जैसे कि वाहन का आईडी.

JWT के हेडर सेक्शन में ये फ़ील्ड होते हैं:

फ़ील्डकंपनी का ब्यौरा
alg एल्गोरिदम का इस्तेमाल करना है. `RS256`.
typ टोकन का टाइप. `JWT`.
बच्चा आपके सेवा खाते का निजी पासकोड आईडी. यह वैल्यू, आपके सेवा खाते की JSON फ़ाइल के `private_key_id` फ़ील्ड में देखी जा सकती है. पक्का करें कि सेवा खाते की ऐसी कुंजी का इस्तेमाल किया जा रहा हो जिसके पास अनुमतियों के सही लेवल हों.

JWT के दावे सेक्शन में ये फ़ील्ड होते हैं:

फ़ील्डकंपनी का ब्यौरा
iss आपके सेवा खाते का ईमेल पता.
बदले में खेलने वाला खिलाड़ी आपके सेवा खाते का ईमेल पता.
ऑडियो आपके सेवा खाते का Service_NAME, इस मामले में https://fleetengine.googleapis.com/
आईएटी टोकन बनाने के समय का टाइमस्टैंप, जो 1 जनवरी, 1970 को 00:00:00 यूटीसी के बाद से सेकंड में बीत चुका है. तिरछा होने पर 10 मिनट दें. अगर टाइमस्टैंप काफ़ी पहले या आने वाले समय का है, तो सर्वर गड़बड़ी की शिकायत कर सकता है.
exp टोकन की समयसीमा खत्म होने का टाइमस्टैंप, जो 1 जनवरी, 1970 को 00:00:00 यूटीसी के बाद से सेकंड में बीत चुका है. अगर टाइमस्टैंप एक घंटे से ज़्यादा का है, तो अनुरोध पूरा नहीं किया जा सकता.
अनुमति देना इस्तेमाल के उदाहरण के हिसाब से, इसमें `vehicleid` या `tripid` हो सकते हैं.

JWT टोकन बनाने का मतलब है, इसे साइन करना. JWT बनाने और साइन करने के निर्देश और कोड सैंपल देखने के लिए, OAuth के बिना सेवा खाते की अनुमति देना देखें. इसके बाद, gRPC कॉल या Fleet Engine को ऐक्सेस करने के लिए इस्तेमाल किए जाने वाले अन्य तरीकों में हस्ताक्षर किया गया टोकन अटैच किया जा सकता है.

JWT के दावे

JWT पेलोड बनाते समय, अनुमति देने वाले सेक्शन में अतिरिक्त दावा जोड़ें. इसके लिए, उस गाड़ी के आईडी या ट्रिप आईडी की वैल्यू पर vehicleid या tripid सेट करें जिसके लिए कॉल किया जा रहा है.

चाहे यात्रा के दौरान या वाहन चलाते समय, ड्राइवर SDK टूल हमेशा vehicleid दावे का इस्तेमाल करता है. फ़्लीट इंजन का बैकएंड यह पक्का करता है कि बदलाव करने से पहले, वाहन, अनुरोध की गई यात्रा से जुड़ा हो.

उपभोक्ता SDK टूल, हमेशा tripid दावे का इस्तेमाल करता है.

राइडशेयर या डिलीवरी की सुविधा देने वाली कंपनी को सभी वाहनों और यात्राओं से मेल खाने के लिए, "*" के साथ vehicleid या tripid का इस्तेमाल करना चाहिए. ध्यान दें कि JWT में दोनों टोकन शामिल हो सकते हैं, भले ही यह ज़रूरी न हो. इससे टोकन साइनिंग को लागू करना आसान हो सकता है.

JWT के इस्तेमाल के उदाहरण

यहां Provider सर्वर के लिए टोकन का एक उदाहरण दिया गया है:

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

यहां Driver ऐप्लिकेशन के लिए टोकन का उदाहरण दिया गया है:

{
  "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 फ़ील्ड के लिए, अपने सेवा खाते का निजी पासकोड आईडी बताएं. आपको यह वैल्यू, अपने सेवा खाते की JSON फ़ाइल के private_key_id फ़ील्ड में मिलेगी.
  • iss और sub फ़ील्ड के लिए, अपने सेवा खाते का ईमेल पता बताएं. आपको यह वैल्यू, अपने सेवा खाते की JSON फ़ाइल के client_email फ़ील्ड में दिखेगी.
  • aud फ़ील्ड के लिए, https://SERVICE_NAME/ बताएं.
  • iat फ़ील्ड के लिए, टोकन बनाए जाने के समय के टाइमस्टैंप का इस्तेमाल करें. इसे 1 जनवरी, 1970 को 00:00:00 यूटीसी के बाद से सेकंड के तौर पर बताया जाता है. तिरछा होने पर 10 मिनट दें. अगर टाइमस्टैंप बहुत पहले या आने वाले समय का है, तो सर्वर गड़बड़ी की शिकायत कर सकता है.
  • exp फ़ील्ड के लिए, टोकन की समयसीमा खत्म होने के समय का टाइमस्टैंप इस्तेमाल करें. इसे 1 जनवरी, 1970 को 00:00:00 यूटीसी से सेकंड के हिसाब से बताया गया है. ज़्यादा से ज़्यादा 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 प्रॉपर्टी, अवधि खत्म होने के कुछ सेकंड बाद का समय है. इसका हिसाब, iat में 3600 जोड़कर लगाया जा सकता है. ऐक्सेस खत्म होने की तारीख, आने वाले समय में एक घंटे से ज़्यादा की नहीं हो सकती.

{
  "aud": "https://fleetengine.googleapis.com/",
  "iss": "super-user-service-account@project-id.iam.gserviceaccount.com",
  "sub": "super-user-service-account@project-id.iam.gserviceaccount.com",
  "iat": iat,
  "exp": exp,
  "authorization": {
     "vehicleid": "*",
     "tripid": "*"
   }
}

इसके बाद, अपने सुपर उपयोगकर्ता सेवा खाते की ओर से टोकन पर साइन करने के लिए, नीचे दिया गया gcloud कमांड चलाएं:

gcloud beta iam service-accounts sign-jwt --iam-account=super-user-service-account@project-id.iam.gserviceaccount.com unsigned_token.json signed_token.jwt

Base64 कोड में बदली गई JWT, अब फ़ाइल signed_token.jwt में सेव की जाएगी. यह टोकन अगले एक घंटे के लिए मान्य है.

अब लिस्ट व्हीकल REST एंडपॉइंट पर curl कमांड चलाकर, टोकन की जांच की जा सकती है:

curl -X GET "https://fleetengine.googleapis.com/v1/providers/project-id/vehicles" -H "Authorization: Bearer $(cat signed_token.jwt)"

वाहन और उनका लाइफ़साइकल

वाहन, ड्राइवर-वाहन की जोड़ी का प्रतिनिधित्व करने वाली इकाई है. फ़िलहाल, ड्राइवर और वाहन को अलग-अलग ट्रैक नहीं किया जा सकता. राइडशेयर या डिलीवरी की सेवा देने वाली कंपनी, वाहन बनाने के लिए, प्रोवाइडर का आईडी (यह Google Cloud प्रोजेक्ट के प्रोजेक्ट आईडी, जिसमें फ़्लीट इंजन एपीआई को कॉल करने के लिए इस्तेमाल किया जाता है वाला सेवा खाता) और राइडशेयर या डिलीवरी की सेवा देने वाली कंपनी के मालिकाना हक वाले वाहन के आईडी का इस्तेमाल करके एक वाहन बनाती है.

अगर वाहन को सात दिनों के बाद भी UpdateVehicle के ज़रिए अपडेट नहीं किया गया, तो वह वाहन अपने-आप मिट जाएगा. पहले से मौजूद प्रोवाइडर आईडी/वाहन आईडी के पेयर से, CreateVehicle को कॉल करने में गड़बड़ी हुई. जिन वाहनों को बार-बार अपडेट नहीं किया जाता उनके मामले में ये दो तरीके अपनाए जा सकते हैं: सेवा देने वाले का अनुमानित आईडी/वाहन आईडी पेयर के साथ CreateVehicle को बार-बार कॉल करना और अगर वाहन पहले से मौजूद है, तो गड़बड़ी को खारिज करना या UpdateVehicle के बाद CreateVehicle पर कॉल करने के बाद NOT_FOUND गड़बड़ी दिखती है.

गाड़ी की जगह की जानकारी के अपडेट

फ़्लीट इंजन की अच्छी परफ़ॉर्मेंस के लिए, इसे वाहन की जगह की जानकारी से जुड़े अपडेट दें. ये अपडेट देने के लिए, इनमें से किसी एक तरीके का इस्तेमाल करें:

  1. ड्राइवर SDK टूल - Android, iOS -- सबसे आसान विकल्प का इस्तेमाल करें.
  2. कस्टम कोड का इस्तेमाल करें -- यह तब फ़ायदेमंद होता है, जब जगहों को आपके बैकएंड के ज़रिए रिले किया जाता हो या Android या iOS के अलावा, किसी दूसरे डिवाइस का इस्तेमाल किया जाता हो.

वाहन के प्रकार

वाहन की इकाई में VehicleType फ़ील्ड शामिल करना ज़रूरी है. इसमें Category ईनम होता है, जिसे AUTO, TAXI, TRUCK, TWO_WHEELER, BICYCLE या PEDESTRIAN में से किसी एक के तौर पर बताया जा सकता है. SearchVehicles और ListVehicles में, वाहन का टाइप फ़िल्टर के मानदंड के तौर पर काम कर सकता है.

अगर कैटगरी को AUTO, TWO_WHEELER, BICYCLE या PEDESTRIAN पर सेट किया गया है, तो वाहनों के लिए सभी रूटिंग, उससे जुड़े RouteTravelMode का इस्तेमाल करेंगे. अगर कैटगरी को TAXI या TRUCK पर सेट किया जाता है, तो रूटिंग को AUTO मोड की तरह ही माना जाता है.

वाहन की विशेषताएं

वाहन की इकाई में, VehicleAttribute का दोहराया गया फ़ील्ड मौजूद है. इन एट्रिब्यूट को फ़्लीट इंजन समझ नहीं लेता. SearchVehicles एपीआई में एक फ़ील्ड शामिल होता है, जिसके लिए वैल्यू के तौर पर Vehicles से मेल खाने वाले सभी एट्रिब्यूट को शामिल करना ज़रूरी होता है.

ध्यान दें कि Vehicle मैसेज में इस्तेमाल किए जा सकने वाले कई फ़ील्ड के साथ-साथ एट्रिब्यूट फ़ील्ड भी होता है. जैसे, vehicle_type और supported_trip_types.

वाहन के लिए बचे हुए वेपॉइंट

वाहन की इकाई में TripWaypoint (RPC | REST) का रिपीटेड फ़ील्ड होता है, जिसे waypoints(RPC | REST) कहा जाता है. इस फ़ील्ड में यात्राओं के बचे हुए वेपॉइंट शामिल होते हैं. इन्हें उसी क्रम में सेट किया जाता है जिस क्रम में वाहन उन तक पहुंचता है. जब वाहन को यात्रा असाइन की जाती है, तो फ़्लीट इंजन इस फ़ील्ड को कैलकुलेट करता है. साथ ही, यात्रा का स्टेटस बदलने पर, वह इस फ़ील्ड को अपडेट भी करता है. इन वेपॉइंट की पहचान, TripId फ़ील्ड और WaypointType फ़ील्ड से की जा सकती है.

मैच के लिए वाहन की ज़रूरी शर्तें पूरी की जा रही हैं

आम तौर पर, वाहनों में यात्रा के अनुरोधों का मिलान करने की ज़िम्मेदारी, राइडशेयर या डिलीवरी की सुविधा देने वाली कंपनी की होती है. यह सेवा, वाहन के एट्रिब्यूट का इस्तेमाल करके कई खोजों में किसी वाहन को शामिल कर सकती है. उदाहरण के लिए, सेवा देने वाली कंपनी, वाहन के दिए जाने वाले फ़ायदों या क्षमताओं के हिसाब से, एट्रिब्यूट का कोई सेट लागू कर सकती है. उदाहरण के लिए, तीन लेवल बूलियन वैल्यू वाले एट्रिब्यूट का सेट हो सकते हैं: is_bronze_level, is_silver_level, और is_gold_level. एक वाहन तीन तरह की ज़रूरी शर्तें पूरी करता है. जब फ़्लीट इंजन को किसी ऐसी यात्रा का अनुरोध मिलता है जिसमें सिल्वर लेवल की क्षमता हो, तो खोज में वह वाहन भी शामिल होता है. इस तरीके से एट्रिब्यूट का इस्तेमाल करने पर, कई तरह की सुविधाएं देने वाले वाहनों को भी शामिल किया जाता है.

वाहन के एट्रिब्यूट अपडेट करने के दो तरीके हैं. एक है, UpdateVehicle एपीआई. इस एपीआई का इस्तेमाल करने पर, वाहन के एट्रिब्यूट का पूरा सेट वैल्यू पर सेट हो जाता है. सिर्फ़ एक एट्रिब्यूट को अपडेट नहीं किया जा सकता. दूसरा तरीका UpdateVehicleAttributes एपीआई है. इस तरीके का इस्तेमाल करने पर, सिर्फ़ एट्रिब्यूट को अपडेट करने में मदद मिलती है. अनुरोध में शामिल एट्रिब्यूट को नई वैल्यू पर सेट किया जाएगा या उन्हें जोड़ा जाएगा. जिन एट्रिब्यूट के बारे में नहीं बताया गया है उनमें कोई बदलाव नहीं किया जाएगा.

कैसे करें: वाहन बनाने का तरीका

हर वाहन को फ़्लीट में ट्रैक करने के लिए, Vehicle इकाई बनानी होगी.

कोई वाहन बनाने के लिए, CreateVehicleRequest के साथ CreateVehicle एंडपॉइंट का इस्तेमाल करें.

Vehicle का provider_id, उस Google Cloud प्रोजेक्ट का प्रोजेक्ट आईडी (जैसे कि my-on-demand-project) होना चाहिए जिसमें वे सेवा खाते हों जिनका इस्तेमाल Fleet Engine को कॉल करने के लिए किया जाएगा. ध्यान दें कि भले ही कई सेवा खाते एक ही राइडशेयर या डिलीवरी देने वाली कंपनी के फ़्लीट इंजन को ऐक्सेस कर सकते हैं, लेकिन फ़िलहाल फ़्लीट इंजन, एक ही Vehicles को ऐक्सेस करने वाले एक से ज़्यादा Google क्लाउड प्रोजेक्ट के सेवा खातों के साथ काम नहीं करता है.

Vehicle को OFFLINE या ONLINE स्थिति में बनाया जा सकता है. अगर ONLINE बनाया गया है, तो इसे SearchVehicles क्वेरी के जवाब में तुरंत लौटाया जा सकता है.

CreateVehicle कॉल में शुरुआती last_location शामिल किए जा सकते हैं. हालांकि, 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

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 के लॉग

CreateVehicle एंडपॉइंट पर कॉल मिलने पर, Fleet Engine API, Google Cloud Platform के लॉग के ज़रिए लॉग एंट्री लिखता है. लॉग एंट्री में, 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 के ज़रिए सूचना पब्लिश करता है. ये सूचनाएं पाने के लिए, कृपया यहां दिए गए निर्देशों का पालन करें.

कैसे करें: वाहन की जगह की जानकारी अपडेट करना

अगर वाहन की जगह की जानकारी अपडेट करने के लिए, ड्राइवर का SDK टूल इस्तेमाल नहीं किया जा रहा है, तो वाहन की जगह की जानकारी के साथ, फ़्लीट इंजन को सीधे कॉल किया जा सकता है. किसी भी चालू वाहन के लिए, Fleet Engine की मदद से, हर मिनट में कम से कम एक बार और हर पांच सेकंड में एक बार जगह की जानकारी अपडेट की जाती है. इन अपडेट के लिए, सिर्फ़ फ़्लीट इंजन ड्राइवर 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

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 को छोड़कर अन्य एट्रिब्यूट को अपडेट करने के लिए, फ़्लीट इंजन के सुपर उपयोगकर्ता के खास अधिकार ज़रूरी हैं.

UpdateVehicleRequest में एक update_mask शामिल होता है, जो यह बताता है कि किन फ़ील्ड को अपडेट करना है. फ़ील्ड उसी तरह काम करता है जैसा फ़ील्ड मास्क के लिए प्रोटोबफ़ दस्तावेज़ में किया गया है.

जैसा कि वाहन के एट्रिब्यूट में बताया गया है, 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

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 के लॉग

UpdateVehicle एंडपॉइंट पर कॉल मिलने पर, Fleet Engine API, Google Cloud Platform के लॉग के ज़रिए लॉग एंट्री लिखता है. लॉग एंट्री में, 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 के ज़रिए सूचना पब्लिश करता है. ये सूचनाएं पाने के लिए, कृपया यहां दिए गए निर्देशों का पालन करें.

कैसे करें: वाहन ढूंढें

फ़्लीट इंजन की मदद से, वाहन खोजने में मदद मिलती है. SearchVehicles एपीआई की मदद से, आपके आस-पास मौजूद उन ड्राइवरों को खोजा जा सकता है जो राइड बुक करने या डिलीवरी का अनुरोध करने जैसे काम के लिए सबसे सही हों. SearchVehicles एपीआई, वाहन के एट्रिब्यूट से मेल खाने वाले टास्क एट्रिब्यूट से मेल खाने वाले ड्राइवर की रैंक की सूची दिखाता है. ज़्यादा जानकारी के लिए, आस-पास मौजूद ड्राइवर ढूंढना देखें.

उदाहरण

उपलब्ध वाहनों की खोज करते समय, फ़्लीट इंजन चालू यात्रा में डिफ़ॉल्ट रूप से वाहनों को शामिल नहीं करता. यह ज़रूरी है कि राइडशेयर या डिलीवरी की सुविधा देने वाली कंपनी की सेवाओं को, खोज के अनुरोधों में साफ़ तौर पर शामिल किया जाए. नीचे दिए गए उदाहरण में, ग्रैंड इंडोनेशिया ईस्ट मॉल से बलाई सिडांग जकार्ता कन्वेंशन सेंटर तक की यात्रा से मिलती-जुलती गाड़ियों की खोज में, उन वाहनों को शामिल करने का तरीका बताया गया है.

शेल

वाहन की जगह की जानकारी अपडेट करें, ताकि वह ज़रूरी शर्तें पूरी कर सके. हालांकि, असल में यह काम, वाहन में चलने वाले Android या iOS डिवाइस पर चल रहे ड्राइवर SDK टूल की मदद से किया जा सकता है.

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 क्लॉज़ के तौर पर काम करती है, जैसे कि SearchVehiclesRequest में minimum_capacity या vehicle_types.

कैसे करें: वाहनों की सूची बनाएं

SearchVehicles को, रैंक किए गए ऑर्डर में कुछ गाड़ियाँ बहुत जल्दी खोजने के लिए ऑप्टिमाइज़ किया गया है. इसका इस्तेमाल मुख्य रूप से आस-पास के उन ड्राइवरों को खोजने के लिए किया जाता है जो काम के हिसाब से सबसे सही हों. हालांकि, कभी-कभी आपको कुछ शर्तों को पूरा करने वाली सभी गाड़ियों को ढूंढना होता है. भले ही, नतीजों को पेज करना ज़रूरी हो. ListVehicles को इस्तेमाल के ऐसे उदाहरण के लिए डिज़ाइन किया गया है.

ListVehicles एपीआई, अनुरोध के कुछ खास विकल्पों को पूरा करने वाली सभी गाड़ियों को खोजने की सुविधा देता है. ListVehicles API, प्रोजेक्ट में मौजूद वाहनों की उन पेजों की सूची दिखाता है जो कुछ ज़रूरी शर्तों को पूरा करती हों.

वाहन के एट्रिब्यूट को फ़िल्टर करने के लिए, कृपया वाहन को फ़िल्टर करने से जुड़ी क्वेरी देखें.

उदाहरण

यह उदाहरण filter स्ट्रिंग का इस्तेमाल करके, vehicle_type और एट्रिब्यूट को फ़िल्टर करता है.

शेल

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

यात्राएं और उनका लाइफ़साइकल

ट्रिप एपीआई और लाइफ़साइकल, वाहन एपीआई और लाइफ़साइकल की तरह ही हैं. फ़्लीट इंजन इंटरफ़ेस का इस्तेमाल करके यात्राएं तैयार करने की ज़िम्मेदारी, राइडशेयर की सुविधा देने वाली कंपनी की है. फ़्लीट इंजन, आरपीसी सेवा TripService और REST रिसॉर्स provider.trips, दोनों उपलब्ध कराता है. ये इंटरफ़ेस, यात्रा की इकाई बनाना, जानकारी के अनुरोध, खोज की सुविधा, और अपडेट की सुविधा को चालू करते हैं.

Trip में स्टेटस फ़ील्ड होता है, ताकि लाइफ़साइकल के ज़रिए इसकी प्रोग्रेस को ट्रैक किया जा सके. वैल्यू, NEW से COMPLETE के साथ CANCELED और UNKNOWN_TRIP_STATUS में बदल जाती हैं. आरपीसी के लिए trip_status या REST के लिए TripStatus देखें.

  • NEW
  • ENROUTE_TO_PICKUP
  • ARRIVED_AT_PICKUP
  • ENROUTE_TO_INTERMEDIATE_DESTINATION
  • ARRIVED_AT_INTERMEDIATE_DESTINATION
  • ENROUTE_TO_DROPOFF
  • COMPLETE

आपकी सेवा इनमें से किसी भी स्थिति से, CANCELED की यात्रा को अपडेट कर सकती है. जब आपकी सेवा कोई यात्रा बनाती है, तो इंजन स्टेटस को NEW के तौर पर सेट करता है. vehicle_id का इस्तेमाल करना ज़रूरी नहीं है. वाहनों की तरह ही, सेवाएं बिना किसी अपडेट के सात दिनों के बाद अपने-आप यात्राएं मिटा देती हैं. अगर आपकी सेवा किसी ऐसे आईडी के साथ यात्रा बनाने की कोशिश करती है जो पहले से मौजूद है, तो एक गड़बड़ी का मैसेज दिखता है. अगर यात्रा की स्थिति COMPLETE या CANCELED के अलावा, किसी और स्थिति में है, तो उसे ‘चालू’ माना जाता है. वाहन की इकाई और SearchTripsRequest के active_trips फ़ील्ड में यह फ़र्क़ अहम होता है.

आपकी सेवा किसी यात्रा के लिए असाइन किए गए vehicle_id को सिर्फ़ तब बदल सकती है, जब यात्रा चालू हो. उदाहरण के लिए, आप ऐसा तब करेंगे, जब कोई ड्राइवर रास्ते के दौरान यात्रा को रद्द कर देता है और यात्रा किसी दूसरे वाहन को फिर से असाइन कर दी जाती है.

एक के बाद एक जाने वाली सहायता लागू करते समय स्थिति अहम होती है. इस सहायता की मदद से, सेवा देने वाली कंपनी किसी वाहन के लिए नई यात्रा असाइन कर सकती है. 'एक के बाद एक यात्रा' बनाने का कोड, एक यात्रा के कोड जैसा ही होता है. साथ ही, इसका कोड एक ही वाहन आईडी का इस्तेमाल किया जाता है. फ़्लीट इंजन, नई यात्रा की शुरुआत की जगह और मंज़िल को वाहन के वेपॉइंट में जोड़ देता है. एक के बाद एक यात्रा करने के बारे में ज़्यादा जानकारी के लिए, एक से ज़्यादा रास्तों वाली यात्राएं बनाना देखें.

यात्रा के लिए बचे हुए वेपॉइंट

यात्रा की इकाई में, TripWaypoint (RPC | REST) का दोहराया गया फ़ील्ड होता है, जिसे remainingWaypoints(RPC | REST) कहा जाता है. इस फ़ील्ड में वे सभी वेपॉइंट शामिल हैं जहां वाहन को इस यात्रा के आखिरी ड्रॉप ऑफ़ पॉइंट से पहले ऑर्डर में यात्रा करनी होगी. यह जानकारी वाहन के बचे हुए वेपॉइंट से ली जाती है. बैक-टू-बैक और कारपूल इस्तेमाल के मामलों में, इस सूची में दूसरी यात्राओं के वेपॉइंट शामिल हैं जो इस यात्रा से पहले देखे जाएंगे. हालांकि, इस यात्रा के बाद वेपॉइंट शामिल नहीं हैं. सूची में वेपॉइंट की पहचान, TripId और WaypointType से की जा सकती है.

यात्रा की स्थिति और वाहन के बचे हुए वेपॉइंट के बीच संबंध

वाहन के बचे हुए वेपॉइंट (आरपीसी | REST) को तब अपडेट किया जाएगा, जब फ़्लीट इंजन को यात्रा के स्टेटस में बदलाव का अनुरोध मिलेगा. tripStatus(RPC | REST) में अन्य स्थिति से ENROUTE_TO_XXX में बदलाव करने पर, पिछले वेपॉइंट को वाहन के बचे हुए वेपॉइंट की सूची से हटा दिया जाएगा. इसका मतलब है कि यात्रा की स्थिति ENROUTE_TO_PICKUP से ARRIVED_AT_PICKUP में बदलने पर भी, यात्रा का पिकअप पॉइंट, वाहन के बाकी वेपॉइंट सूची में ही रहेगा. हालांकि, यात्रा की स्थिति ENROUTE_TO_INTERMEDIATE_DESTINATION या ENROUTE_TO_DROPOFF में बदलने पर, उनका पिकअप पॉइंट, वाहन के बाकी रास्ते से हटा दिया जाएगा.

यह ARRIVED_AT_INTERMEDIATE_DESTINATION और ENROUTE_TO_INTERMDEDIATE_DESTINATION के लिए भी इसी तरह का किराया है. ARRIVED_AT_INTERMEDIATE_DESTINATION में, मौजूदा इंटरमीडिएट डेस्टिनेशन को वाहन के बाकी रास्ते की सूची से तब तक नहीं हटाया जाएगा, जब तक कि वाहन अगले वेपॉइंट पर जाने की सूचना न दे.

यात्रा की स्थिति बदलकर COMPLETED करने पर, इस यात्रा का कोई भी वेपॉइंट, वाहन के बचे हुए वेपॉइंट सूची में नहीं होगा.

कैसे करें: यात्रा बनाएं

यात्रा के हर अनुरोध को ट्रैक करने और उसका फ़्लीट में मौजूद वाहनों से मिलान करने के लिए, एक Trip इकाई होनी चाहिए. यात्रा बनाने के लिए, CreateTripRequest के साथ CreateTrip एंडपॉइंट का इस्तेमाल करें.

यात्रा बनाने के लिए इन एट्रिब्यूट की ज़रूरत होती है:

  • parent - ऐसी स्ट्रिंग जिसमें कंपनी का आईडी शामिल होता है. यह आईडी, Google Cloud प्रोजेक्ट बनने के दौरान बनाया गया था.
  • trip_id - ऐसी स्ट्रिंग जो राइडशेयर की सुविधा देने वाली कंपनी ने बनाई है.
  • trip - यात्रा की जानकारी देने वाला बुनियादी मेटाडेटा वाला कंटेनर.
    • trip_type - इससे पता चलता है कि यात्रा की यात्रा के लिए, एक ही वाहन (SHARED) या सिर्फ़ एक पक्ष (EXCLUSIVE) की यात्रा करने वाले दूसरे यात्री भी हो सकते हैं.
    • pickup_point - TerminalLocation, जो यात्रा के ऑरिजिन पॉइंट को दिखाता है. आरपीसी रेफ़रंस या REST रेफ़रंस देखें

यात्रा बनाते समय number_of_passengers, dropoff_point, और vehicle_id दिए जा सकते हैं. हालांकि, ये फ़ील्ड ज़रूरी नहीं हैं, लेकिन अगर इन्हें सबमिट किया जाता है, तो इन्हें सेव रखा जाता है. यात्रा के दूसरे सभी फ़ील्ड को अनदेखा कर दिया जाता है. उदाहरण के लिए, सभी यात्राएं NEW के trip_status से शुरू होती हैं, भले ही आप बनाने का अनुरोध करते समय CANCELED के trip_status में पास हों.

उदाहरण

नीचे दिए गए उदाहरण में, ग्रैंड इंडोनेशिया ईस्ट मॉल की यात्रा के बारे में बताया गया है. यह यात्रा दो यात्रियों के लिए है और यह खास है. Trip का provider_id और प्रोजेक्ट आईडी एक ही होना चाहिए. उदाहरण में, राइडशेयर की सेवा देने वाली कंपनी ने 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

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 के लॉग

CreateTrip एंडपॉइंट पर कॉल मिलने पर, Fleet Engine API, Google Cloud Platform के लॉग का इस्तेमाल करके लॉग एंट्री लिखता है. लॉग एंट्री में, CreateTrip अनुरोध में दी गई वैल्यू की जानकारी शामिल होती है. अगर कॉल सफल होता है, तो इसमें Trip की जानकारी भी शामिल होगी.

कैसे करें: यात्रा अपडेट करना

यात्रा की इकाई में ऐसे फ़ील्ड होते हैं जो सेवा की मदद से ट्रैकिंग की सुविधा देते हैं. साथ ही, ड्राइवर SDK टूल और उपभोक्ता SDK टूल से यात्रा की जानकारी की जानकारी देने के लिए भी फ़ील्ड मौजूद होते हैं. प्रॉपर्टी अपडेट करने के लिए, UpdateTripRequest मैसेज का इस्तेमाल करें. इससे अनुरोध के field_mask के मुताबिक, यात्रा वाले फ़ील्ड अपडेट हो जाते हैं. UpdateTripRequest देखें.

इन एट्रिब्यूट को अपडेट करने की ज़िम्मेदारी, राइडशेयर की सुविधा देने वाली कंपनी की है:

  • यात्रा की स्थिति.
  • वाहन का आईडी. यात्रा बनाने के समय या वाहन को यात्रा से मैच करने के बाद.
  • पिकअप, ड्रॉपऑफ़ या वेपॉइंट में बदलाव.

ड्राइवर SDK टूल या उपभोक्ता SDK टूल की मदद से, 'गतिविधि शेयर करने की सुविधा' का इस्तेमाल करते समय, फ़्लीट इंजन इन फ़ील्ड को अपने-आप अपडेट कर देता है:

  • रास्ते
  • ईटीए
  • बची हुई दूरी
  • वाहन की जगह की जानकारी
  • शेष वेपॉइंट

आरपीसी में Trip या REST में Resource.Trip देखें.

यात्रा से जुड़े अपडेट के लिए Google Cloud Platform के लॉग

UpdateTrip एंडपॉइंट पर कॉल मिलने पर, Fleet Engine API, Google Cloud Platform के लॉग का इस्तेमाल करके लॉग एंट्री लिखता है. लॉग एंट्री में, UpdateTrip अनुरोध में दी गई वैल्यू की जानकारी शामिल होती है. अगर कॉल पूरा हो जाता है, तो इसमें लौटाए गए Trip की जानकारी भी शामिल होगी.

कैसे करें: सर्च ट्रिप

फ़्लीट इंजन की मदद से, यात्राओं की जानकारी खोजी जा सकती है. जैसा कि पहले बताया गया है, कोई यात्रा सात दिनों के बाद अपने-आप मिट जाती है. इसलिए, SearchTrips सभी यात्राओं का पूरा इतिहास नहीं दिखाता है.

SearchTrips एक सुविधाजनक एपीआई है, लेकिन नीचे दी गई सूची में इस्तेमाल के दो उदाहरण दिए गए हैं.

  • वाहन की चालू यात्राओं की जानकारी तय करना -- सेवा देने वाली कंपनी यह तय कर सकती है कि वाहन में फ़िलहाल कौनसी यात्राएं चालू हैं. SearchTripsRequest में, vehicle_id को उस वाहन पर सेट किया गया है जिस पर विचार किया जा रहा है. साथ ही, active_trips_only को true पर सेट होना चाहिए.

  • सेवा देने वाली कंपनी और फ़्लीट इंजन की स्थिति का मिलान -- सेवा देने वाली कंपनी, अपनी यात्रा की स्थिति और फ़्लीट इंजन की स्थिति की पुष्टि करने के लिए, SearchTrips का इस्तेमाल कर सकती है. TripStatus के लिए यह खास तौर पर ज़रूरी है. अगर वाहन को असाइन की गई यात्रा की स्थिति ठीक से COMPLETE या CANCELED पर सेट नहीं है, तो SearchVehicles ने वाहन को शामिल नहीं किया है.

इस तरह SearchTrips का इस्तेमाल करने के लिए, vehicle_id को खाली छोड़ें, active_trips_only को true पर सेट करें, और minimum_staleness को यात्रा के ज़्यादातर समय से ज़्यादा का समय सेट करें. उदाहरण के लिए, एक घंटे का इस्तेमाल किया जा सकता है. नतीजों में ऐसी यात्राएं शामिल होती हैं जो न तो पूरी हुई हैं और न ही रद्द की गई हैं. साथ ही, जिन्हें एक घंटे से ज़्यादा समय में अपडेट नहीं किया गया है. सेवा देने वाली कंपनी को इन यात्राओं की जांच करनी चाहिए, ताकि यह पक्का किया जा सके कि फ़्लीट इंजन में उनकी स्थिति सही तरीके से अपडेट की गई है.

समस्या हल करना

DEADLINE_EXCEEDED गड़बड़ी होने पर, फ़्लीट इंजन की स्थिति के बारे में जानकारी नहीं है. सेवा देने वाली कंपनी को CreateTrip को फिर से कॉल करना चाहिए, जो कि या तो 201 (CREATED) या 409 (देती है) को फिर से कॉल करता है. बाद वाले मामले में, पिछला अनुरोध DEADLINE_EXCEEDED से पहले सफल रहा. यात्रा से जुड़ी गड़बड़ियों को ठीक करने के बारे में ज़्यादा जानकारी के लिए, Consumer API की गाइड देखें: Android या iOS.

कारपूल राइड सहायता

TripType.SHARED की सुविधा वाले वाहन के लिए, एक से ज़्यादा SHARED यात्राएं असाइन की जा सकती हैं. जब आपने शेयर की गई किसी यात्रा के लिए (CreateTrip या UpdateTrip अनुरोध में) vehicle_id असाइन किया हो, तब आपको Trip.vehicle_waypoints के ज़रिए इस शेयर की गई राइड में, वाहन को असाइन की गई सभी यात्राओं के लिए, पास नहीं किए गए सभी वेपॉइंट का क्रम बताना होगा. आरपीसी के लिए vehicle_waypoints देखें या REST के लिए vehicleWaypoints देखें.

एक से ज़्यादा डेस्टिनेशन मैनेज किए जा सकते हैं

किसी मध्यवर्ती गंतव्य की पहचान करना

यात्रा (RPC | REST) में फ़ील्ड intermediateDestinations और intermediateDestinationIndex फ़ील्ड को डेस्टिनेशन बताने के लिए इस्तेमाल किया जाता है.

इंटरमीडिएट डेस्टिनेशन को अपडेट करें

बीच के डेस्टिनेशन को UpdateTrip की मदद से अपडेट किया जा सकता है. इंटरमीडिएट डेस्टिनेशन अपडेट करते समय, आपको इंटरमीडिएट डेस्टिनेशन की पूरी सूची देनी होगी. इसमें, सिर्फ़ एक नए जोड़े गए या बदलाव किए जाने वाले डेस्टिनेशन की जानकारी शामिल नहीं होगी. जब intermediateDestinationIndex, जोड़े गए/बदले गए इंटरमीडिएट डेस्टिनेशन की स्थिति के बाद इंडेक्स पर ले जाता है, तो नए/अपडेट किए गए इंटरमीडिएट डेस्टिनेशन को वाहन के waypoints या यात्रा के remainingWaypoints में नहीं जोड़ा जाएगा. इसकी वजह यह है कि intermediateDestinationIndex से पहले के सभी इंटरमीडिएट डेस्टिनेशन को पहले ही विज़िट किया जा चुका माना जाता है.

यात्रा की स्थिति में बदलाव

फ़्लीट इंजन को भेजे गए, यात्रा की स्थिति की जानकारी अपडेट करने के अनुरोध में (RPC | REST) फ़ील्ड intermediateDestinationsVersion होना ज़रूरी है. इससे यह पता चलता है कि इंटरमीडिएट डेस्टिनेशन पार हो गई है. टारगेट किए गए इंटरमीडिएट डेस्टिनेशन की जानकारी फ़ील्ड 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 प्रोजेक्ट के बनाए गए विषय पर सूचनाएं पब्लिश करता है. आपके Google Cloud प्रोजेक्ट में, फ़्लीट इंजन के लिए Pub/Sub डिफ़ॉल्ट रूप से चालू नहीं होता. Pub/Sub को चालू करने के लिए, कृपया सहायता मामला दर्ज करें या अपने ग्राहक इंजीनियर से संपर्क करें.

अपने Cloud प्रोजेक्ट के लिए विषय बनाने के लिए, इन निर्देशों का पालन करें. विषय का आईडी 'fleet_engine_Notification' होना चाहिए.

विषय उसी Cloud प्रोजेक्ट में बनाया जाना चाहिए जो Fleet Engine API को कॉल कर रहा है.

विषय बनाने के बाद, आपको उस विषय पर पब्लिश करने के लिए, Fleet Engine API को अनुमति देनी होगी. ऐसा करने के लिए, अपने अभी बनाए गए विषय पर क्लिक करें और नई अनुमति जोड़ें. अनुमतियों में बदलाव करने वाला टूल खोलने के लिए, आपको जानकारी पैनल दिखाएं पर क्लिक करना पड़ सकता है. मुख्य खाता geo-fleet-engine@system.gserviceaccount.com होना चाहिए और भूमिका Pub/Sub publisher होनी चाहिए.

सूचनाएं पाने की सदस्यता लेने के लिए अपना क्लाउड प्रोजेक्ट सेट अप करने के लिए, इन निर्देशों का पालन करें

Fleet Engine API हर सूचना को दो अलग-अलग डेटा फ़ॉर्मैट में पब्लिश करेगा, 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"
    }
  }
}