This product or feature is in Preview (pre-GA). Pre-GA products and features might have limited support, and changes to pre-GA products and features might not be compatible with other pre-GA versions. Pre-GA Offerings are covered by the Google Maps Platform Service Specific Terms. For more information, see the launch stage descriptions.

このページは Cloud Translation API によって翻訳されました。

Places Insights API ウェブサービスの使用に関するベストプラクティス

Google Maps Platform ウェブサービスは、Google 地図アプリケーションに地理データを提供するサービス。

このガイドでは、リソースの設定に役立つ一般的な手順について説明します。ウェブサービスサービスレスポンスの処理に使用されますPlaces Insights API の詳細なドキュメントについては、デベロッパーガイドをご覧ください。

ウェブサービスとは

Google Maps Platform ウェブサービスは、Maps API のデータをリクエストするためのインターフェースです。マップアプリケーション内でデータを使用する方法について説明します。これらのサービスは、使用できるように設計されているため、ライセンスの制限をご覧ください。

Maps API ウェブサービスは、特定の URL に HTTP(S) リクエストを使用して、URL パラメータやサービスの引数としての JSON 形式の POST データ。通常、これらのサービスは、解析および変換用の JSON 形式のレスポンス本文アプリケーションによる処理です。

次の例は、Pod の URL を REST GET リクエスト:

AN ACTUAL API CALL INCLUDING THE API_KEY&key=API_KEY

注: すべての Places Insights API アプリケーションには認証が必要です。認証情報の詳細を確認する。

SSL/TLS アクセス

API キーを使用する、またはユーザーを含む Google Maps Platform リクエストには、すべて HTTPS が必須です。できます。機密データを含む HTTP 経由で送信されたリクエストは拒否される場合があります。

有効な URL の作成

「有効」な URL とは何か、説明の必要はないと考えられるかもしれませんが、それほど単純なことではありません。ブラウザのアドレスバーに入力される URL には特殊文字（"上海+中國" など）が含まれている場合があります。このような特殊文字は、ブラウザで別のエンコードに内部的に変換してから送信する必要があります。同様に、UTF-8 入力を生成または受け付けるコードでは、UTF-8 の文字が使用された URL を「有効」な URL として扱うことがありますが、それらの文字はウェブサーバーに送信する前に変換する必要があります。このプロセスは、URL エンコードまたはパーセントエンコードと呼ばれます。

特殊文字

すべての URL は URI（Uniform Resource Identifier）仕様で規定されている構文に従う必要があるため、特殊文字を変換する必要があります。つまり、URL には、ASCII 文字の特別なサブセット（よく使用される英数記号および URL 内で制御文字として使用される予約文字）のみを含める必要があります。次の表は、こうした特殊記号をまとめたものです。

有効な URL 文字の概要

セット	文字	URL での使用法
英数字	a b c d e f g h i j k l m n o p q r s t u v w x y z A B C D E F G H I J K L M N O P Q R S T U V W X Y Z 0 1 2 3 4 5 6 7 8 9	テキスト文字列、スキームでの使用（`http`）、ポート（`8080`）など
未予約	- _ . ~	テキスト文字列
予約済み	! * ' ( ) ; : @ & = + $ , / ? % # [ ]	制御文字やテキスト文字列

有効な URL を作成するときは、表しますしかし、URL での使用がこの文字セットだけに制限された場合、通常は 2 つの問題が発生します。1 つは省略、もう 1 つは置き換えです。

処理する文字が上記のセットに含まれない場合。たとえば、「上海+中國」のような英語以外の文字は、上記の文字を使用してエンコードする必要があります。一般的な命名規則では、URL 内で使用できないスペースもプラス記号 '+' を使用して表します。
上記のセットに予約文字として含まれる文字を、リテラル文字として使用する必要がある場合。たとえば、「?」は URL 内でクエリ文字列の先頭を示すために使用されます。文字列「?　and the Mysterions」を使用する場合は、文字 '?' をエンコードする必要があります。

URL エンコードが必要なすべての文字を、'%' と、UTF-8 文字に対応する 2 文字の 16 進数値を使用してエンコードします。たとえば、UTF-8 の「上海+中國」は、「%E4%B8%8A%E6%B5%B7%2B%E4%B8%AD%E5%9C%8B」として URL エンコードされます。文字列「? and the Mysterians」は、「%3F+and+the+Mysterians」または「%3F%20and%20the%20Mysterians」として URL エンコードされます。

エンコードが必要な一般的な文字

エンコードする必要がある一般的な文字は次のとおりです。

危険な文字	エンコードされた値
スペース	`%20`
"	`%22`
<	`%3C`
>	`%3E`
#	`%23`
%	`%25`
\|	`%7C`

ユーザー入力から受け取った URL の変換には、場合によって注意が必要です。たとえば、ユーザーが住所を「5th&Main St.」と入力することも考えられます。通常は、ユーザー入力をリテラル文字として処理して、URL をパーツから作成する必要があります。

さらに、URL は、すべての Google Maps Platform ウェブサービスと Static Web API で 16,384 文字に制限されています。ほとんどのサービスでは、この文字制限に達することはめったにありません。ただし、複数のパラメータを持つ特定のサービスでは、URL が長くなる可能性があります。

Google API の適切な使用

API クライアントの設計に問題があると、インターネットと Google のサーバー。このセクションでは、API のクライアントのベストプラクティスについて説明します。以下のベストプラクティスに従うと、アプリケーションによる意図しない API の乱用を防ぐことができます。

指数関数的バックオフ

まれに、リクエストの処理中になんらかの問題が生じることがあります。4XX または 5XX HTTP エラーが返されることがありますレスポンスコードを返さなければ、クライアントと Google のネットワークの間のどこかで TCP 接続があります。多くの場合、次のようにリクエストを再試行する価値はあります。元のリクエストが失敗した場合でも、フォローアップリクエストが成功する可能性があります。しかし、単に問題を解くのではなく、 Google のサーバーにリクエストを繰り返し行うループが発生します。このループ動作により、パイプラインにクライアントと Google の間のネットワークが原因で、多くの関係者に問題が生じることがあります。

よりよいアプローチは、試行間の遅延を増加させながら再試行することです。通常、試行のたびに乗法係数で増加します。この手法は指数バックオフ。

たとえば、アプリケーションでこのリクエストを Time Zone API:

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

次の Python の例では、指数関数的バックオフを使用してリクエストを実行する方法を示しています。

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}")

また、アプリケーション呼び出しの上位に再試行コードが含まれていないことにも注意する必要があります。連続してリクエストが繰り返されるチェーンです。

同期されたリクエスト

Google の API への大量の同期リクエストは、分散リクエストのように Google のインフラストラクチャに対するサービス拒否（DDoS）攻撃を受けたため、適切に対処する宛先 API リクエストが同期されていないことを確かめるために、通信できます。

たとえば、現在のタイムゾーンで時刻を表示するアプリケーションについて考えてみましょう。このアプリケーションは、表示時刻を更新できるように、クライアントのオペレーティングシステムで毎分 0 秒に起動するアラームを設定するものとします。アプリケーションは、 しないでください。

固定されたアラームに応答して API 呼び出しを行うと、API 呼び出しが失敗する異なるデバイス間でも同期されずに、均等に分散されます。アプリケーションの設計が不適切だと、このような処理を行うと、通常の 60 倍のレベルでトラフィックが下がります

その代わりに、ランダムに選択された時間に 2 つ目のアラームを設定するのが良い設計の 1 つです。この 2 番目のアラームを起動すると、アプリケーションは必要な API を呼び出し、表示されます。アプリケーションで 0 分の開始時に表示を更新する場合は、 API を再度呼び出す必要はありません。この方法では時系列で均等に分散されます。さらに、API 呼び出しによってレンダリングが遅延することはありません。更新されます。

時刻の初め以外の一般的な同期時刻については、ターゲットにしない時間を指定できます。

レスポンスの処理

このセクションでは、これらの値をウェブサービスレスポンスから動的に抽出する方法について説明します。

Google Maps ウェブサービスでは、わかりやすいレスポンスを提供していますが、必ずしもユーザーにとってわかりやすいとはいえません。クエリを実行するときは表示するより細かいデータだけを抽出使用できます。通常は、ウェブからのレスポンスを解析し、関心のある値のみを抽出できます

使用する解析スキームは、レスポンスを返すかどうかによって JSON での出力です。JSON レスポンスは、すでに次の形式になっています。 JavaScript オブジェクト（JavaScript 自体で処理可能）必要ありません。