Elevation API: Mendapatkan Kunci API

Catatan: Premium Plan Google Maps Platform tidak lagi tersedia untuk pendaftar atau pelanggan baru.

Memilih metode autentikasi

Untuk menggunakan Elevation API, Anda harus mengautentikasi permintaan menggunakan kunci API atau client ID dan tanda tangan digital.

Metode autentikasi yang Anda pilih didasarkan pada lisensi Anda:

  • Pelanggan dengan Premium Plan dapat menggunakan kunci API atau client ID dan tanda tangan digital.
  • Pelanggan dengan lisensi sebelumnya harus menggunakan client ID dan tanda tangan digital.

Punya Premium Plan atau lisensi sebelumnya?
Untuk mengetahui lisensi yang Anda miliki:
> Di Portal Dukungan Google Cloud, klik Maps: Laporan Penggunaan di sebelah kiri.
> Apakah ID di bagian atas laporan memiliki format berikut?
   gme-[company] & proj-[number] ([type])
Jika ya, berarti Anda memiliki Premium Plan.
Jika tidak, berarti Anda memiliki lisensi sebelumnya (Maps API for Work atau Maps API for Business).

Saat memutuskan metode autentikasi yang akan digunakan, pertimbangkan hal-hal berikut ini:

  • Autentikasi menggunakan kunci API (Premium Plan)
    Dengan menggunakan kunci API untuk mengautentikasi permintaan, Anda dapat:
  • Autentikasi menggunakan client ID dan tanda tangan digital (Premium Plan atau lisensi sebelumnya)
    Dengan menggunakan client ID dan tanda tangan digital untuk mengautentikasi permintaan, Anda dapat:
    • Menambahkan parameter channel ke permintaan sehingga Anda dapat melihat laporan penggunaan yang lebih detail.
    • Melihat laporan penggunaan berisi data lebih dari 30 hari di Portal Dukungan Google Cloud.
    • Menggunakan alat Maps Analytics untuk Maps JavaScript API.

Dapatkan informasi selengkapnya tentang laporan yang tersedia untuk pelanggan Premium Plan.

Autentikasi menggunakan kunci API

Mendapatkan kunci API

Kunci API adalah ID unik yang digunakan untuk mengautentikasi permintaan yang dikaitkan dengan project untuk tujuan penggunaan dan penagihan.

Cara mendapatkan kunci API:

  1. Di GCP Console, pada halaman pemilih project, pilih atau buat project Google Cloud yang ingin Anda tambahkan kunci API.

    Buka halaman pemilih project

    Catatan: Untuk mendapatkan akses penuh ke fitur yang terdapat dalam paket, pelanggan Premium harus menggunakan project yang dikaitkan dengan akun Premium mereka. Saat membeli lisensi, Anda menerima nama aset Premium Anda dalam format berikut: gme-[company] & proj-[number] ([type]). Untuk memastikan Anda mengakses project yang benar, login ke konsol sebagai pemilik project menggunakan console.cloud.google.com/project/number (ganti number dengan nomor project Anda). Anda dapat menemukan pemilik project di email selamat datang.

  2. Buka halaman API & Layanan > Kredensial.

    Buka halaman Kredensial

  3. Pada halaman Kredensial, klik Buat kredensial > Kunci API.
    Dialog Kunci API dibuat menampilkan kunci API yang baru dibuat.
  4. Klik Tutup.
    Kunci API baru dicantumkan pada halaman Kredensial di bagian Kunci API.
    (Jangan lupa untuk membatasi kunci API sebelum menggunakannya dalam produksi.)

Menambahkan kunci API ke permintaan

Anda harus menyertakan kunci API pada setiap permintaan Elevation API. Pada contoh berikut, ganti YOUR_API_KEY dengan kunci API Anda.

https://maps.googleapis.com/maps/api/elevation/json?locations=39.7391536,-104.9847034&key=YOUR_API_KEY

Membatasi kunci API

Membatasi Kunci API akan meningkatkan keamanan aplikasi Anda dengan memastikan hanya permintaan yang sah yang dibuat dengan Kunci API Anda. Sebaiknya Anda mengikuti petunjuk untuk menetapkan pembatasan pada Kunci API Anda. Untuk mengetahui informasi selengkapnya, lihat Praktik Terbaik Kunci API.

Cara membatasi kunci API:

  1. Di GCP Console, pada halaman pemilih project, pilih atau buat project Google Cloud yang ingin Anda tambahkan kunci API.

    Buka halaman pemilih project

  2. Buka halaman API & Layanan > Kredensial.

    Buka halaman Kredensial

  3. Pilih kunci API yang ingin Anda batasi. Halaman properti kunci API akan muncul.
  4. Di bagian Pembatasan kunci, tetapkan pembatasan berikut:
    • Pembatasan aplikasi:
      1. Untuk menerima permintaan dari daftar alamat IP server web yang Anda berikan, pilih alamat IP (server web, cron job, dll.) dari daftar Pembatasan aplikasi.
      2. Tentukan satu alamat IPv4 atau IPv6, atau subnet menggunakan notasi CIDR (misalnya, 192.168.0.0/22). Jika Anda perlu memasukkan entri lain, kotak baru akan muncul setelah Anda selesai menambahkan entri sebelumnya.
    • Pembatasan API:
      1. Klik Batasi kunci.
      2. Pilih Elevation API dari drop-down Pilih API.
        (Jika Elevation API tidak tercantum, Anda harus mengaktifkannya.)
  5. Untuk menyelesaikan perubahan, klik Simpan.

Mengautentikasi menggunakan client ID dan tanda tangan digital

Setelah membeli lisensi Premium Plan Google Maps Platform, Anda akan menerima email selamat datang dari Google yang berisi client ID dan kunci kriptografis pribadi Anda (yang dapat digunakan untuk membuat tanda tangan digital unik).

Contoh kode di bawah ini menunjukkan parameter client dan signature tujuan penerusan client ID dan tanda tangan digital unik Anda.

    https://maps.googleapis.com/maps/api/elevation/json
      ?locations=39.7391536,-104.9847034
      &client=YOUR_CLIENT_ID
      &signature=SIGNATURE
  • Ganti YOUR_CLIENT_ID dengan client ID yang tercantum di email selamat datang.

    Client ID Anda diawali dengan karakter gme-.

  • Ganti SIGNATURE dengan tanda tangan digital unik Anda (lihat Membuat tanda tangan digital).

Catatan:

  • Sebagai opsi, Anda dapat menggunakan parameter channel saat mengautentikasi Elevation API menggunakan client ID dan tanda tangan digital untuk menerima laporan penggunaan yang lebih detail. Lihat Ringkasan Pelaporan Premium Plan untuk mengetahui informasi selengkapnya.
  • Jika sebelumnya Anda menggunakan kunci API untuk autentikasi, kemudian beralih menggunakan client ID, Anda harus menghapus parameter key dari permintaan. Layanan web Google Maps API akan menolak permintaan yang dibuat dengan client ID dan kunci API sekaligus.

Membuat tanda tangan digital

Permintaan ke Elevation API oleh pelanggan Premium Plan Google Maps Platform memerlukan signature digital yang dapat dibuat menggunakan kunci kriptografis pribadi yang diberikan kepada Anda di email selamat datang (lihat Selengkapnya tentang kunci kriptografis pribadi).

Ikuti langkah-langkah membuat tanda tangan digital untuk permintaan Anda di bawah ini.

  1. Buat URL permintaan tanpa tanda tangan, pastikan untuk menyertakan parameter client. Perhatikan bahwa semua karakter non-standar perlu dienkodekan ke URL:

    https://maps.googleapis.com/maps/api/elevation/json?locations=39.7391536,-104.9847034&client=clientID

    Catatan: Semua layanan Google memerlukan encoding karakter UTF-8 (yang secara implisit menyertakan ASCII). Jika aplikasi Anda beroperasi menggunakan himpunan karakter lain, pastikan URL dibuat menggunakan UTF-8 dan dienkode ke URL dengan benar.

  2. Hilangkan bagian domain dari permintaan, dengan menyisakan jalur dan kueri saja:

    /maps/api/elevation/json?locations=39.7391536,-104.9847034&client=clientID

  3. Ambil kunci pribadi Anda, yang dienkode di Base64 yang dimodifikasi untuk URL, lalu tanda tangani URL di atas menggunakan algoritme HMAC-SHA1. Anda mungkin perlu mendekode kunci ini ke format biner asalnya. Perhatikan bahwa tanda tangan yang dihasilkan di hampir semua library kriptografi akan memiliki format biner.

    Catatan: Base64 yang dimodifikasi untuk URL akan mengganti karakter + dan / dari Base64 standar dengan - dan _, sehingga semua tanda tangan Base64 tidak perlu lagi dienkode ke URL.

  4. Enkodekan tanda tangan biner yang dihasilkan dengan menggunakan Base64 yang dimodifikasi untuk URL untuk mengonversi tanda tangan ini menjadi sesuatu yang dapat diteruskan dalam URL.

  5. Sertakan tanda tangan ini ke URL dalam parameter signature:

    https://maps.googleapis.com/maps/api/elevation/json?locations=39.7391536,-104.9847034&client=clientID&signature=base64signature

Catatan:

  • Tanda tangan unik memungkinkan server kami memverifikasi bahwa situs yang menghasilkan permintaan menggunakan client ID Anda telah diizinkan untuk melakukannya. Tanda tangan tersebut juga bersifat unik untuk setiap URL, sehingga memastikan permintaan yang menggunakan client ID Anda tidak bisa dimodifikasi tanpa mengharuskan pembuatan tanda tangan baru.
  • Mencoba mengakses Elevation API dengan tanda tangan yang tidak valid akan menyebabkan error HTTP 403 (Dilarang). Saat mengonversi aplikasi Anda untuk menggunakan penandatanganan URL, pastikan Anda menguji tanda tangan Anda untuk memastikan tanda tangan tersebut menghasilkan permintaan yang valid. Anda harus terlebih dahulu menguji apakah URL asli sudah valid serta apakah Anda menghasilkan tanda tangan yang benar.
  • Untuk contoh yang menunjukkan cara menerapkan penandatanganan URL menggunakan kode sisi server, lihat Kode contoh untuk penandatanganan URL.

Untuk menandatangani URL sekarang, masukkan URL dan rahasia penandatanganan URL Anda di bawah ini. URL tersebut harus memiliki format seperti yang dijelaskan di langkah 1 di atas, dan dienkode ke URL.

Kode contoh untuk penandatanganan URL

Bagian berikut ini menunjukkan cara mengimplementasikan penandatanganan URL menggunakan kode sisi server. URL harus selalu ditandatangani sisi server agar kunci kriptografis tidak dapat dilihat pengguna.

Python

Contoh di bawah ini menggunakan library Python standar untuk menandatangani URL. (Download kodenya.)

#!/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

Contoh di bawah ini menggunakan class java.util.Base64 yang tersedia sejak JDK 1.8 - versi lama mungkin perlu menggunakan Apache Commons atau yang serupa. (Download kodenya.)

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;
  }
}

Node.js

Contoh di bawah ini menggunakan modul Node native untuk menandatangani URL. (Download kodenya.)

'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;
}

C#

Contoh di bawah ini menggunakan library System.Security.Cryptography default untuk menandatangani permintaan URL. Perhatikan bahwa kita perlu mengonversi encoding Base64 default untuk mengimplementasikan versi yang aman untuk URL. (Download kodenya.)

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

Untuk keperluan pengujian, Anda bisa menguji URL dan kunci pribadi berikut untuk mengetahui apakah URL dan kunci tersebut menghasilkan tanda tangan yang benar. Perhatikan bahwa kunci pribadi ini hanya untuk keperluan pengujian dan tidak akan divalidasi oleh layanan Google.

  • URL: https://maps.googleapis.com/maps/api/geocode/json?address=New+York&client=clientID
  • Kunci Pribadi: vNIXE0xscrmjlyV-12Nj_BvUPaw=
  • Bagian URL untuk Ditandatangani: /maps/api/geocode/json?address=New+York&client=clientID
  • Tanda Tangan: chaRF2hTJKOScPr-RQCEhZbSzIE=
  • URL Lengkap yang Ditandatangani: https://maps.googleapis.com/maps/api/geocode/json?address=New+York&client=clientID&signature=chaRF2hTJKOScPr-RQCEhZbSzIE=

Contoh dalam bahasa lain

Contoh yang mencakup lebih banyak bahasa tersedia di project penandatanganan URL.

Selengkapnya tentang kunci kriptografis pribadi

Kunci penandatanganan URL kriptografis pribadi Anda akan diterbitkan bersama client ID Anda dan merupakan "kunci bersama rahasia" antara Anda dan Google. Kunci penandatanganan ini adalah milik Anda sendiri dan bersifat unik terhadap client ID Anda. Oleh karena itu, pastikan kunci penandatanganan Anda tetap aman. Kunci ini tidak boleh diteruskan dalam permintaan, disimpan di situs, atau diposting ke forum publik. Siapa pun yang mendapatkan kunci penandatanganan ini dapat memalsukan permintaan dengan menggunakan identitas Anda.

Catatan: Kunci penandatanganan kriptografis pribadi ini tidak sama dengan kunci API yang diterbitkan oleh Google Cloud Platform Console.

Jika Anda kehilangan kunci kriptografis pribadi, login ke Portal Dukungan Google Cloud lalu klik Maps: Kelola Client ID untuk mengambilnya.

Memecahkan masalah autentikasi

Jika permintaan Anda salah format atau memberikan tanda tangan yang tidak valid, Elevation API akan menampilkan error HTTP 403 (Forbidden).

Untuk memecahkan setiap masalah URL, Anda dapat menggunakan Debugger Penandatanganan URL. Alat bantu ini memungkinkan Anda untuk memvalidasi URL dan tanda tangan yang dihasilkan oleh aplikasi Anda secara cepat.

Atau, pelanggan Premium Plan dapat memecahkan setiap masalah URL dengan login ke Portal Dukungan Google Cloud lalu memilih Resource > Alat online Premium Plan Google Maps Platform > Debugger Penandatanganan URL untuk Web Service API dan Image API.