Dodawanie ograniczeń do kluczy interfejsu API

Klucze API identyfikują Twoją aplikację lub witrynę w Google Cloud. Ograniczenia związane z kluczami interfejsu API zapewniają, że tylko Twoje aplikacje i witryny mogą z nich korzystać. Ze względów bezpieczeństwa zalecamy dodanie ograniczeń określających:

Jeśli klient używa ograniczonego klucza interfejsu API do wysyłania żądania, które nie spełnia ograniczeń związanych z kluczami interfejsu API, żądanie kończy się niepowodzeniem. Jeśli na przykład klucz API wymaga wysyłania żądań HTTP z konkretnej domeny, ale żądanie HTTP pochodzi z innej domeny, żądanie zostanie odrzucone z błędem.

Ograniczenia możesz dodawać podczas tworzenia klucza API za pomocą metody CreateKey lub po utworzeniu klucza za pomocą metody UpdateKey. Na tej stronie opisano ograniczenia, które można dodać do klucza interfejsu API, oraz sposób ich dodawania.

Zanim zaczniesz

Strona korzysta zcurl zoauth2l Narzędzie wiersza poleceń służące do wysyłania żądań do interfejsu API Keys API. Zobacz Pierwsze kroki z kluczami API, aby dowiedzieć się, jak rozpocząć eksperymentowanie z interfejsem API.

Dodawanie ograniczeń klienta

Ograniczenia klienta określają, które witryny, adresy IP lub aplikacje mogą używać klucza interfejsu API. Ograniczenia klienta są dodawane na podstawie typu klienta, który wywołuje interfejs API. Możesz określić jeden z następujących typów ograniczeń klienta:

  • browserKeyRestrictions: strony odsyłające HTTP (witryny), które mogą korzystać z klucza.
  • serverKeyRestrictions: adresy IP rozmówców, którzy mogą korzystać z klucza.
  • androidKeyRestrictions: aplikacje na Androida, które mogą używać klucza.
  • iosKeyRestrictions: aplikacje na iOS, które mogą używać klucza.

Dodawanie ograniczeń przeglądarki

Poniższy przykład pokazuje, jak wywołać metodę UpdateKey, by ograniczyć stronę odsyłającą HTTP do www.example.com:

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys/KEY_ID?updateMask=restrictions \
  --request PATCH \
  --data '{
    "restrictions" : {
      "browserKeyRestrictions": {
        "allowedReferrers": "www.example.com"
      }
    }
    "etag": "ETAG"
  }'

Gdy odpowiedź od operations.get zawiera "done": true, response zawiera zaktualizowane Key z ograniczeniami.

Poniższy przykład pokazuje, jak utworzyć nowy klucz API, który zezwala tylko na żądania HTTP z listy określonych adresów URL.

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys \
  --request POST \
  --data '{
    "displayName" : "API key with browser restrictions",
    "restrictions" : {
      "browserKeyRestrictions": {
        "allowedReferrers": ["www.example.com", "www.example-2.com"]
      }
    }
  }'

Poniższa tabela zawiera przykładowe scenariusze i ograniczenia przeglądarki:

Scenariusz Ograniczenia
Zezwól na dowolny adres URL w Twojej witrynie Musisz ustawić dwa adresy URL na liście „allowReferers”.
  1. Adres URL domeny bez subdomeny i z symbolem wieloznacznym dla ścieżki. Na przykład:
    example.com/*
  2. Drugi adres URL zawierający symbol wieloznaczny dla subdomeny i symbol wieloznaczny dla ścieżki. Na przykład:
    *.example.com/*
Zezwalaj na określony adres URL Dodaj URL z dokładną ścieżką. Na przykład:
www.example.com/path
www.example.com/path/path
Zezwalaj na wszystkie adresy URL w jednej subdomenie lub samej domenie Aby zezwolić na używanie całej domeny, musisz ustawić dwa adresy URL na liście „allowReferers”.
  1. Adres URL domeny bez ukośnika końcowego. Na przykład:
    www.example.com
    sub.example.com
    example.com
  2. Drugi adres URL domeny zawierający symbol wieloznaczny ścieżki. Na przykład:
    www.example.com/*
    sub.example.com/*
    example.com/*

Dodawanie ograniczeń serwera

Możesz określić co najmniej jeden adres IP wywołujących, na przykład serwery internetowe lub zadania cron, które mogą używać Twojego klucza interfejsu API. Adresy IP możesz określić w dowolnym z tych formatów:

  • IPv4 (198.51.100.1)
  • IPv6 (2001:db8::1)
  • Podsieć korzystająca z zapisu CIDR (198.51.100.0/24, 2001:db8::/64)

Poniższy przykład pokazuje, jak utworzyć klucz interfejsu API z listą allowedIps:

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys  \
  --request POST \
  --data  '{
    "displayName" : "API key with server restrictions with IPv4, IPv6 and CIDR",
    "restrictions" : {
      "serverKeyRestrictions": {
        "allowedIps": ["198.51.100.1","198.51.100.0/24","2001:db8::1","2001:db8::/64"]
      }
    }
  }'

Dodawanie ograniczeń Androida

Możesz ograniczyć użycie klucza API tylko do aplikacji na Androida. Podczas tworzenia lub aktualizowania klucza interfejsu API podaj nazwę pakietu i odcisk cyfrowy SHA-1 dla każdej aplikacji.

Załóżmy na przykład, że uruchomiono narzędzie keytool i utworzono następujący odcisk cyfrowy:

  Certificate fingerprint: SHA1: DA:39:A3:EE:5E:6B:4B:0D:32:55:BF:EF:95:60:18:90:AF:D8:07:09

Poniższy przykład pokazuje, jak utworzyć klucz interfejsu API z odciskiem palca i nazwą pakietu w androidKeyRestrictions:

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys  \
  --request POST \
  --data  '{
    "displayName" : "API key with Android restrictions",
    "restrictions" : {
      "androidKeyRestrictions": {
        "allowedApplications": [
          {
            "sha1Fingerprint": "DA:39:A3:EE:5E:6B:4B:0D:32:55:BF:EF:95:60:18:90:AF:D8:07:09",
            "packageName": "com.example.my.app"
          }
        ]
      }
    }
  }'

Dodawanie ograniczeń systemu iOS

Możesz ograniczyć użycie klucza interfejsu API tylko do aplikacji na iOS, podając identyfikator pakietu każdej aplikacji podczas tworzenia lub aktualizowania klucza. Poniższy przykład pokazuje, jak ustawić klucz iosKeyRestrictions podczas tworzenia klucza API:

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys  \
  --request POST \
  --data  '{
    "displayName" : "API key with iOs restrictions",
    "restrictions" : {
      "iosKeyRestrictions": {
        "allowedBundleIds": ["com.example.my.app1", "com.example.my.app2"]
      }
    }
  }'

Dodawanie ograniczeń interfejsu API

Ograniczenia interfejsu API pozwalają określić, które interfejsy API Google Cloud można wywoływać za pomocą klucza interfejsu API. Zalecamy dodanie do wszystkich kluczy interfejsu API zarówno ograniczeń klienta, jak i interfejsu API.

Możesz określić jedną lub więcej usług w ograniczeniach interfejsu API. Poniższy przykład pokazuje, jak ograniczyć używanie nowego klucza API tylko do usług translate.googleapis.com i datastore.googleapis.com:

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys  \
  --request POST \
  --data '{
    "restrictions": {
      "api_targets": [
        {
          "service": "translate.googleapis.com"
        },
        {
          "service" : "datastore.googleapis.com"
        }
      ]
    },
  }'

Aby uzyskać listę usług włączonych w projekcie Cloud, użyj polecenia gcloud services list.

Oprócz ograniczenia klucza interfejsu API do używania w określonych usługach możesz opcjonalnie określić metody w każdej usłudze, aby dodatkowo ograniczyć ten klucz. Poniższy przykład pokazuje, jak ograniczyć poprzedni klucz tylko do dozwolonych metod translate.googleapis.com:

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys/KEY_ID?updateMask=restrictions  \
  --request PATCH \
  --data '{
    "restrictions": {
      "api_targets": [
        {
          "service": "translate.googleapis.com"
          "methods": [
            "Get*",
            "DetectLanguage"
          ]
        },
        {
          "service" : "datastore.googleapis.com"
        }
      ]
    },
    "etag": "ETAG"
  }'

Co dalej?