Подпишите свой запрос цифровым ключом API.
В зависимости от вашего использования для аутентификации запросов может потребоваться цифровая подпись в дополнение к ключу API. См. следующую статью:
Как работают цифровые подписи
Цифровые подписи генерируются с использованием секрета подписи URL-адреса , который доступен в Google Cloud Console. Этот секрет, по сути, представляет собой закрытый ключ, которым вы делитесь только между вами и Google, и он уникален для вашего проекта.
В процессе подписи используется алгоритм шифрования для объединения URL-адреса и вашего общего секрета. Полученная в результате уникальная подпись позволяет нашим серверам проверять, имеет ли право на это любой сайт, генерирующий запросы с использованием вашего ключа API.
Ограничить неподписанные запросы
Чтобы убедиться, что ваш ключ API принимает только подписанные запросы:
- Перейдите на страницу квот платформы Google Maps в Cloud Console.
- Щелкните раскрывающийся список проекта и выберите тот же проект, который вы использовали при создании ключа API для своего приложения или сайта.
- Выберите Maps Static API в раскрывающемся списке API.
- Разверните раздел Неподписанные запросы .
- В таблице «Имя квоты» нажмите кнопку «Изменить» рядом с квотой, которую вы хотите изменить. Например, неподписанных запросов в день.
- Обновите лимит квоты на панели «Изменить лимит квоты» .
- Выберите Сохранить .
Прежде чем начать
Прежде чем начать, выясните URL-адрес веб-страницы, содержащей вашу статическую карту. Этот URL-адрес должен быть подписан цифровой подписью.
Подписание ваших запросов
Подписание запросов состоит из следующих шагов:
- Шаг 1. Получите секрет подписи URL-адреса
- Шаг 2. Создайте неподписанный запрос.
- Шаг 3. Создайте подписанный запрос.
Шаг 1. Получите секрет подписи URL-адреса
Чтобы получить секрет подписи URL-адреса вашего проекта:
- Перейдите на страницу учетных данных платформы Google Maps в Cloud Console.
- Откройте раскрывающийся список проекта и выберите тот же проект, который вы использовали при создании ключа API для Maps Static API.
- Прокрутите вниз до карты «Секретный генератор» . Поле Текущий секрет содержит текущий секрет подписи URL-адреса.
- На странице также имеется виджет «Подписать URL-адрес сейчас» , который позволяет автоматически подписывать запрос Maps Static API, используя текущий секрет подписи. Прокрутите вниз до карточки «Подписать URL сейчас», чтобы получить к ней доступ.
Чтобы получить новый секрет подписи URL-адреса, выберите «Регенерировать секрет» . Срок действия предыдущего секрета истечет через 24 часа после создания нового секрета. По истечении 24 часов запросы, содержащие старый секрет, перестают работать.
Шаг 2. Создайте неподписанный запрос.
Символы , не перечисленные в таблице ниже, должны быть закодированы в URL-адресе:
Набор | персонажи | использование URL-адреса |
---|---|---|
Буквенно-цифровой | abcdefghijklm nopqrstuvwxyz ABCDEFGHIJKLM NOPQRSTUVWXYZ 0 1 2 3 4 5 6 7 8 9 | Текстовые строки, использование схемы ( http ), порт ( 8080 ) и т. д. |
незарезервировано | - _ . ~ | Текстовые строки |
Сдержанный | ! * ' ( ) ; : @ & = + $ , / ? % # [ ] | Управляющие символы и/или текстовые строки |
То же самое относится к любым символам в наборе Reserved , если они передаются внутри текстовой строки. Дополнительную информацию см. в разделе Специальные символы .
Создайте URL-адрес неподписанного запроса без подписи. Инструкции см. в следующей документации разработчика:
Обязательно укажите ключ API в key
параметре. Например:
https://maps.googleapis.com/maps/api/staticmap?center=Z%C3%BCrich&zoom=12&size=400x400&key=YOUR_API_KEY
Создать подписанный запрос
Для одноразовых случаев использования, таких как размещение простого изображения статического API Карт или изображения статического API просмотра улиц на вашей веб-странице, а также в целях устранения неполадок, вы можете автоматически создать цифровую подпись с помощью доступного виджета «Подписать URL сейчас» .
Для динамически генерируемых запросов необходимо подписание на стороне сервера , что требует нескольких дополнительных промежуточных шагов.
В любом случае вы должны получить URL-адрес запроса, к которому в конце добавлен параметр signature
. Например:
https://maps.googleapis.com/maps/api/staticmap?center=Z%C3%BCrich&zoom=12&size=400x400&key=YOUR_API_KEY
&signature=BASE64_SIGNATURE
Использование виджета «Подписать URL сейчас»
Чтобы создать цифровую подпись с помощью ключа API с помощью виджета «Подписать URL сейчас» в Google Cloud Console:
- Найдите виджет «Подписать URL-адрес сейчас» , как описано в разделе «Шаг 1. Получите секрет подписи URL-адреса» .
- В поле URL-адрес вставьте URL-адрес неподписанного запроса из шага 2. Создание неподписанного запроса .
- Появившееся поле «Ваш подписанный URL-адрес» будет содержать ваш URL-адрес с цифровой подписью. Обязательно сделайте копию.
Генерация цифровых подписей на стороне сервера
По сравнению с виджетом «Подписать URL-адрес сейчас» при создании цифровых подписей на стороне сервера вам потребуется выполнить несколько дополнительных действий:
Удалите схему протокола и части хоста URL-адреса, оставив только путь и запрос:
Отображаемый секрет подписи URL-адресов закодирован в модифицированном формате Base64 для URL-адресов.
Поскольку большинство криптографических библиотек требуют, чтобы ключ был в необработанном байтовом формате, перед подписанием вам, вероятно, придется декодировать секрет подписи URL-адреса в исходный необработанный формат.
- Подпишите приведенный выше разделенный запрос, используя HMAC-SHA1.
Поскольку большинство криптографических библиотек генерируют подпись в формате необработанных байтов, вам потребуется преобразовать полученную двоичную подпись с помощью модифицированного Base64 для URL-адресов, чтобы преобразовать ее во что-то, что можно будет передать внутри URL-адреса.
Добавьте подпись в кодировке Base64 к исходному URL-адресу неподписанного запроса в параметре
signature
. Например:https://maps.googleapis.com/maps/api/staticmap?center=Z%C3%BCrich&zoom=12&size=400x400&key=YOUR_API_KEY &signature=BASE64_SIGNATURE
/maps/api/staticmap?center=Z%C3%BCrich&zoom=12&size=400x400&key=YOUR_API_KEY
Примеры, демонстрирующие способы реализации подписи URL-адресов с помощью серверного кода, см. в разделе Пример кода для подписи URL-адресов ниже.
Пример кода для подписи URL-адресов
В следующих разделах показаны способы реализации подписи URL-адресов с использованием серверного кода. URL-адреса всегда должны быть подписаны на стороне сервера, чтобы избежать раскрытия секрета подписи URL-адресов пользователям.
Питон
В приведенном ниже примере для подписи URL-адреса используются стандартные библиотеки Python. ( Загрузить код.)
#!/usr/bin/python # -*- coding: utf-8 -*- """ Signs a URL using a URL signing secret """ import hashlib import hmac import base64 import urllib.parse as urlparse def sign_url(input_url=None, secret=None): """ Sign a request URL with a URL signing secret. Usage: from urlsigner import sign_url signed_url = sign_url(input_url=my_url, secret=SECRET) Args: input_url - The URL to sign secret - Your URL signing secret Returns: The signed request URL """ if not input_url or not secret: raise Exception("Both input_url and secret are required") url = urlparse.urlparse(input_url) # We only need to sign the path+query part of the string url_to_sign = url.path + "?" + url.query # Decode the private key into its binary format # We need to decode the URL-encoded private key decoded_key = base64.urlsafe_b64decode(secret) # Create a signature using the private key and the URL-encoded # string using HMAC SHA1. This signature will be binary. signature = hmac.new(decoded_key, str.encode(url_to_sign), hashlib.sha1) # Encode the binary signature into base64 for use within a URL encoded_signature = base64.urlsafe_b64encode(signature.digest()) original_url = url.scheme + "://" + url.netloc + url.path + "?" + url.query # Return signed URL return original_url + "&signature=" + encoded_signature.decode() if __name__ == "__main__": input_url = input("URL to Sign: ") secret = input("URL signing secret: ") print("Signed URL: " + sign_url(input_url, secret))
Ява
В приведенном ниже примере используется класс java.util.Base64
, доступный начиная с JDK 1.8. В более старых версиях может потребоваться использование Apache Commons или аналогичного. ( Загрузить код.)
import java.io.IOException; import java.io.UnsupportedEncodingException; import java.net.URI; import java.net.URISyntaxException; import java.security.InvalidKeyException; import java.security.NoSuchAlgorithmException; import java.util.Base64; // JDK 1.8 only - older versions may need to use Apache Commons or similar. import javax.crypto.Mac; import javax.crypto.spec.SecretKeySpec; import java.net.URL; import java.io.BufferedReader; import java.io.InputStreamReader; public class UrlSigner { // Note: Generally, you should store your private key someplace safe // and read them into your code private static String keyString = "YOUR_PRIVATE_KEY"; // The URL shown in these examples is a static URL which should already // be URL-encoded. In practice, you will likely have code // which assembles your URL from user or web service input // and plugs those values into its parameters. private static String urlString = "YOUR_URL_TO_SIGN"; // This variable stores the binary key, which is computed from the string (Base64) key private static byte[] key; public static void main(String[] args) throws IOException, InvalidKeyException, NoSuchAlgorithmException, URISyntaxException { BufferedReader input = new BufferedReader(new InputStreamReader(System.in)); String inputUrl, inputKey = null; // For testing purposes, allow user input for the URL. // If no input is entered, use the static URL defined above. System.out.println("Enter the URL (must be URL-encoded) to sign: "); inputUrl = input.readLine(); if (inputUrl.equals("")) { inputUrl = urlString; } // Convert the string to a URL so we can parse it URL url = new URL(inputUrl); // For testing purposes, allow user input for the private key. // If no input is entered, use the static key defined above. System.out.println("Enter the Private key to sign the URL: "); inputKey = input.readLine(); if (inputKey.equals("")) { inputKey = keyString; } UrlSigner signer = new UrlSigner(inputKey); String request = signer.signRequest(url.getPath(),url.getQuery()); System.out.println("Signed URL :" + url.getProtocol() + "://" + url.getHost() + request); } public UrlSigner(String keyString) throws IOException { // Convert the key from 'web safe' base 64 to binary keyString = keyString.replace('-', '+'); keyString = keyString.replace('_', '/'); System.out.println("Key: " + keyString); // Base64 is JDK 1.8 only - older versions may need to use Apache Commons or similar. this.key = Base64.getDecoder().decode(keyString); } public String signRequest(String path, String query) throws NoSuchAlgorithmException, InvalidKeyException, UnsupportedEncodingException, URISyntaxException { // Retrieve the proper URL components to sign String resource = path + '?' + query; // Get an HMAC-SHA1 signing key from the raw key bytes SecretKeySpec sha1Key = new SecretKeySpec(key, "HmacSHA1"); // Get an HMAC-SHA1 Mac instance and initialize it with the HMAC-SHA1 key Mac mac = Mac.getInstance("HmacSHA1"); mac.init(sha1Key); // compute the binary signature for the request byte[] sigBytes = mac.doFinal(resource.getBytes()); // base 64 encode the binary signature // Base64 is JDK 1.8 only - older versions may need to use Apache Commons or similar. String signature = Base64.getEncoder().encodeToString(sigBytes); // convert the signature to 'web safe' base 64 signature = signature.replace('+', '-'); signature = signature.replace('/', '_'); return resource + "&signature=" + signature; } }
Узел JS
В приведенном ниже примере для подписи URL-адреса используются собственные модули Node. ( Загрузить код.)
'use strict' const crypto = require('crypto'); const url = require('url'); /** * Convert from 'web safe' base64 to true base64. * * @param {string} safeEncodedString The code you want to translate * from a web safe form. * @return {string} */ function removeWebSafe(safeEncodedString) { return safeEncodedString.replace(/-/g, '+').replace(/_/g, '/'); } /** * Convert from true base64 to 'web safe' base64 * * @param {string} encodedString The code you want to translate to a * web safe form. * @return {string} */ function makeWebSafe(encodedString) { return encodedString.replace(/\+/g, '-').replace(/\//g, '_'); } /** * Takes a base64 code and decodes it. * * @param {string} code The encoded data. * @return {string} */ function decodeBase64Hash(code) { // "new Buffer(...)" is deprecated. Use Buffer.from if it exists. return Buffer.from ? Buffer.from(code, 'base64') : new Buffer(code, 'base64'); } /** * Takes a key and signs the data with it. * * @param {string} key Your unique secret key. * @param {string} data The url to sign. * @return {string} */ function encodeBase64Hash(key, data) { return crypto.createHmac('sha1', key).update(data).digest('base64'); } /** * Sign a URL using a secret key. * * @param {string} path The url you want to sign. * @param {string} secret Your unique secret key. * @return {string} */ function sign(path, secret) { const uri = url.parse(path); const safeSecret = decodeBase64Hash(removeWebSafe(secret)); const hashedSignature = makeWebSafe(encodeBase64Hash(safeSecret, uri.path)); return url.format(uri) + '&signature=' + hashedSignature; }
С#
В приведенном ниже примере для подписи URL-запроса используется библиотека System.Security.Cryptography
по умолчанию. Обратите внимание, что нам нужно преобразовать кодировку Base64 по умолчанию, чтобы реализовать версию, безопасную для URL. ( Загрузить код.)
using System; using System.Collections.Generic; using System.Security.Cryptography; using System.Text; using System.Text.RegularExpressions; using System.Web; namespace SignUrl { public struct GoogleSignedUrl { public static string Sign(string url, string keyString) { ASCIIEncoding encoding = new ASCIIEncoding(); // converting key to bytes will throw an exception, need to replace '-' and '_' characters first. string usablePrivateKey = keyString.Replace("-", "+").Replace("_", "/"); byte[] privateKeyBytes = Convert.FromBase64String(usablePrivateKey); Uri uri = new Uri(url); byte[] encodedPathAndQueryBytes = encoding.GetBytes(uri.LocalPath + uri.Query); // compute the hash HMACSHA1 algorithm = new HMACSHA1(privateKeyBytes); byte[] hash = algorithm.ComputeHash(encodedPathAndQueryBytes); // convert the bytes to string and make url-safe by replacing '+' and '/' characters string signature = Convert.ToBase64String(hash).Replace("+", "-").Replace("/", "_"); // Add the signature to the existing URI. return uri.Scheme+"://"+uri.Host+uri.LocalPath + uri.Query +"&signature=" + signature; } } class Program { static void Main() { // Note: Generally, you should store your private key someplace safe // and read them into your code const string keyString = "YOUR_PRIVATE_KEY"; // The URL shown in these examples is a static URL which should already // be URL-encoded. In practice, you will likely have code // which assembles your URL from user or web service input // and plugs those values into its parameters. const string urlString = "YOUR_URL_TO_SIGN"; string inputUrl = null; string inputKey = null; Console.WriteLine("Enter the URL (must be URL-encoded) to sign: "); inputUrl = Console.ReadLine(); if (inputUrl.Length == 0) { inputUrl = urlString; } Console.WriteLine("Enter the Private key to sign the URL: "); inputKey = Console.ReadLine(); if (inputKey.Length == 0) { inputKey = keyString; } Console.WriteLine(GoogleSignedUrl.Sign(inputUrl,inputKey)); } } }
Примеры на дополнительных языках
Примеры, охватывающие больше языков, доступны в проекте подписи URL-адресов .
Поиск неисправностей
Если запрос содержит недопустимую подпись, API возвращает ошибку HTTP 403 (Forbidden)
. Эта ошибка, скорее всего, возникает, если используемый секрет подписи не связан с переданным ключом API или если ввод, отличный от ASCII, не закодирован в URL-адресе перед подписанием.
Чтобы устранить проблему, скопируйте URL-адрес запроса, удалите параметр запроса signature
и повторно создайте действительную подпись, следуя инструкциям ниже:
Чтобы создать цифровую подпись с помощью ключа API с помощью виджета «Подписать URL сейчас» в Google Cloud Console:
- Найдите виджет «Подписать URL-адрес сейчас» , как описано в разделе «Шаг 1. Получите секрет подписи URL-адреса» .
- В поле URL-адрес вставьте URL-адрес неподписанного запроса из шага 2. Создание неподписанного запроса .
- Появившееся поле «Ваш подписанный URL-адрес» будет содержать ваш URL-адрес с цифровой подписью. Обязательно сделайте копию.