این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

امضای درخواست شناسه مشتری

مهم: طرح ویژه پلتفرم نقشه‌های گوگل دیگر برای ثبت‌نام‌کنندگان یا مشتریان جدید در دسترس نیست.

امضاهای دیجیتال

نحوه عملکرد امضاهای دیجیتال

امضاهای دیجیتال با استفاده از یک راز امضای URL یا کلید رمزنگاری تولید می‌شوند که در کنسول Google Cloud موجود است. این راز اساساً یک کلید خصوصی است که فقط بین شما و گوگل به اشتراک گذاشته می‌شود و مختص شناسه کلاینت شماست.

فرآیند امضا از یک الگوریتم رمزگذاری برای ترکیب URL و رمز مشترک شما استفاده می‌کند. امضای منحصر به فرد حاصل به سرورهای ما اجازه می‌دهد تا تأیید کنند که هر سایتی که با استفاده از شناسه کلاینت شما درخواست ایجاد می‌کند، مجاز به انجام این کار است.

امضای درخواست‌های شما

امضای درخواست‌های شما شامل مراحل زیر است:

مرحله ۱: رمز امضای URL خود را دریافت کنید
مرحله ۲: ساخت یک درخواست بدون امضا
مرحله ۳: ایجاد درخواست امضا شده

مرحله ۱: رمز امضای URL خود را دریافت کنید

برای دریافت امضای مخفی URL پروژه خود:

به صفحه شناسه کلاینت در کنسول Cloud بروید.
فیلد کلید (Key) شامل رمز امضای URL شناسه کلاینت فعلی شما است.

اگر نیاز به بازسازی رمز امضای URL شناسه کلاینت خود دارید، با پشتیبانی تماس بگیرید .

مرحله ۲: درخواست امضا نشده خود را بسازید

کاراکترهایی که در جدول زیر فهرست نشده‌اند باید با URL کدگذاری شوند:

خلاصه‌ای از کاراکترهای معتبر URL

تنظیم	شخصیت‌ها	استفاده از آدرس اینترنتی (URL)
الفبایی-عددی	abcdefghijklm nopqrstuvwxyz ABCDEFGHIJKLM NOPQRSTUVWXYZ 0 1 2 3 4 5 6 7 8 9	رشته‌های متنی، استفاده از طرح ( `http` )، پورت ( `8080` ) و غیره.
بدون رزرو	- _ . ~	رشته‌های متنی
رزرو شده	! * '(); : @ & = + $ , / ? % # [ ]	کاراکترهای کنترلی و/یا رشته‌های متنی

همین امر در مورد هر کاراکتری که در مجموعه رزرو شده قرار دارد، در صورتی که درون یک رشته متنی قرار گیرد، صدق می‌کند. برای اطلاعات بیشتر، به کاراکترهای ویژه مراجعه کنید.

آدرس اینترنتی درخواست امضا نشده خود را بدون امضا بسازید.

مطمئن شوید که شناسه کلاینت را نیز در پارامتر client وارد کنید. برای مثال:

https://maps.googleapis.com/maps/api/staticmap?center=Z%C3%BCrich&size=400x400&client=YOUR_CLIENT_ID

درخواست امضا شده را ایجاد کنید

برای عیب‌یابی، می‌توانید با استفاده از ویجت موجود «الان یک URL را امضا کن»، به‌طور خودکار یک امضای دیجیتال ایجاد کنید.

برای درخواست‌های تولید شده به صورت پویا، به امضای سمت سرور نیاز دارید که مستلزم چند مرحله میانی اضافی است.

در هر صورت، در نهایت باید یک URL درخواست داشته باشید که یک پارامتر signature به انتهای آن اضافه شده است. برای مثال:

https://maps.googleapis.com/maps/api/staticmap?center=Z%C3%BCrich&size=400x400&client=YOUR_CLIENT_ID
&signature=BASE64_SIGNATURE

طرح پروتکل و بخش‌های میزبان URL را حذف کنید و فقط مسیر و پرس‌وجو را باقی بگذارید:

/maps/api/staticmap?center=Z%C3%BCrich&size=400x400&client=YOUR_CLIENT_ID

رمز امضای URL نمایش داده شده در یک Base64 اصلاح شده برای URLها کدگذاری شده است.
از آنجایی که اکثر کتابخانه‌های رمزنگاری نیاز دارند که کلید در قالب بایت خام باشد، احتمالاً قبل از امضا، باید رمز امضای URL خود را به قالب خام اصلی آن رمزگشایی کنید.
درخواست حذف‌شده‌ی فوق را با استفاده از HMAC-SHA1 امضا کنید.
از آنجایی که اکثر کتابخانه‌های رمزنگاری، امضا را در قالب بایت خام تولید می‌کنند، شما باید امضای دودویی حاصل را با استفاده از Base64 اصلاح‌شده برای URLها تبدیل کنید تا آن را به چیزی تبدیل کنید که بتواند درون URL منتقل شود.
نکته: Base64 اصلاح‌شده برای URLها، کاراکترهای + و / در Base64 استاندارد را به ترتیب با - و _ جایگزین می‌کند، به طوری که این Base64ها دیگر نیازی به کدگذاری URL ندارند.
امضای رمزگذاری شده با Base64 را به URL درخواست امضا نشده اصلی در پارامتر signature اضافه کنید. برای مثال:
```
https://maps.googleapis.com/maps/api/staticmap?center=Z%C3%BCrich&size=400x400&client=YOUR_CLIENT_ID
&signature=BASE64_SIGNATURE
```

برای نمونه‌هایی که روش‌های پیاده‌سازی امضای URL با استفاده از کد سمت سرور را نشان می‌دهند، به کد نمونه برای امضای URL در زیر مراجعه کنید.

نمونه کد برای امضای URL

بخش‌های زیر روش‌های پیاده‌سازی امضای URL با استفاده از کد سمت سرور را نشان می‌دهند. URLها همیشه باید سمت سرور امضا شوند تا از افشای رمز امضای URL شما برای کاربران جلوگیری شود.

پایتون

مثال زیر از کتابخانه‌های استاندارد پایتون برای امضای یک URL استفاده می‌کند. (کد را دانلود کنید .)

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

نود جی‌اس

مثال زیر از ماژول‌های بومی Node برای امضای یک URL استفاده می‌کند. (کد را دانلود کنید .)

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

سی شارپ

مثال زیر از کتابخانه پیش‌فرض System.Security.Cryptography برای امضای یک درخواست URL استفاده می‌کند. توجه داشته باشید که برای پیاده‌سازی یک نسخه امن برای URL، باید کدگذاری پیش‌فرض Base64 را تبدیل کنیم. (کد را دانلود کنید .)

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-signing موجود است.

عیب‌یابی

اگر درخواست شامل امضای نامعتبر باشد، API خطای HTTP 403 (Forbidden) را برمی‌گرداند. این خطا به احتمال زیاد زمانی رخ می‌دهد که رمز امضای استفاده شده به شناسه کلاینت ارسالی مرتبط نباشد، یا اگر ورودی غیر ASCII قبل از امضا، URL-encode نشده باشد.

برای عیب‌یابی مشکل، آدرس اینترنتی درخواست را کپی کنید، پارامتر جستجوی signature را حذف کنید و با دنبال کردن دستورالعمل‌های زیر، یک امضای معتبر را دوباره ایجاد کنید:

برای تولید امضای دیجیتال با شناسه کلاینت خود با استفاده از ویجت Sign a URL now در زیر:

رمز امضای URL شناسه کلاینت خود را، همانطور که در مرحله 1 توضیح داده شده است، دریافت کنید: رمز امضای URL خود را دریافت کنید .
در فیلد URL ، آدرس اینترنتی درخواست امضا نشده خود را از مرحله ۲: ساخت درخواست امضا نشده خود، جایگذاری کنید.
در فیلد «رمز امضای URL» ، رمز امضای URL خود را از مرحله ۲ وارد کنید.
یک امضای دیجیتال بر اساس URL درخواست امضا نشده و رمز امضای شما ایجاد شده و به URL اصلی شما ضمیمه می‌شود.
فیلد «نشانی اینترنتی امضا شده شما» که ظاهر می‌شود، حاوی نشانی اینترنتی امضا شده دیجیتالی شما خواهد بود.