Coğrafi Kodlama API'si Web Hizmetlerini Kullanmaya Yönelik En İyi Uygulamalar

Google Haritalar Platformu web hizmetleri, Google'a yönelik HTTP arayüzleri koleksiyonudur. Haritalar uygulamalarınız için coğrafi veriler sağlayan hizmetlerdir.

Bu kılavuzda, web hizmeti ve işleme konularını ele alacağız. Geliştirici kılavuzuna bakın bölümünü ziyaret edin.

Web hizmeti nedir?

Google Haritalar Platformu web hizmetleri, Google Haritalar API'si verilerini istemek için kullanılan bir arayüzdür ve Haritalar uygulamalarınızdaki verileri kullanarak harici hizmetlerden yararlanabilirsiniz. Bu hizmetler uyarınca, bir haritayla birlikte kullanılmak üzere tasarlanır. Lisans Kısıtlamaları Google Haritalar Platformu Hizmet Şartları'na tabidir.

Haritalar API'leri web hizmetleri, URL parametrelerini ileten ve/veya Hizmetlerin bağımsız değişkenleri olarak JSON biçimli POST verileri. Genellikle bu hizmetler verileri ayrıştırmak için JSON veya XML olarak yanıt gövdesi ve/veya uygulamanız tarafından işleniyor.

Tipik bir Coğrafi Kodlama API'si isteği genellikle şu formu kullanın:

https://maps.googleapis.com/maps/api/geocode/output?parameters

burada output, yanıt biçimini belirtir (genellikle json veya xml).

Not: Tüm Geocoding API uygulamaları kimlik doğrulama gerektirir. Kimlik doğrulama kimlik bilgileri hakkında daha fazla bilgi edinin.

SSL/TLS Erişimi

HTTPS, API anahtarları kullanan veya kullanıcı içeren tüm Google Haritalar Platformu istekleri için gereklidir dışı verilerdir. HTTP üzerinden yapılan ve hassas veriler içeren istekler reddedilebilir.

Geçerli bir URL oluşturma

Bu örneğin "geçerli" bir URL kendiliğinden ortaya çıkar, ancak durum pek öyle değil. Bir özel karakterler içerebilir (ör. "上海+中國"); tarayıcının bunu dahili olarak çevirmesi gerekir iletilmeden önce bu karakterleri farklı bir kodlamaya dönüştürmelidir. Aynı jeton, UTF-8 girişi oluşturan veya kabul eden tüm kodlar UTF-8 karakterleri içeren URL'leri "geçerli" olarak işleyebilir ancak aynı zamanda bir web sunucusuna göndermeden önce çevirmesini isteyin. Bu sürece denir URL kodlaması veya yüzde kodlama.

Özel karakterler

Özel karakterleri çevirmemiz gerekiyor. tüm URL'ler, Üniforma Kaynak Tanımlayıcı (URI) spesifikasyonu. Bu, URL'lerin ASCII karakterlerinin yalnızca özel bir alt kümesini içermelidir: tanıdık alfanümerik semboller ve kontrol olarak kullanılmak üzere ayrılmış bazı karakterler karakterleri kullanabilirsiniz. Bu tabloda şu karakterler özetlenmektedir:

Geçerli bir URL oluştururken, URL'nin yalnızca tablosunu oluşturalım. Bu karakter grubunu genel olarak kullanmak için bir URL oluşturma biri ihmal, biri ikame olmak üzere iki soruna yol açar:

• Kullanmak istediğiniz karakterler ayarlandı. Örneğin, yabancı dillerdeki karakterler gibi 上海+中國 etiketleri, tablodaki karakteri ekleyin. Genel kurala göre alanlar (yani alanlar izin verilmeyen içerikler) genellikle artı işaretiyle gösterilir '+' karakter de mevcut.
• Yukarıdaki karakterler arasında ayrılmış karakterler olarak yer almaktadır. anahtar kelimenin olduğu gibi kullanılması gerekir. Örneğin, ?, şunu belirtmek için URL'lerde kullanılır: sorgu dizesinin başlangıcı; öğesini kullanmak istiyorsanız dizesi "? ve Gizemler'e hoş geldiniz." bu URL'yi kodlamanız gerekir '?' karakter.

URL olarak kodlanacak tüm karakterler kodlanmıştır '%' karakteri ve iki karakterden oluşan bir onaltılık karakter kullanılarak değerine karşılık gelir. Örneğin, UTF-8'deki 上海+中國 parametresi şu şekilde URL olarak kodlanır: %E4%B8%8A%E6%B5%B7%2B%E4%B8%AD%E5%9C%8B. İlgili içeriği oluşturmak için kullanılan ? and the Mysterians dizesinin URL'si şöyle olur: %3F+and+the+Mysterians veya %3F%20and%20the%20Mysterians.

Yaygın olarak kodlama gerektiren karakterler

Kodlanması gereken bazı yaygın karakterler şunlardır:

Kullanıcı girişinden aldığınız bir URL'yi dönüştürmek bazen zor olabilir. Örneğin, bir kullanıcı "5th&Main Street" olarak bir adres girebilir. Genel olarak, URL'nizi kendi parçalarından oluşturmanız gerekir: herhangi bir kullanıcı girişi değişmez karakter olarak kabul edilir.

Ayrıca, URL'ler tüm Google Haritalar Platformu web hizmetleri için 16.384 karakterle sınırlıdır ve statik web API'leri. Çoğu hizmette bu karakter sınırına nadiren yaklaşılır. Ancak, belirli hizmetlerde uzun URL'lere neden olabilecek bazı parametreler bulunduğunu unutmayın.

Google API'lerinin Sonradan Kullanımı

Kötü tasarlanmış API istemcileri hem internette hem de internette Google sunucuları. Bu bölümde, API istemcileri için bazı en iyi uygulamalar yer almaktadır. Takip edilenler Bu en iyi uygulamalar, uygulamanızın yanlışlıkla kötüye kullanımı nedeniyle engellenmesini önlemenize yardımcı olabilir. API'lar.

Hataları ve yeniden denemeleri yönetme

UNKNOWN_ERROR veya OVER_QUERY_LIMIT yanıt kodları hakkında bilgi için Coğrafi Kodlama API'sı ile hataları ve yeniden denemeleri yönetme hakkında bilgi edinin.

Üstel Geri Alma

Nadiren isteğiniz yerine getirilirken bir şeyler ters gidebilir. 4XX veya 5XX HTTP olabilir veya TCP bağlantısı istemciniz ile Google'ın web sunucusu arasında bir yerde, sunucu. Çoğunlukla isteği yeniden denemek daha iyidir, takip isteği de başarılı olabilir. Ancak, bütçe oluşturmak için Google sunucularına istek gönderen sürekli bir döngü vardır. Bu döngü davranışı, birçok taraf için soruna neden olan bir iletişim ağı örneğidir.

Daha iyi bir yaklaşım, denemeler arasındaki gecikmeleri artırarak tekrar denemektir. Genellikle gecikme, her denemede çarpımsal bir faktörle artırılır. Bu yaklaşıma Üstel Geri Alma.

Örneğin, Time Zone API:

https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510&timestamp=1331161200&key=YOUR_API_KEY

Aşağıdaki Python örneğinde, isteğin eksponansiyel geri yüklemeyle nasıl gönderileceği gösterilmektedir:

import json
import time
import urllib.error
import urllib.parse
import urllib.request

# The maps_key defined below isn't a valid Google Maps API key.
# You need to get your own API key.
# See https://developers.google.com/maps/documentation/timezone/get-api-key
API_KEY = "YOUR_KEY_HERE"
TIMEZONE_BASE_URL = "https://maps.googleapis.com/maps/api/timezone/json"


def timezone(lat, lng, timestamp):

    # Join the parts of the URL together into one string.
    params = urllib.parse.urlencode(
        {"location": f"{lat},{lng}", "timestamp": timestamp, "key": API_KEY,}
    )
    url = f"{TIMEZONE_BASE_URL}?{params}"

    current_delay = 0.1  # Set the initial retry delay to 100ms.
    max_delay = 5  # Set the maximum retry delay to 5 seconds.

    while True:
        try:
            # Get the API response.
            response = urllib.request.urlopen(url)
        except urllib.error.URLError:
            pass  # Fall through to the retry loop.
        else:
            # If we didn't get an IOError then parse the result.
            result = json.load(response)

            if result["status"] == "OK":
                return result["timeZoneId"]
            elif result["status"] != "UNKNOWN_ERROR":
                # Many API errors cannot be fixed by a retry, e.g. INVALID_REQUEST or
                # ZERO_RESULTS. There is no point retrying these requests.
                raise Exception(result["error_message"])

        if current_delay > max_delay:
            raise Exception("Too many retry attempts.")

        print("Waiting", current_delay, "seconds before retrying.")

        time.sleep(current_delay)
        current_delay *= 2  # Increase the delay each time we retry.


if __name__ == "__main__":
    tz = timezone(39.6034810, -119.6822510, 1331161200)
    print(f"Timezone: {tz}")

Ayrıca, uygulama çağrısında daha üst düzey bir yeniden deneme kodu olmadığından da kısa sürede tekrarlanan isteklere yol açan bir zincirle ilgilidir.

Senkronize İstekler

Google'ın API'lerine yapılan senkronize edilmiş çok sayıda istek, Dağıtılmış Hizmet Reddi (DDoS) saldırısı ve buna göre işlem yapılması. Alıcı: API isteklerinin senkronize edilmediğinden emin olun. müzakere tekniği de eklediniz.

Örneğin, saati geçerli saat diliminde gösteren bir uygulamayı ele alalım. Bu uygulama muhtemelen istemci işletim sisteminde alarm çalacak ve cihazı şu saatte uyandıracak: gösterilen zamanın güncellenebilmesi için dakikanın başlangıcını. Başvuru, Söz konusu alarmla ilişkili işlemlerin bir parçası olarak API çağrısı yapmamalıdır.

Sabit bir alarma karşılık olarak API çağrıları yapmak, API çağrılarının senkronize etmek yerine dakikanın başında senkronize edilir. eşit olarak dağıtılır. Bunu yapan kötü tasarlanmış bir uygulama, her dakikanın başında normal düzeylerde altmış kadar trafik alabilir.

Bunun yerine, rastgele seçilen bir zamana ayarlanmış ikinci bir alarm olması olası iyi bir tasarımdır. Bu ikinci alarm etkinleştiğinde uygulama ihtiyaç duyduğu API'leri çağırır ve sonuç. Uygulama dakika başında ekranını güncellemek istediğinde önceden saklanan sonuçları çağırır. Bu yaklaşımla, API çağrıları eşit olarak yayılır. Ayrıca, ekran etkinken API çağrılarının güncelleniyor.

Dakikanın başlangıcı dışında, diğer yaygın senkronizasyon zamanları için de hedeflenecekler seçeneği bir saatin başında, her günün başlangıcında ise gece yarısı olacak.

Yanıtlar İşleniyor

Bu bölümde, bu değerlerin web hizmeti yanıtlarından dinamik olarak nasıl ayıklanacağı anlatılmaktadır.

Google Haritalar web hizmetleri, Google Haritalar'da kullanıcı dostu olmadığını söyleyebiliriz. Sorgu gerçekleştirirken yerine bir veri kümesi görüntülemek yerine, muhtemelen birkaç değerler. Genellikle, yanıtları web'den ayrıştırmak yalnızca sizi ilgilendiren değerleri ayıklayabilir.

Kullandığınız ayrıştırma şeması, dönüşüm modellemeden önce XML veya JSON biçiminde dışa aktarılır. JSON yanıtları, zaten şu biçimindedir: JavaScript nesneleri, JavaScript'in kendi içinde işlenebilir gerekir. XML yanıtları, XML işlemcisi kullanılarak işlenmelidir. ve XML biçimindeki öğeleri ele almak için bir XML sorgu dili içerir. XPath'i XML işlemede yaygın olarak desteklendiğinden aşağıdaki örneklere göz atın kitaplıklar.

XPath ile XML işleme

XML, web siteleri ve siteler için kullanılan nispeten olgun veri alışverişidir. JSON kadar hafif olmasa da, , daha fazla dil desteği ve daha güçlü araçlar sunar. Kod XML işleme sistemi, örneğin Java'da javax.xml paket.

XML yanıtlarını işlerken, müşterilerinize XML belgesindeki düğümleri seçmek için kullanılan sorgu dili öğelerin, tablodaki mutlak konumlarda bulunduğunu XML işaretlemesi. XPath Düğümleri ve öğeleri benzersiz bir şekilde tanımlamak için kullanılan bir dil söz dizimidir bir kontrol listesidir. XPath ifadeleri, kullanıcı yolculuğunuzun belirli bir içeriği kapsayabilir.

XPath İfadeleri

XPath hakkında biraz bilgi sahibi olmak, bir yöntem kullanmayı tercih eder. Bu bölümde, resmî bir belge olan öğelerin bir XML belgesindeki XPath ile düzeltilir. Böylece, birden çok öğeyi ele alabilir ve karmaşık sorgular oluşturabilir.

XPath bir XML içindeki öğeleri seçmek için ifadeleri kullanır. dizin yolları için kullanılana benzer bir söz dizimi kullanılarak çalıştırılması gerekir. Bu ifadeler, bir XML belgesindeki öğeleri tanımlar ağacı, DOM'ninkine benzer bir hiyerarşik ağaçtır. Genellikle, XPath ifadeleri açgözlüdür ve bu ifadenin sağlanan ölçütlerle eşleşen tüm düğümlerle eşleşir.

Bu örnek için aşağıdaki soyut XML'i kullanarak örnekler:

<WebServiceResponse>
 <status>OK</status>
 <result>
  <type>sample</type>
  <name>Sample XML</name>
  <location>
   <lat>37.4217550</lat>
   <lng>-122.0846330</lng>
  </location>
 </result>
 <result>
  <message>The secret message</message>
 </result>
</WebServiceResponse>

İfadelerde Düğüm Seçimi

XPath seçimleri, düğümleri seçin. Kök düğüm tüm belgeyi kapsadığından emin olun. Bu düğümü "/" özel ifadesi. Kök düğüm, XML belgenizin en üst düzey düğümü değildir; aslında, bu üst düzey öğenin bir seviye üzerindedir ve somut olarak ortaya koyar.

Öğe düğümleri, XML içindeki çeşitli öğeleri temsil eder belge ağacını tıklayın. Bir <WebServiceResponse> öğesi, örneğin, örnek hizmetten yararlanın. Düğümleri tek tek seçmek için mutlak veya göreceli yollar vardır. Bunlar, başında "/" yok karakteriyle ayrılır.

• Mutlak yol: "/WebServiceResponse/result" ifade edilen <result> düğümün tümünü seçer. <WebServiceResponse> kategorisinin alt öğeleridir düğüm. (Bu öğelerin her ikisinin de, "/" adlı düğüm.)
• Geçerli bağlamdan göreli yol: ifade "result" herhangi bir <result> ile eşleşir öğeleri geçerli bağlamla ilişkilendirin. Genellikle bağlam konusunda endişelenmeniz gerekir. Çünkü genelde tek bir ifadeyle hizmet sonuçları elde etmenizi sağlar.

Bu ifadelerden herhangi biri, "//" ile gösterilen, joker karakterli bir yol karakteridir. Bu joker karakter, karar vermektir. "//formatted_address" XPath ifadesi , mevcut belgede söz konusu ada sahip olan tüm düğümlerle eşleşir. //viewport//lat ifadesi tümüyle eşleşir <viewport> öğesini izleyebilen <lat> öğeleri ebeveyn olmanız gerekir.

Varsayılan olarak, XPath ifadeleri tüm öğelerle eşleşir. İçeriklerinizin bir şart sağlayarak belirli bir öğeyle eşleşecek ifadeyi, değeri, köşeli parantez ([]) içinde yer alır. XPath "/GeocodeResponse/result[2] ifadesi her zaman örneğine bakalım.

    <WebServiceResponse>
     <status>OK</status>
     <result>
      <type>sample</type>
      <name>Sample XML</name>
      <location>
       <lat>37.4217550</lat>
       <lng>-122.0846330</lng>
      </location>
     </result>
     <result>
      <message>The secret message</message>
     </result>
    </WebServiceResponse>
    

    <result>
     <type>sample</type>
     <name>Sample XML</name>
     <location>
      <lat>37.4217550</lat>
      <lng>-122.0846330</lng>
     </location>
    </result>
    <result>
     <message>The secret message</message>
    </result>
    

    <location>
     <lat>37.4217550</lat>
     <lng>-122.0846330</lng>
    </location>
    

    <message>The secret message</message>
    

     <type>sample</type>
     <name>Sample XML</name>
     <location>
      <lat>37.4217550</lat>
      <lng>-122.0846330</lng>
     </location>
    

    Sample XML
    

Öğeleri seçerken düğümleri ve ses merkezlerini seçtiğiniz metin de koruyabilir. Genellikle, tüm eşleşen düğümleri yinelemek ve metni ayıklamak ister. Siz metin düğümleriyle doğrudan da eşleşebilir; bkz. Metin Düğümleri başlıklı bölüme bakın.

XPath'in özellik düğümlerini de desteklediğini unutmayın; ancak, Tüm Google Haritalar web hizmetleri, öznitelikleri olmayan öğeler sunar; özelliklerin eşleşmesi gerekmez.

İfadelerde Metin Seçimi

Bir XML belgesindeki metin, XPath ifadelerinde belirtilir bir metin düğümü operatörü aracılığıyla ekleyebilirsiniz. Bu operatör "text()" belirtilen düğümden metin ayıklamayı gösterir. Örneğin, "//formatted_address/text()" XPath ifadesi şunu içerecek: <formatted_address> içindeki tüm metinleri döndür öğeler.

    sample
    Sample XML

    37.4217550
    -122.0846330
    The secret message
    

    The secret message
    

    Sample XML
    

Alternatif olarak, bir ifadeyi değerlendirebilir ve "düğüm kümesi"ni, tekrar tekrar yapmak istediğinizde metnini de görebilirsiniz. Bu yaklaşımı aşağıdaki örnekte kullanıyoruz.

XPath hakkında daha fazla bilgi için XPath W3C Spesifikasyonu.

Java'daki XPath'i değerlendirme

Java, XML'i ayrıştırma ve XPath ifadelerini kullanma için geniş destek sunar javax.xml.xpath.* paketinde. Bu nedenle, bu bölümdeki örnek kod aşağıdaki işlemler için Java’yı kullanır: XML'in nasıl işleneceğini ve XML hizmet yanıtlarından verilerin nasıl ayrıştırılacağını gösterir.

XPath'i Java kodunuzda kullanmak için önce örneklendirmeniz gerekir XPathFactory ve çağrı örneği XPath nesnesi oluşturmak için bu fabrikada newXPath(). Böylece bu nesne, geçirilen XML'i işleyebilir ve XPath ifadelerini bulmak için evaluate() yöntemini kullanır.

XPath ifadelerini değerlendirirken, işlemi yinelediğinizden emin olun tüm olası "düğüm kümelerinin" üzerinde bu bilgiler iade edilebilir. Çünkü bunlar sonuçları Java kodunda DOM düğümleri olarak döndürülürse, NodeList nesnesi içinde bu tür birden çok değer ve o nesne üzerinde iterasyon yaparak onlardan herhangi bir metni veya değeri çıkarın düğüm.

Aşağıdaki kodda, XPath özelliğinin nasıl oluşturulacağı gösterilmektedir bir XML ve bir XPath ifadesi atayın ve ifadesini kullanın.

import org.xml.sax.InputSource;
import org.w3c.dom.*;
import javax.xml.xpath.*;
import java.io.*;

public class SimpleParser {

  public static void main(String[] args) throws IOException {

	XPathFactory factory = XPathFactory.newInstance();

    XPath xpath = factory.newXPath();

    try {
      System.out.print("Web Service Parser 1.0\n");

      // In practice, you'd retrieve your XML via an HTTP request.
      // Here we simply access an existing file.
      File xmlFile = new File("XML_FILE");

      // The xpath evaluator requires the XML be in the format of an InputSource
	  InputSource inputXml = new InputSource(new FileInputStream(xmlFile));

      // Because the evaluator may return multiple entries, we specify that the expression
      // return a NODESET and place the result in a NodeList.
      NodeList nodes = (NodeList) xpath.evaluate("XPATH_EXPRESSION", inputXml, XPathConstants.NODESET);

      // We can then iterate over the NodeList and extract the content via getTextContent().
      // NOTE: this will only return text for element nodes at the returned context.
      for (int i = 0, n = nodes.getLength(); i < n; i++) {
        String nodeString = nodes.item(i).getTextContent();
        System.out.print(nodeString);
        System.out.print("\n");
      }
    } catch (XPathExpressionException ex) {
	  System.out.print("XPath Error");
    } catch (FileNotFoundException ex) {
      System.out.print("File Error");
    }
  }
}