نقل البيانات إلى Solar API على "منصة خرائط Google"

مطوّرو المنطقة الاقتصادية الأوروبية

للانتقال من Google Earth Engine Solar API إلى ‫Solar API على "منصة خرائط Google"، اتّبِع الخطوات التالية:

  1. فعِّل واجهة Google Maps Platform Solar API في مشروعك على السحابة الإلكترونية.
  2. أنشئ مفتاحًا جديدًا واقتصر على GMP Solar API.
  3. عدِّل الرمز باتّباع التعليمات التفصيلية الواردة أدناه.

المقارنة جنبًا إلى جنب

‫Solar API (جديد) منازل مع شمس Earth Engine Solar API (متوقّفة نهائيًا) رمز EE
حالة الإطلاق تم طرح الميزة. الإصدار التجريبي (متوقّف نهائيًا)
إذن الوصول
الآلية حساب Google Cloud من خلال وحدة تحكّم Cloud، وذلك عن طريق تفعيل Solar API وإدارة واجهة برمجة التطبيقات من خلال قسم "منصة خرائط Google" حساب Google Cloud من خلال Cloud Console، وذلك من خلال تفعيل Earth Engine Solar API
من يمكنه الاستفادة منها؟ علني الوصول الخاضع للتحكّم
المستوى موفَّرة ذاتيًا الوصول اليدوي إلى مشروع على السحابة الإلكترونية
المصادقة مفتاح واجهة برمجة التطبيقات وOAuth مفتاح واجهة برمجة التطبيقات
التسعير
الاستراتيجية Pay-as-you-go خصم بنسبة %100
التقسيم إلى مستويات لكل 1, 000 طلب بحث، مع انخفاض الأسعار استنادًا إلى الحجم –
نقاط النهاية أسعار مختلفة لكل نقطة نهاية –
السحابة الإلكترونية
التتبّع Cloud Monitoring ضِمن "Google Maps Platform" Cloud Monitoring ضمن "واجهات برمجة التطبيقات والخدمات"
الحصة الطلبات في الدقيقة (QPM) والطلبات في الساعة (QPH) سنويًا
التسجيل Cloud Logging (اختياري) Cloud Logging (اختياري)
الفوترة حساب فوترة السحابة الإلكترونية -
الدعم دعم كامل لـ "منصة خرائط Google" مع اتفاقية مستوى الخدمة (SLO) أو اتفاقية مستوى الخدمة (SLA) محدودة، حسب البريد الإلكتروني
واجهة برمجة التطبيقات
اسم المضيف https://solar.googleapis.com/v1/ (REST) https://earthenginesolar.googleapis.com/v1/ (REST)
الطُرق
  • buildingInsights:findClosest
  • dataLayers:get
  • buildings:findClosest
  • solar.get
الردّ لم يتم إجراء أي تغييرات مقارنةً بالإصدار التجريبي –
solarInfo نطاق جغرافي يبلغ نصف قطره 100 متر أو أقل نطاق جغرافي يبلغ نصف قطره 100 متر أو أقل
التغطية
المساحة عالمي عالمي
جودة البيانات HIGH/MEDIUM HIGH/MEDIUM
نوع المبنى أي مبنى تم ربطه بعنوان ويقع ضمن نطاق تغطية صور Solar API أي مبنى تم ربطه بعنوان ويقع ضمن نطاق تغطية صور Solar API
بنود الخدمة
بنود الخدمة بنود "منصة خرائط Google" بنود Google Earth Engine

خطوة بخطوة

إعداد مشروعك على Google Cloud

يمكنك الاطّلاع على التعليمات هنا: إعداد مشروعك على Google Cloud.

يمكن لأدوار معيّنة فقط إنشاء مشروع على السحابة الإلكترونية. إذا لم تتمكّن من إنشاء مشروع، تواصَل مع مشرف مؤسستك.

يمكنك أيضًا استخدام مشروع حالي على السحابة الإلكترونية. لمزيد من المعلومات، يمكنك الاطّلاع على مقالة بدء استخدام "منصة خرائط Google".

إعداد حساب الفوترة

يمكنك الاطّلاع على التعليمات هنا: كيفية إدارة حساب الفوترة.

يمكنك استخدام مشروع حالي على السحابة الإلكترونية مع حساب فوترة حالي.

الحصول على مفتاح واجهة برمجة التطبيقات أو استخدام رمز OAuth المميز

بعد إعداد مشروعك على Google Cloud، عليك إنشاء مفتاح API وتأمينه لاستخدام Solar API كما هو موضّح في استخدام مفاتيح API. أو يمكنك إنشاء رمز OAuth مميز كما هو موضّح في استخدام OAuth.

استخدام Solar API

  • إرسال طلبات GET إلى نقاط النهاية الجديدة : https://solar.googleapis.com
  • يُرجى العِلم أنّ بعض أسماء طرق واجهة برمجة التطبيقات قد تغيّرت:
    • buildings:findClosest ‏← buildingInsights:findClosest
    • solarinfo:get ‏← dataLayers:get

تجربة سريعة: استخدِم مفتاح واجهة برمجة التطبيقات المحفوظ من الخطوة السابقة واستبدِل YOUR_API_KEY في نموذج طلب البحث أدناه، قبل تحميل عنوان URL في المتصفّح:

https://solar.googleapis.com/v1/dataLayers:get?location.latitude=37.2746464&location.longitude=-121.7530949&radius_meters=10&key=YOUR_API_KEY

الاستجابة للإصدار الأوّلي من "المعاينة"

في الإصدار الأوّلي من "المعاينة" الذي تم طرحه في 9 أيار (مايو) 2023، كانت عناوين URL في الردود بالتنسيق التالي:

https://earthengine.googleapis.com/v1alpha/projects/sunroof-api/thumbnails/THUMBNAIL_ID:getPixels

المقتطف التالي هو مثال على الردّ:

{
  "imageryDate": {
    "year": 2015,
    "month": 8,
    "day": 8
  },
  "imageryProcessedDate": {
    "year": 2021,
    "month": 2,
    "day": 15
  },
  "dsmUrl": "https://earthengine.googleapis.com/v1alpha/projects/geo-solar-api/thumbnails/fbde33e9cd16d5fd10d19a19dc580bc1-8614f599c5c264553f821cd034d5cf32:getPixels",
  "rgbUrl": "https://earthengine.googleapis.com/v1alpha/projects/geo-solar-api/thumbnails/91ed3551f2d0abee20af35e07bd0c927-c96c59e80cf1fc1dc86cf59fc8ec86ba:getPixels",
  "maskUrl": "https://earthengine.googleapis.com/v1alpha/projects/geo-solar-api/thumbnails/e4051553dba6870c03d855ae82c30b7e-7cc8ae6ce7c73f219e3c1924e5c17fc6:getPixels",
  "annualFluxUrl": "https://earthengine.googleapis.com/v1alpha/projects/geo-solar-api/thumbnails/9b0f87f49d778a65c9e27ff936e6dbba-b90be2fe80d25abd4c9e8c4dc809f763:getPixels",
  "monthlyFluxUrl": "https://earthengine.googleapis.com/v1alpha/projects/geo-solar-api/thumbnails/90e7cca77402f14809e349937f0a0be8-94fafeb4ef42d72f1b3c0652a1cb5518:getPixels",
  "hourlyShadeUrls": [
    "https://earthengine.googleapis.com/v1alpha/projects/geo-solar-api/thumbnails/dcd276e4782aef4ff1b230b781736d37-e193b231ce57a03449afc3e21cf6783b:getPixels",
    ...
  ]
  }

لإرسال طلب إلى عنوان URL في الردّ، يجب تضمين عنوان URL الكامل في الطلب.

يمكنك الاطّلاع على المواصفات الكاملة لهذا الطلب والردّ في المستندات المرجعية.

كتابة تطبيق يتوافق مع كلا تنسيقي الردود

يمكنك الآن كتابة تطبيق يتعامل مع كل من تنسيقات المعاينة الأصلية وتنسيقات الرد الحالية.

الفرق الرئيسي بين الردّين، بالإضافة إلى عنوان URL نفسه، هو أنّه يجب تمرير مفتاح واجهة برمجة التطبيقات إلى طلب يصل إلى عناوين URL من تنسيق الردّ الجديد. إذا لم تضمّن مفتاح واجهة برمجة التطبيقات، سيتعذّر تنفيذ الطلب.

على سبيل المثال، يمكنك إضافة الرمز التالي إلى تطبيقك لفحص عنوان URL والتعامل مع كل إصدار بشكل صحيح:

JavaScript

/**
* Function to examine a response URL and to append the API key to the
* URL if it is in the new format.
*/
function prepareGetGeoTiffUrl(geoTiffUrl, apiKey) {
  if (geoTiffUrl.match("solar.googleapis.com")) {
    let url = new URL(geoTiffUrl);
    url.searchParams.set('apiKey', apiKey);
    return url.toString();
  }
  return geoTiffUrl;
}

Python

# Functions to examine a response URL and to append the API key to the
# URL if it is in the new format.

def add_api_key_to_url(base_url: str, api_key: str) -> str:
  '''Formats URL that currently lacks an API key to use the one provided.'''
  return base_url + "&key=" +api_key;

def prepare_geo_tiff_url(base_url: str, api_key: str) -> str:
  '''Prepares URL from GetDataLayers depending on API being called.
    If the geoTIFF url from GetDataLayers is for the solar API GetGeoTiff
      endpoint, append the API key. Otherwise return the URL as is.
  '''
  if re.search("solar.googleapis.com", geo_tiff_url):
    return add_api_key_to_url(geo_tiff_url, api_key)
  return geo_tiff_url

Java

/** Adds API key to a URL. */
private String addApiKeyToUrl(String geoTiffUrl, String apiKey) {
  return geoTiffUrl + "&key=" + apiKey;
}

/**
* Function to examine a response URL and to append the API key to the
* URL if it is in the new format.
*/
private String prepareGetGeoTiffUrl(String geoTiffUrl, String apiKey) {
  Pattern pattern = Pattern.compile("solar.googleapis.com");
  Matcher matcher = pattern.matcher(geoTiffUrl);
  if (matcher.find()) {
    return addApiKeyToUrl(geoTiffUrl, apiKey);
  } else {
    return geoTiffUrl;
  }
}

مراقب

مستوى المشروع مستوى حساب الفوترة

Cloud Monitoring Cloud Billing

نصائح مهمة

  • الحصة: الاستهلاك الذي يمكن توسيعه (بدلاً من الاستهلاك السنوي الذي سيتم إيقافه)
    • الحصة الحالية التي سيتم تغييرها إلى QPM
    • أفضل الممارسات: ضبط الحصة على مستوى العميل وإرسال التنبيهات
  • الأسعار:
    • Pay-as-you-go
    • لن يتم تحصيل رسوم مقابل الردود 404 NOT_FOUND عندما لا يكون الموقع الجغرافي ضمن نطاق التغطية، ولكن سيتم احتسابها ضمن الحصة المحددة.
  • بنود الاستخدام العامة: بنود خدمة "منصة خرائط Google"