הגדרת Route Optimization API

במאמר הזה מוסבר איך מתחילים להשתמש ב-Route Optimization API.

דרישות מוקדמות

כאן נסביר איך מגדירים חשבון Google Cloud ופרויקט בענן ב-Google Cloud עם חיוב מופעל. אתם צריכים גם להכיר את אופן החיוב על השימוש ב-Route Optimization API.

1. בדיקת החיוב והעלות של השימוש ב-Route Optimization API.

2. מוודאים שיש לכם חשבון Google Cloud.

   נכנסים למסוף Google Cloud

3. מוודאים שיש לכם פרויקט ב-Google Cloud שהחיוב מופעל בו.

   כניסה לדף Billing
1. בוחרים את הפרויקט כדי לפתוח את הדף Billing.

2. בדף Billing:

   • אם החיוב כבר מופעל בפרויקט שנבחר ויש לכם רק חשבון לחיוב אחד, ייפתח הדף Billing.
   • אם יש לכם כמה חשבונות לחיוב, לוחצים על Go to linked billing account כדי לראות את הפרטים של החשבון לחיוב שמשויך לפרויקט.
   • אם קיים חשבון לחיוב אבל הוא לא משויך לפרויקט, תתבקשו לקשר חשבון לחיוב לפרויקט.
   • אם אין חשבון לחיוב או שרוצים ליצור חשבון חדש, בוחרים באפשרות Manage Billing Accounts כדי ליצור חשבון חדש לחיוב. למידע נוסף, קראו את המאמר איך יוצרים חשבון חדש לחיוב ב-Cloud בשירות עצמי.

הפעלת ה-API

כדי להשתמש ב-Route Optimization API, צריך להפעיל אותו בפרויקט ב-Google Cloud באמצעות מסוף Google Cloud או הפקודה gcloud.

כדי להפעיל את ה-API:

gcloud services enable \
    --project "PROJECT" \
    "routeoptimization.googleapis.com"

כדי למנוע שימוש לא מורשה, במוצרים של Google Maps Platform צריך לכלול אסימון OAuth בקריאות ל-API.

יצירת טוקן OAuth

‫Route Optimization API תומך ב-OAuth 2.0 לצורך אימות. ‫Google תומכת בתרחישים נפוצים של OAuth 2.0, כמו תרחישים של שרת אינטרנט.

במאמר הזה מוסבר איך להעביר אסימון OAuth לקריאה ל-Route Optimization API בסביבת הפיתוח. למידע נוסף על השימוש ב-OAuth בסביבת ייצור, קראו את המאמר שיטות אימות ב-Google.

אתם יכולים לשלוח בקשות API ישירות לשרת של Google Maps API, או להשתמש בספריות לקוח כדי לפשט את הקוד. במפות Google יש ספריות לקוח ל-Go, ל-Java, ל-Node.js ול-Python. מידע נוסף זמין במאמר ספריות הלקוח של Route Optimization API.

סקירה כללית על OAuth

יש כמה דרכים ליצור ולנהל טוקני גישה באמצעות OAuth, בהתאם לסביבת הפריסה.

אתם יכולים להשתמש ב-OAuth 2.0 לאינטראקציות משרת-אל-שרת בין האפליקציה שלכם לשירות של Google. בתרחיש הזה, אתם משתמשים בחשבון שירות שמשויך לאפליקציה שלכם ולא למשתמש ספציפי. אתם יכולים לשלוח בקשות API באמצעות חשבון השירות בלי לערב משתמשים באופן ישיר. למידע נוסף על שיטות אימות, ראו שיטות אימות ב-Google.

לחלופין, אתם יכולים לשלב את Route Optimization API באפליקציה לנייד ל-Android או ל-iOS. מידע נוסף על השימוש ב-OAuth ועל ניהול טוקני גישה לסביבות פריסה שונות זמין במאמר שימוש ב-OAuth 2.0 לגישה ל-Google APIs.

היקפי ההרשאות של OAuth

כדי להשתמש ב-OAuth עם Route Optimization API, צריך להקצות לטוקן OAuth את היקף ההרשאות הבא:

https://www.googleapis.com/auth/cloud-platform

הגדרת תפקידים

במאמר הזה מוסבר על התפקידים וההרשאות של ניהול זהויות והרשאות גישה (IAM) ב-Route Optimization. בעזרת IAM תוכלו לתת גישה פרטנית למשאבים ספציפיים של Route Optimization, ולמנוע גישה למשאבים אחרים. בעזרת IAM תוכלו לשמור על העקרון של הרשאות אבטחה מינימליות, כדי שלאף אחד לא יהיו יותר הרשאות ממה שנדרש לו בפועל.

כשחשבון משתמש (משתמש, קבוצה או חשבון שירות) קורא ל-Google Cloud API, צריכות להיות לו הרשאות IAM מתאימות כדי להשתמש במשאב. כדי לתת לחשבון משתמש את ההרשאות הנדרשות, מקצים לו תפקיד ב-IAM.

כדי להכיר את ניהול הגישה ב-Google Cloud באופן כללי, קראו את הסקירה הכללית על IAM.

אלה התפקידים המוגדרים מראש ב-IAM שמאפשרים לחשבונות משתמשים לגשת ל-Route Optimization:

• ‫Route Optimization Editor (roles/routeoptimization.editor): מעניקה למשתמש או לחשבון השירות גישת קריאה וכתיבה למשאבים של Route Optimization בפרויקט. ההרשאה הזו כוללת את היכולת להפעיל את OptimizeTours ואת BatchOptimizeTours, וגם לאחזר פעולות ממושכות באמצעות GetOperation.
• ‫Route Optimization Viewer (roles/routeoptimization.viewer): הרשאת קריאה בלבד למשאבים של אופטימיזציית מסלולים בפרויקט. התפקיד הזה מאפשר להפעיל את OptimizeTours ולגשת לפעולות ארוכות באמצעות GetOperation.

gcloud projects add-iam-policy-binding PROJECT \
  --member user:someone@example.com \
  --role roles/routeoptimization.editor

מידע נוסף זמין במאמר הקצאת תפקיד ב-IAM באמצעות מסוף Google Cloud.

דוגמה: ניסיון של קריאות ל-API בארכיטקטורת REST בסביבת הפיתוח המקומית

אם אין לכם סביבה שיוצרת טוקנים ואתם רוצים לנסות את Route Optimization API עם טוקן OAuth, אתם יכולים להשתמש בתהליך שמתואר בקטע הזה.

בדוגמה הזו נסביר איך להשתמש באסימון OAuth שסופק על ידי Application Default Credentials ‏ (ADC) כדי לבצע את הקריאה. במאמר אימות לשירותי Cloud באמצעות ספריות לקוח תוכלו ללמוד איך משתמשים ב-ADC כדי לקרוא ל-Google APIs באמצעות ספריות לקוח.

התהליך הבא של REST מיועד רק לפיתוח או לבדיקה, ולא לייצור.

דרישות מוקדמות

לפני ששולחים בקשת REST באמצעות ADC, צריך להשתמש ב-CLI של gcloud כדי לספק את פרטי הכניסה ל-ADC:

1. מתקינים ומפעילים את ה-CLI של gcloud. למידע נוסף, קראו את המאמר התקנת ה-CLI של gcloud.

2. אימות באמצעות ה-CLI של gcloud:

   gcloud auth application-default login

3. משלימים את תהליך הכניסה כדי לשמור את פרטי הכניסה בקובץ פרטי הכניסה המקומי שמשמש את ADC.

מידע נוסף זמין במאמר הגדרת ADC לסביבת פיתוח מקומית.

שליחת בקשת REST

בדוגמה הזו, אתם מעבירים שתי כותרות של בקשות:

• מעבירים את טוקן ה-OAuth בכותרת Authorization באמצעות הפקודה הבאה כדי ליצור את הטוקן:

  gcloud auth application-default print-access-token

  האסימון שמוחזר כולל את ההיקף https://www.googleapis.com/auth/cloud-platform.

• מעבירים את המזהה או השם של פרויקט בענן ב-Google Cloud שמופעל בו חיוב בכותרת X-Goog-User-Project.

כדי לשלוח קריאה ל-Route Optimization API באמצעות אסימון OAuth:

1. בדוגמת הקוד הבאה, מחליפים את PROJECT_NUMBER_OR_ID במספר או במזהה של הפרויקט ב-Google Cloud:

   curl -X POST 'https://routeoptimization.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID:optimizeTours' \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
   --data-binary @- << EOM
   {
   "model": {
   "shipments": [
     {
       "pickups": [
         {
           "arrivalLocation": {
             "latitude": 37.73881799999999,
             "longitude": -122.4161
           }
         }
       ],
       "deliveries": [
         {
           "arrivalLocation": {
             "latitude": 37.79581,
             "longitude": -122.4218856
           }
         }
       ]
     }
   ],
   "vehicles": [
     {
       "startLocation": {
         "latitude": 37.73881799999999,
         "longitude": -122.4161
       },
       "endLocation": {
         "latitude": 37.73881799999999,
         "longitude": -122.4161
       }
     }
   ],
   "globalStartTime": "2023-01-13T16:00:00-08:00",
   "globalEndTime": "2023-01-14T16:00:00-08:00"
   }
   }
   EOM
   

2. כדי להעתיק את הפקודה curl, לוחצים על Copy בדוגמת הקוד.

3. מדביקים את הפקודה בחלון הטרמינל ומריצים אותה.

התגובה היא אובייקט JSON:

{
  "routes": [
    {
      "vehicleStartTime": "2023-01-14T00:00:00Z",
      "vehicleEndTime": "2023-01-14T00:39:22Z",
      "visits": [
        {
          "isPickup": true,
          "startTime": "2023-01-14T00:00:00Z",
          "detour": "0s"
        },
        {
          "startTime": "2023-01-14T00:19:53Z",
          "detour": "0s"
        }
      ],
      "transitions": [
        {
          "travelDuration": "0s",
          "waitDuration": "0s",
          "totalDuration": "0s",
          "startTime": "2023-01-14T00:00:00Z"
        },
        {
          "travelDuration": "1193s",
          "travelDistanceMeters": 9007,
          "waitDuration": "0s",
          "totalDuration": "1193s",
          "startTime": "2023-01-14T00:00:00Z"
        },
        {
          "travelDuration": "1169s",
          "travelDistanceMeters": 9546,
          "waitDuration": "0s",
          "totalDuration": "1169s",
          "startTime": "2023-01-14T00:19:53Z"
        }
      ],
      "metrics": {
        "performedShipmentCount": 1,
        "travelDuration": "2362s",
        "waitDuration": "0s",
        "delayDuration": "0s",
        "breakDuration": "0s",
        "visitDuration": "0s",
        "totalDuration": "2362s",
        "travelDistanceMeters": 18553
      }
    }
  ],
  "metrics": {
    "aggregatedRouteMetrics": {
      "performedShipmentCount": 1,
      "travelDuration": "2362s",
      "waitDuration": "0s",
      "delayDuration": "0s",
      "breakDuration": "0s",
      "visitDuration": "0s",
      "totalDuration": "2362s",
      "travelDistanceMeters": 18553
    },
    "usedVehicleCount": 1,
    "earliestVehicleStartTime": "2023-01-14T00:00:00Z",
    "latestVehicleEndTime": "2023-01-14T00:39:22Z"
  }
}

פתרון בעיות

אם הבקשה מחזירה הודעת שגיאה שלפיה ה-API לא תומך בפרטי הכניסה של משתמשי הקצה, עיינו בקטע פתרון בעיות בהגדרות של ADC.