Tworzenie kluczy interfejsu API i zarządzanie nimi

Na tej stronie wyjaśniamy, jak tworzyć klucze API i zarządzać nimi przy użyciu interfejsu API Keys API.

Informacje o tym, jak używać klucza interfejsu API do wywoływania interfejsów API Google Cloud, znajdziesz w artykule Korzystanie z kluczy interfejsu API.

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.

Tworzę klucz interfejsu API

Klucz interfejsu API możesz utworzyć za pomocą metody CreateKey. Metoda wymaga parametru Key. Możesz określić tylko pola displayName i restrictions obiektu Key. Metoda CreateKey nie jest metodą synchroniczną. Zamiast tego po wywołaniu funkcji CreateKey inicjujesz długo działającą operację. Poniższy przykład powoduje wywołanie CreateKey w celu utworzenia klucza API bez ograniczeń:

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys -X POST -d '{"displayName" : "Example API key"}'

Jeśli operacja się powiedzie, w odpowiedzi zostanie zwrócona długoterminowa operacja. Zgodnie z opisem w sekcji Odpowiadanie na długo działające operacje wielokrotnie wywołujesz funkcję operations.get z wartością z pola name. Gdy odpowiedź z operations.get zawiera "done": true, obiekt response zawiera parametr Key podobny do tego:

{
  "name": "operations/akmf.p7-103621867718-06f94db2-7e91-4c58-b826-e6b80e4dc3eb",
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.api.apikeys.v2.Key",
    "name": "projects/PROJECT_NUMBER/locations/global/keys/aecd7943-98ff-4ce2-a876-ec1b37c671ca",
    "displayName": "Example API key",
    "keyString": "----REDACTED----",
    "createTime": "2021-03-23T17:39:46.721099Z",
    "uid": "aecd7943-98ff-4ce2-a876-ec1b37c671ca",
    "updateTime": "2021-03-23T17:39:47.046746Z",
    "etag": "k0bsYGkIvSxDVwNxyw49NQ=="
  }
}

W obiekcie response:

  • Pole name zawiera unikalny identyfikator klucza interfejsu API. Wartości z pola name używasz w innych metodach, które wymagają podania nazwy klucza. Ta wartość nie jest wyświetlana w Google Cloud Console, ale możesz wywołać metodę ListKeys, by uzyskać names dla wszystkich kluczy interfejsu API. Pole Key.name ma zawsze następujący format: projects/PROJECT_NUMBER/locations/global/keys/KEY_ID.
  • Pole displayName jest mapowane na pole Name w Cloud Console, więc podczas wywołania CreateKey możesz podać displayName.
  • Pole keyString zawiera ciąg, który wysyłasz do interfejsów API, które wymagają klucza interfejsu API. Pole keyString jest mapowane na pole API key w Cloud Console. Możesz wywołać metodę GetKeyString, by uzyskać keyString dla klucza interfejsu API.
  • Pole etag zawiera sumę kontrolną obliczoną przez serwer na podstawie bieżącej wartości klucza. Przekaż wartość etag podczas wywoływania metod UpdateKey i DeleteKey.

Identyfikator klucza określony przez użytkownika

Jako parametr zapytania dla metody CreateKey możesz określić parametr keyId. Po określeniu wartość staje się końcowym składnikiem właściwości Key.name.

Rozważmy na przykład to wywołanie funkcji CreateKey:

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys?keyId=my-test-key1 -X POST -d '{"displayName" : "Example API key"}'

W tym przykładzie pole Key.name ma następującą wartość:

    "name": "projects/PROJECT_NUMBER/locations/global/keys/my-test-key1"

Klonowanie klucza interfejsu API

Aby utworzyć kopię klucza interfejsu API w tym samym projekcie Cloud, użyj metody CloneKey. Wywołanie CloneKey powoduje rozpoczęcie długiej operacji, która powoduje utworzenie klucza o takich samych parametrach displayName i restrictions co oryginalny klucz, ale z nowymi wartościami name i keyString.

Poniższy przykład ilustruje, jak wywołać funkcję CloneKey:

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys/KEY_ID/:clone -X POST

Gdy odpowiedź z operations.get zawiera "done": true, response zawiera nowy obiekt Key.

Nowy klucz ma te same parametry displayName i restrictions co oryginalny, ale nowe name i keyString.

Aktualizowanie wyświetlanej nazwy

Aby zmienić displayName klucza API lub dodać displayName do klucza API, który został utworzony bez niego, wywołaj metodę UpdateKey. Wywołanie UpdateKey powoduje rozpoczęcie długiej operacji, która aktualizuje klucz.

Poniższy przykład ilustruje, jak wywołać funkcję UpdateKey:

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys/KEY_ID?updateMask=displayName -X PATCH -d '{"displayName": "New display name", "etag" : "ETAG"}'

Gdy odpowiedź z operations.get zawiera "done": true, response zawiera obiekt Key ze zaktualizowaną wersją displayName.

Usuwanie klucza interfejsu API

Aby usunąć klucz interfejsu API, użyj metody DeleteKey. Wywołanie DeleteKey powoduje rozpoczęcie długiej operacji, która oznacza klucz jako DELETED.

Poniższy przykład ilustruje, jak wywołać funkcję DeleteKey:

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys/KEY_ID?etag="ETAG" -X DELETE

Gdy odpowiedź z operations.get zawiera "done": true, response jest podobny do tego:

{
  "name": "operations/akmf.cdabc4df-cbff-4420-8c7e-65dc832c945d",
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.api.apikeys.v2.Key"
    "name": "projects/PROJECT_NUMBER/locations/global/keys/aecd7943-98ff-4ce2-a876-ec1b37c671ca",
    "displayName": "Example API key",
    "keyString": "----REDACTED----",
    "createTime": "2021-03-23T17:39:46.721099Z",
    "uid": "aecd7943-98ff-4ce2-a876-ec1b37c671ca",
    "updateTime": "2021-03-23T17:39:47.046746Z",
    "deleteTime": "2021-03-24T22:35:37.290544Z",
    "etag": "k0bsYGkIvSxDVwNxyw49NQ=="
  }
}

Nie można użyć klucza API oznaczonego jako DELETED, ale nie jest on też całkowicie usuwany z naszego systemu. Po 30 dniach klucz interfejsu API jest trwale usuwany. Do metody ListKeys możesz dodać filtr, który zwróci klucze API oznaczone jako DELETED:

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys/KEY_ID?filter=state:DELETED

Przywracanie klucza interfejsu API

Aby przywrócić klucz interfejsu API, zanim zostanie trwale usunięty, wywołaj metodę UndeleteKey. Wywołanie UndeleteKey powoduje rozpoczęcie długiej operacji, która oznacza klucz jako ACTIVE.

Poniższy przykład ilustruje, jak wywołać funkcję UndeleteKey:

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys/KEY_ID/:undelete -X POST

Co dalej?