הצטרפו אלינו לאירוע הבא של Google Maps Platform Developer Community Day בסן פרנסיסקו בדצמבר. להגשת בקשה להשתתפות.

‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

הגדרת Address Validation API

מפתחים באזור הכלכלי האירופי (EEA)

במאמר הזה מוסבר איך להתחיל להשתמש ב-Address Validation API.

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

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

בודקים את החיוב והעלות של השימוש ב-Address Validation API במאמר שימוש וחיוב ב-Address Validation API.
מוודאים שיש לכם חשבון Google Cloud.
נכנסים למסוף Google Cloud
הערה: אם אתם משתמשים חדשים ואין לכם חשבון Google Cloud, כלומר אתם לא יכולים להיכנס למסוף, קראו את המאמר תחילת השימוש ב-Google Maps Platform.
מוודאים שיש לכם פרויקט ב-Google Cloud שהחיוב מופעל בו.
כניסה לדף Billing
הערה: אם אתם משתמשים חדשים ואין לכם פרויקט ב-Google Cloud, קראו את המאמר תחילת השימוש בפלטפורמה של מפות Google.

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

הפעלת ה-API

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

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

המסוף

פותחים את דף המוצר במסוף Google Cloud:
הפעלת Address Validation API
לוחצים על הכפתור הפעלה.

הערה: אם ה-API כבר מופעל, הלחצן Manage מופיע במקום Enable.

gcloud

gcloud services enable \
    --project &quot;PROJECT" \
    "addressvalidation.googleapis.com"

מידע נוסף על Google Cloud SDK, התקנת Cloud SDK והפקודות הבאות:

קבלת מפתח API לשימוש עם Address Validation API

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

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

המסוף

נכנסים לדף Google Maps Platform > Keys & Credentials.

כניסה לדף Keys & Credentials
אם מתבקשים, בוחרים את הפרויקט.
מבצעים אחת מהפעולות האלה:
- יצירת מפתח חדש:
  1. לוחצים על Create credentials > מפתח API.
  2. בחלונית יצירת מפתח API, פותחים את הרשימה בחירת הגבלות API.
  3. מבטלים את הבחירה בכל ממשקי ה-API שהמפתח הזה לא צריך, ומוודאים שהאפשרות Address Validation API נשארת מסומנת.
  4. לוחצים על יצירה. בחלונית מוצג מפתח ה-API החדש.
- שימוש במפתח קיים:
  1. לוחצים על שם המפתח.
  2. ברשימה Select API restrictions, בוחרים באפשרות Address Validation API.
  3. לוחצים על שמירה.
בחירת API כאן לא מפעילה אותו. מוודאים ש-Address Validation API מופעל בדף ספריית ה-API שלו.
כדי לראות את מחרוזת המפתח מאוחר יותר, עוברים לדף Keys & Credentials ולוחצים על Show key ליד המפתח.

אם המסוף נראה שונה מהשלבים האלה, עיינו במאמרים יצירת מפתח API והוספת הגבלות על API במסמכי התיעוד של Google Cloud.

gcloud

בפקודות הבאות, מחליפים את PROJECT_ID במזהה הפרויקט.

יצירת מפתח חדש: מריצים את הפקודה הבאה ומחליפים את DISPLAY_NAME בשם של המפתח.
```
gcloud services api-keys create \
    --project=&quot;PROJECT_ID" \
    --display-name=&quot;DISPLAY_NAME" \
    --api-target=service=addressvalidation.googleapis.com
```
מידע נוסף על Google Cloud SDK, התקנת Cloud SDK והפקודות הבאות:
- gcloud services api-keys create
שימוש במפתח קיים: מריצים את הפקודה הבאה ומחליפים את KEY_ID במזהה המפתח. הדגל --append שומר על ממשקי ה-API שהמפתח כבר מאפשר. בלעדיו, הפקודה מחליפה אותם.
```
gcloud services api-keys update KEY_ID \
    --project=&quot;PROJECT_ID" \
    --append \
    --api-target=service=addressvalidation.googleapis.com
```
מידע נוסף על Google Cloud SDK, התקנת Cloud SDK והפקודות הבאות:
- gcloud services api-keys update
- gcloud services api-keys list
מזהה המפתח הוא לא מחרוזת המפתח או השם המוצג. כדי למצוא אותו, מריצים את הפקודה gcloud services api-keys list --project="PROJECT_ID". המזהה הוא החלק האחרון בשדה name: projects/PROJECT_NUMBER/locations/global/keys/KEY_ID.

כדי לראות את מחרוזת המפתח, מריצים את הפקודה gcloud services api-keys get-key-string KEY_ID --project="PROJECT_ID".

שליחת בקשת API

שולחים בקשת API ל-Address Validation API כדי לקבל תשובה בפורמט JSON לאימות הכתובת "1600 Amphitheatre Parkway, Mountain View, CA". בכל בקשה צריך לכלול את המחרוזת האלפאנומרית של מפתח ה-API, ולהשתמש ב-HTTPS בבקשות שכוללות את מפתח ה-API.

לוחצים על API_KEY בקוד שבהמשך כדי להוסיף את המחרוזת האלפאנומרית של המפתח:

curl -X POST -d '{
  "address": {
    "regionCode": "US",
    "locality": "Mountain View",
    "addressLines": ["1600 Amphitheatre Pkwy"]
  }
}' \
-H 'Content-Type: application/json' \
"https://addressvalidation.googleapis.com/v1:validateAddress?key=API_KEY"

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

התגובה היא אובייקט JSON בפורמט הבא:

{
  "result": {
    "verdict": {
      "inputGranularity": "PREMISE",
      "validationGranularity": "PREMISE",
      "geocodeGranularity": "PREMISE",
      "addressComplete": true,
      "hasInferredComponents": true
    },
    "address": {
      "formattedAddress": "1600 Amphitheatre Parkway, Mountain View, CA 94043-1351, USA",
      "postalAddress": {
        "regionCode": "US",
        "languageCode": "en",
        "postalCode": "94043-1351",
        "administrativeArea": "CA",
        "locality": "Mountain View",
        "addressLines": [
          "1600 Amphitheatre Pkwy"
        ]
      },
      "addressComponents": [
        {
          "componentName": {
            "text": "1600"
          },
          "componentType": "street_number",
          "confirmationLevel": "CONFIRMED"
        },
        {
          "componentName": {
            "text": "Amphitheatre Parkway",
            "languageCode": "en"
          },
          "componentType": "route",
          "confirmationLevel": "CONFIRMED"
        },
        {
          "componentName": {
            "text": "Mountain View",
            "languageCode": "en"
          },
          "componentType": "locality",
          "confirmationLevel": "CONFIRMED"
        },
        {
          "componentName": {
            "text": "USA",
            "languageCode": "en"
          },
          "componentType": "country",
          "confirmationLevel": "CONFIRMED"
        },
        {
          "componentName": {
            "text": "94043"
          },
          "componentType": "postal_code",
          "confirmationLevel": "CONFIRMED",
          "inferred": true
        },
        {
          "componentName": {
            "text": "CA",
            "languageCode": "en"
          },
          "componentType": "administrative_area_level_1",
          "confirmationLevel": "CONFIRMED",
          "inferred": true
        },
        {
          "componentName": {
            "text": "1351"
          },
          "componentType": "postal_code_suffix",
          "confirmationLevel": "CONFIRMED",
          "inferred": true
        }
      ]
    },
    "geocode": {
      "location": {
        "latitude": 37.4225022,
        "longitude": -122.0847398
      },
      "plusCode": {
        "globalCode": "849VCWF8+24"
      },
      "bounds": {
        "low": {
          "latitude": 37.4225022,
          "longitude": -122.0847398
        },
        "high": {
          "latitude": 37.4225022,
          "longitude": -122.0847398
        }
      },
      "placeId": "ChIJF4Yf2Ry7j4AR__1AkytDyAE",
      "placeTypes": [
        "street_address"
      ]
    },
    "metadata": {
      "business": true,
      "residential": false
    },
    "uspsData": {
      "standardizedAddress": {
        "firstAddressLine": "1600 AMPHITHEATRE PKWY",
        "cityStateZipAddressLine": "MOUNTAIN VIEW CA 94043-1351",
        "city": "MOUNTAIN VIEW",
        "state": "CA",
        "zipCode": "94043",
        "zipCodeExtension": "1351"
      },
      "deliveryPointCode": "00",
      "deliveryPointCheckDigit": "0",
      "dpvConfirmation": "Y",
      "dpvFootnote": "AABB",
      "dpvCmra": "N",
      "dpvVacant": "N",
      "dpvNoStat": "Y",
      "carrierRouteIndicator": "D",
      "postOfficeCity": "MOUNTAIN VIEW",
      "postOfficeState": "CA",
      "fipsCountyCode": "085",
      "county": "SANTA CLARA",
      "elotNumber": "0103",
      "elotFlag": "A",
      "addressRecordType": "S",
      "dpvNoStatReasonCode": 5,
      "dpvDrop": "N",
      "dpvThrowback": "N",
      "dpvNonDeliveryDays": "N",
      "dpvNoSecureLocation": "N",
      "dpvPbsa": "N",
      "dpvDoorNotAccessible": "N",
      "dpvEnhancedDeliveryCode": "Y"
    }
  },
  "responseId": "a3d051f9-a802-4d8a-b530-46ee45903453"
}

החלת הגבלות על מפתחות API

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

הגבלות על ממשקי API מציינות לאילו ערכות SDK וממשקי API אפשר לקרוא באמצעות מפתח ה-API. כשיוצרים מפתח במסוף וב-CLI של gcloud, צריך להגדיר לפחות הגבלה אחת ל-API.
הגבלות על אפליקציות מציינות אילו כתובות IP, אפליקציות ואתרים יכולים להשתמש במפתח API.

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

יצירת טוקן OAuth

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

מתקינים ומפעילים את ה-CLI של gcloud. למידע נוסף, קראו את המאמר התקנת ה-CLI של gcloud.
אימות באמצעות ה-CLI של gcloud:
```
gcloud auth application-default login
```
משלימים את תהליך הכניסה כדי לשמור את פרטי הכניסה בקובץ פרטי הכניסה המקומי שמשמש את 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.

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

בדוגמת הקוד הבאה, מחליפים את PROJECT_ID במזהה הפרויקט ב-Google Cloud:

curl -X POST -d '{
"address": {
"regionCode": "US",
"locality": "Mountain View",
"addressLines": ["1600 Amphitheatre Pkwy"]
}
}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://addressvalidation.googleapis.com/v1:validateAddress"

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

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

{
  "result": {
    "verdict": {
      "inputGranularity": "PREMISE",
      "validationGranularity": "PREMISE",
      "geocodeGranularity": "PREMISE",
      "addressComplete": true,
      "hasInferredComponents": true
    },
    "address": {
      "formattedAddress": "1600 Amphitheatre Parkway, Mountain View, CA 94043-1351, USA",
      "postalAddress": {
        "regionCode": "US",
        "languageCode": "en",
        "postalCode": "94043-1351",
        "administrativeArea": "CA",
        "locality": "Mountain View",
        "addressLines": [
          "1600 Amphitheatre Pkwy"
        ]
      },
      "addressComponents": [
        {
          "componentName": {
            "text": "1600"
          },
          "componentType": "street_number",
          "confirmationLevel": "CONFIRMED"
        },
        {
          "componentName": {
            "text": "Amphitheatre Parkway",
            "languageCode": "en"
          },
          "componentType": "route",
          "confirmationLevel": "CONFIRMED"
        },
        {
          "componentName": {
            "text": "Mountain View",
            "languageCode": "en"
          },
          "componentType": "locality",
          "confirmationLevel": "CONFIRMED"
        },
        {
          "componentName": {
            "text": "USA",
            "languageCode": "en"
          },
          "componentType": "country",
          "confirmationLevel": "CONFIRMED"
        },
        {
          "componentName": {
            "text": "94043"
          },
          "componentType": "postal_code",
          "confirmationLevel": "CONFIRMED",
          "inferred": true
        },
        {
          "componentName": {
            "text": "CA",
            "languageCode": "en"
          },
          "componentType": "administrative_area_level_1",
          "confirmationLevel": "CONFIRMED",
          "inferred": true
        },
        {
          "componentName": {
            "text": "1351"
          },
          "componentType": "postal_code_suffix",
          "confirmationLevel": "CONFIRMED",
          "inferred": true
        }
      ]
    },
    "geocode": {
      "location": {
        "latitude": 37.4225022,
        "longitude": -122.0847398
      },
      "plusCode": {
        "globalCode": "849VCWF8+24"
      },
      "bounds": {
        "low": {
          "latitude": 37.4225022,
          "longitude": -122.0847398
        },
        "high": {
          "latitude": 37.4225022,
          "longitude": -122.0847398
        }
      },
      "placeId": "ChIJF4Yf2Ry7j4AR__1AkytDyAE",
      "placeTypes": [
        "street_address"
      ]
    },
    "metadata": {
      "business": true,
      "residential&quot;: false
    },
    "uspsData": {
      "standardizedAddress": {
        "firstAddressLine": "1600 AMPHITHEATRE PKWY",
        "cityStateZipAddressLine": "MOUNTAIN VIEW CA 94043-1351",
        "city": "MOUNTAIN VIEW",
        "state": "CA",
        "zipCode": "94043",
        "zipCodeExtension": "1351"
      },
      "deliveryPointCode": "00",
      "deliveryPointCheckDigit": "0",
      "dpvConfirmation": "Y",
      "dpvFootnote": "AABB",
      "dpvCmra": "N",
      "dpvVacant": "N",
      "dpvNoStat": "Y",
      "carrierRouteIndicator": "D",
      "postOfficeCity": "MOUNTAIN VIEW",
      "postOfficeState": "CA",
      "fipsCountyCode": "085",
      "county": "SANTA CLARA",
      "elotNumber": "0103",
      "elotFlag": "A",
      "addressRecordType": "S",
      "dpvNoStatReasonCode": 5,
      "dpvDrop": "N",
      "dpvThrowback": "N",
      "dpvNonDeliveryDays": "N",
      "dpvNoSecureLocation": "N",
      "dpvPbsa": "N",
      "dpvDoorNotAccessible": "N",
      "dpvEnhancedDeliveryCode": "Y"
    }
  },
  "responseId": "fac2ae1b-50ce-442c-8bc3-d459039950ef"
}

פתרון בעיות

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

המאמרים הבאים

עכשיו, אחרי שהפעלתם את Address Validation API ושלחתם בקשה בהצלחה, אתם יכולים לקרוא את המאמרים שליחת בקשה לאימות כתובת והסבר על תגובה בסיסית לאימות כתובת כדי לקבל מידע נוסף על השימוש ב-API.

הגדרת Address Validation API קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

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

הפעלת ה-API

המסוף

gcloud

קבלת מפתח API לשימוש עם Address Validation API

המסוף

gcloud

שליחת בקשת API

החלת הגבלות על מפתחות API

יצירת טוקן OAuth

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

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

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

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

שליחת בקשת REST

פתרון בעיות

המאמרים הבאים

הגדרת Address Validation API