راه‌اندازی Address Validation API

توسعه‌دهندگان منطقه اقتصادی اروپا (EEA)

این سند مراحلی را که برای شروع استفاده از Address Validation API لازم است شرح می‌دهد.

پیش‌نیازها

این رویه شما را در راه‌اندازی کردن «حساب Google Cloud» و پروژه Google Cloud با صورت‌حساب فعال راهنمایی می‌کند. همچنین باید با نحوه کسر هزینه برای استفاده از Address Validation API آشنا باشید.

  1. مرور صورت‌حساب و هزینه استفاده در استفاده و صورت‌حساب Address Validation API.

  2. تأیید کنید که حساب Google Cloud دارید.

    به سیستم کنسول Google Cloud وارد شوید

  3. تأیید کنید که پروژه Google Cloud با صورت‌حساب فعال دارید.

    رفتن به صفحه «صورت‌حساب»
    1. پروژه‌تان را انتخاب کنید تا صفحه صورت‌حساب باز شود.

    2. در صفحه صورت‌حساب:

      • اگر صورت‌حساب ازقبل برای پروژه انتخاب‌شده فعال شده باشد و فقط یک حساب صورت‌حساب داشته باشید، صفحه صورت‌حساب باز می‌شود.
      • اگر چند حساب صورت‌حساب دارید، رفتن به حساب صورت‌حساب پیوندشده را انتخاب کنید تا جزئیات مربوط به حساب صورت‌حساب مرتبط با پروژه را ببینید.
      • اگر حساب صورت‌حساب وجود داشته باشد اما با پروژه مرتبط نباشد، از شما خواسته می‌شود حساب صورت‌حساب را به پروژه پیوند دهید.
      • اگر حساب صورت‌حسابی وجود ندارد، یا می‌خواهید حساب صورت‌حساب جدیدی ایجاد کنید، مدیریت حساب‌های صورت‌حساب را انتخاب کنید تا حساب صورت‌حساب جدیدی ایجاد کنید. برای اطلاعات بیشتر، ایجاد حساب Cloud Billing سلف سرویس جدید را ببینید.

فعال کردن میانای برنامه‌سازی کاربردی

قبل‌از اینکه بتوانید از Address Validation API استفاده کنید، باید از کنسول Google Cloud یا فرمان gcloud برای فعال کردن آن در پروژه Google Cloud خود استفاده کنید.

برای فعال کردن میانای برنامه‌سازی کاربردی:

کنسول

  1. صفحه محصول را در کنسول Google Cloud باز کنید:

    فعال کردن Address Validation API

  2. روی دکمه فعال کردن کلیک کنید.

gcloud

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

درباره کیت توسعه نرم‌افزار Google Cloud، نصب کیت توسعه نرم‌افزار Cloud، و فرمان‌های زیر بیشتر بخوانید:

دریافت کلید میانای برنامه‌سازی کاربردی برای استفاده با Address Validation API

محصولات Google Maps Platform با الزام تماس‌های میانای برنامه‌سازی کاربردی به داشتن کلید میانای برنامه‌سازی کاربردی یا کد OAuth دربرابر استفاده غیرمجاز محافظت می‌شوند. رویه کلید میانای API در اولویت است. برای استفاده از کد OAuth به‌جای آن، ایجاد کد OAuth را ببینید.

کلید میانای برنامه‌سازی کاربردی رشته حرفی‌عددی منحصربه‌فردی است که حساب Cloud Billing و پروژه Google Cloud شما را با درخواستی که برنامه‌تان از میانای برنامه‌سازی کاربردی یا کیت توسعه نرم‌افزار Google Maps Platform می‌کند مرتبط می‌کند. برای ایجاد کلید جدید یا افزودن میانای برنامه‌سازی کاربردی یا کیت توسعه نرم‌افزار به کلید موجود، این دستورالعمل‌ها را دنبال کنید.

کنسول

  1. به صفحه پلاتفرم Google Maps > کلیدها و اطلاعات کاربری بروید.

    به صفحه «کلیدها و اعتبارنامه‌ها» بروید

  2. اگر درخواست شد، پروژه‌تان را انتخاب کنید.

  3. یکی از موارد زیر را انجام دهید:

    • ایجاد کلید جدید:

      1. روی ایجاد اطلاعات کاربری > کلید میانای API کلیک کنید.
      2. در پانل ایجاد کلید میانای API، فهرست انتخاب محدودیت‌های میانای API را باز کنید.
      3. هر میانای برنامه‌سازی کاربردی را که این کلید به آن نیاز ندارد پاک کنید و مطمئن شوید Address Validation API همچنان انتخاب شده باشد.
      4. روی ایجاد کردن کلیک کنید. پانل کلید میانای برنامه‌سازی کاربردی جدیدتان را نمایش می‌دهد.

    • استفاده از کلید موجود:

      1. روی نام کلید کلیک کنید.
      2. در فهرست انتخاب محدودیت‌های API، Address Validation API را انتخاب کنید.
      3. روی ذخیره کلیک کنید.

    انتخاب کردن میانای برنامه‌سازی کاربردی در اینجا آن را فعال نمی‌کند. مطمئن شوید Address Validation API در صفحه کتابخانه میانای برنامه‌سازی کاربردی آن فعال باشد.

  4. برای دیدن رشته کلید در آینده، به صفحه کلیدها و اطلاعات کاربری بروید و روی نمایش کلید برای کلید کلیک کنید.

اگر کنسول با این مراحل متفاوت است، ایجاد کلید میانای برنامه‌سازی کاربردی و افزودن محدودیت‌های کلید میانای برنامه‌سازی کاربردی را در اسناد Google Cloud ببینید.

gcloud

در فرمان‌های زیر، PROJECT_ID را با شناسه پروژه‌تان جایگزین کنید.

  • ایجاد کلید جدید: فرمان زیر را اجرا کنید و DISPLAY_NAME را با نامی برای کلید جایگزین کنید. 

    gcloud services api-keys create \
    --project="PROJECT_ID" \
    --display-name="DISPLAY_NAME" \
    --api-target=service=addressvalidation.googleapis.com

    درباره کیت توسعه نرم‌افزار Google Cloud، نصب کیت توسعه نرم‌افزار Cloud، و فرمان‌های زیر بیشتر بخوانید:

  • استفاده از کلید موجود: فرمان زیر را اجرا کنید و KEY_ID را با شناسه کلید جایگزین کنید. پرچم --append میاناهای برنامه‌سازی کاربردی را که کلید ازقبل مجاز کرده است حفظ می‌کند. بدون آن، فرمان جایگزین آن‌ها می‌شود.

    gcloud services api-keys update KEY_ID \
    --project="PROJECT_ID" \
    --append \
    --api-target=service=addressvalidation.googleapis.com

    درباره کیت توسعه نرم‌افزار Google Cloud، نصب کیت توسعه نرم‌افزار Cloud، و فرمان‌های زیر بیشتر بخوانید:

    شناسه کلید، رشته کلید یا نام نمایشی نیست. برای پیدا کردن آن، 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" را اجرا کنید.

درخواست دادن به میانای برنامه‌سازی کاربردی

درخواست Address Validation API را برای برگرداندن پاسخ JSON برای اعتبارسنجی نشانی «1600 Amphitheatre Parkway, Mountain View, CA» ایجاد کنید. باید رشته الفبانمایی کلید میانای برنامه‌سازی کاربردی‌تان را در هر درخواست بگنجانید و برای درخواست‌هایی که شامل کلید میانای برنامه‌سازی کاربردی است از HTTPS استفاده کنید.

  1. روی 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"
  2. روی نماد کپی در نمونه کد، نماد کپی را انتخاب کنید.، کلیک کنید تا فرمان curl کپی شود.
  3. فرمان را در پنجره ترمینال جای‌گذاری کنید و فرمان را اجرا کنید.

پاسخ در قالب 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"
}

اعمال محدودیت‌های کلید میانای برنامه‌سازی کاربردی

Google اکیداً توصیه می‌کند که کلیدهای میانای API خود را با محدود کردن استفاده از آن‌ها فقط به میاناهای برنامه‌سازی کاربردی و برنامه‌هایی که به آن‌ها نیاز دارند، محدود کنید. محدود کردن کلیدهای میانای API با محافظت از برنامه شما دربرابر درخواست‌های غیرمجاز، امنیت آن را افزایش می‌دهد. کلیدهای میانای برنامه‌سازی کاربردی از دو نوع محدودیت پشتیبانی می‌کنند:

  • محدودیت‌های میانای برنامه‌سازی کاربردی مشخص می‌کند کدام کیت‌های توسعه نرم‌افزار و میاناهای برنامه‌سازی کاربردی را می‌توان بااستفاده از کلید میانای برنامه‌سازی کاربردی فراخوانی کرد. کنسول و gcloud CLI هنگام ایجاد کلید به حداقل یک محدودیت API نیاز دارند.
  • محدودیت‌های برنامه مشخص می‌کند کدام وب‌سایت‌ها، نشانی‌های IP، یا برنامه‌ها می‌توانند از کلید میانای برنامه‌سازی کاربردی استفاده کنند.

برای اطلاعات بیشتر درباره اعمال محدودیت‌ها، به محدود کردن کلیدهای میانای برنامه‌سازی کاربردی مراجعه کنید.

ایجاد کد OAuth

Address Validation API از OAuth 2.0 برای اصالت‌سنجی پشتیبانی می‌کند. Google از سناریوهای رایج OAuth 2.0، مثل سناریوهای سرور وب، پشتیبانی می‌کند.

این سند نحوه ارسال کد OAuth به فراخوانی Address Validation API در محیط توسعه نرم‌افزار را شرح می‌دهد. برای اطلاعات بیشتر درباره استفاده از OAuth در محیط تولید، به روش‌های اصالت‌سنجی در Google مراجعه کنید.

می‌توانید با ارسال درخواست‌های میانای برنامه‌سازی کاربردی به سرور، مستقیماً میاناهای برنامه‌سازی کاربردی Google Maps را فراخوانی کنید، یا می‌توانید از کتابخانه‌های کارخواه برای ساده کردن کدتان استفاده کنید. ‫Google Maps کتابخانه‌های کارخواه را برای 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

مثال: فراخوانی‌های REST API را در محیط توسعه محلی‌تان امتحان کنید

اگر محیطی ندارید که کد ایجاد کند و می‌خواهید Address Validation API را با کد OAuth امتحان کنید، از روش ارائه‌شده در این بخش استفاده کنید.

این مثال نحوه استفاده از کد OAuth ارائه‌شده توسط اعتبارنامه‌های پیش‌فرض برنامه (ADC) را برای برقراری تماس شرح می‌دهد. برای اطلاعات بیشتر درباره استفاده از ADC برای فراخوانی Google APIs با کتابخانه‌های کارخواه، به اصالت‌سنجی بااستفاده از کتابخانه‌های کارخواه مراجعه کنید.

از روال REST زیر فقط برای توسعه یا آزمایش استفاده کنید، نه برای تولید.

پیش‌نیازها

قبل‌از اینکه درخواست REST بااستفاده از ADC ایجاد کنید، از gcloud CLI برای ارائه اعتبارنامه به ADC استفاده کنید:

  1. gcloud CLI را نصب و مقداردهی اولیه کنید. برای اطلاعات بیشتر، به نصب gcloud CLI مراجعه کنید.

  2. با gcloud CLI اصالت‌سنجی کنید:

    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 ارسال کنید.

برای فراخوانی Address Validation API بااستفاده از نشانه OAuth، مراحل زیر را تکمیل کنید:

  1. در نمونه کد زیر، 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"

  2. برای کپی کردن فرمان curl، روی کپی کردن در نمونه کد کلیک کنید.

  3. فرمان را در پنجره ترمینال جای‌گذاری کنید و سپس آن را اجرا کنید.

پاسخ در قالب 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": "fac2ae1b-50ce-442c-8bc3-d459039950ef"
}

عیب‌یابی

اگر درخواستتان پیام خطایی برمی‌گرداند که می‌گوید این میانای برنامه‌سازی کاربردی از اعتبارنامه کاربر نهایی پشتیبانی نمی‌کند، به عیب‌یابی راه‌اندازی ADC مراجعه کنید.

قدم بعدی چیست

اکنون که Address Validation API را فعال کرده‌اید و درخواست موفقی ارسال کرده‌اید، برای کسب اطلاعات بیشتر درباره استفاده از این API، به ارسال درخواست اعتبارسنجی نشانی و آشنایی با پاسخ اعتبارسنجی نشانی پایه مراجعه کنید.