Konfigurowanie interfejsu Places API (nowość)

Deweloperzy z Europejskiego Obszaru Gospodarczego (EOG)

Jeśli Twój adres rozliczeniowy znajduje się w Europejskim Obszarze Gospodarczym, od 8 lipca 2025 r. do korzystania z usług będą miały zastosowanie Warunki korzystania z usługi Google Maps Platform w EOG. Funkcje różnią się w zależności od regionu. Więcej informacji

W tym dokumencie opisujemy, jak zacząć korzystać z Places API (New).

Wymagania wstępne

Ta procedura przeprowadzi Cię przez proces konfigurowania konta Google Cloud i projektu w chmurze Google Cloud z włączonymi płatnościami. Musisz też wiedzieć, jak naliczane są opłaty za korzystanie z interfejsu Places API (New).

1. Sprawdź rozliczenia i koszty użytkowania w sekcji Użytkowanie i rozliczenia Places API (nowego).

2. Sprawdź, czy masz konto Google Cloud.

   Zaloguj się w konsoli Google Cloud
   Uwaga: jeśli jesteś nowym użytkownikiem i nie masz konta Google Cloud, co oznacza, że nie możesz zalogować się w konsoli, zapoznaj się z artykułem Pierwsze kroki z Google Maps Platform.

3. Sprawdź, czy masz projekt Google Cloud z włączonymi płatnościami.

   Otwórz stronę Płatności
   Uwaga: jeśli jesteś nowym użytkownikiem i nie masz projektu w chmurze Google, zapoznaj się z artykułem Pierwsze kroki z Google Maps Platform.
1. Wybierz projekt, aby otworzyć stronę Płatności.

2. Na stronie Płatności:

   • Jeśli w wybranym projekcie płatności są już włączone i masz tylko jedno konto rozliczeniowe, otworzy się strona Płatności.
   • Jeśli masz kilka kont rozliczeniowych, kliknij Przejdź do połączonego konta, aby wyświetlić szczegóły konta rozliczeniowego powiązanego z projektem.
   • Jeśli konto rozliczeniowe istnieje, ale nie jest powiązane z projektem, pojawi się prośba o połączenie konta rozliczeniowego z projektem.
   • Jeśli nie masz konta rozliczeniowego lub chcesz utworzyć nowe, wybierz Zarządzaj kontami rozliczeniowymi, aby utworzyć nowe konto rozliczeniowe. Więcej informacji znajdziesz w artykule o tworzeniu nowego samoobsługowego konta rozliczeniowego Cloud.

Włącz API

Zanim zaczniesz korzystać z Places API (New), musisz włączyć go w projekcie Google Cloud za pomocą konsoli Google Cloud lub polecenia gcloud.

Uwaga: po włączeniu interfejsu API może minąć kilka minut, zanim będzie można wysłać do niego żądanie.

Aby włączyć interfejs API:

Konsola

1. Otwórz stronę produktu w konsoli Google Cloud:

   Włączanie Places API (nowość)

2. Kliknij przycisk Włącz.

   Uwaga: jeśli interfejs API jest już włączony, zamiast przycisku Włącz zobaczysz przycisk Zarządzaj.

gcloud

gcloud services enable \
    --project "PROJECT" \
    "places.googleapis.com"

Więcej informacji o pakiecie SDK Google Cloud, instalacji pakietu SDK Cloud i tych poleceniach:

• gcloud services enable
• gcloud services disable

Uzyskiwanie klucza interfejsu API do użycia z Places API (nowość)

Ważne: ten przewodnik po konfiguracji zawiera procedurę konfigurowania klucza interfejsu API i tworzenia tokena OAuth. Wybierz procedurę odpowiednią dla Twojego środowiska wdrażania.

Usługi Google Maps Platform są zabezpieczone przed nieautoryzowanym użyciem, ponieważ wymagają, aby wywołania interfejsu API zawierały klucz interfejsu API lub token OAuth. Najpierw należy wykonać procedurę dotyczącą klucza interfejsu API. Jeśli chcesz użyć tokena OAuth, zapoznaj się z artykułem Tworzenie tokena OAuth.

Klucz interfejsu API to unikalny ciąg alfanumeryczny, który wiąże Twoje konto rozliczeniowe Cloud i projekt w chmurze Google Cloud z żądaniem wysyłanym przez aplikację do interfejsu API lub pakietu SDK Google Maps Platform. Aby utworzyć nowy klucz lub dodać interfejs API bądź pakiet SDK do istniejącego klucza, wykonaj te instrukcje.

Konsola

1. Otwórz stronę Google Maps Platform > Klucze i dane logowania.

   Otwórz stronę Klucze i dane uwierzytelniające

2. Jeśli pojawi się taka prośba, wybierz projekt.

3. Wykonaj jedną z tych czynności:

   • Utwórz nowy klucz:

     1. Kliknij Utwórz dane logowania > Klucz interfejsu API.
     2. W panelu Utwórz klucz interfejsu API otwórz listę Wybierz ograniczenia interfejsu API.
     3. Odznacz wszystkie interfejsy API, których ten klucz nie potrzebuje, i upewnij się, że interfejs Places API (New) jest zaznaczony.
     4. Kliknij Utwórz. W panelu pojawi się nowy klucz interfejsu API.

   • Użyj istniejącego klucza:

     1. Kliknij nazwę klucza.
     2. Na liście Wybierz ograniczenia interfejsu API wybierz Places API (New).
     3. Kliknij Zapisz.

   Wybranie interfejsu API w tym miejscu nie powoduje jego włączenia. Upewnij się, że interfejs Places API (nowy) jest włączony na stronie Biblioteka API.

4. Aby później wyświetlić ciąg klucza, otwórz stronę Klucze i dane uwierzytelniające i kliknij Pokaż klucz.

Jeśli konsola wygląda inaczej niż w tych krokach, zapoznaj się z artykułami Tworzenie klucza interfejsu API i Dodawanie ograniczeń interfejsu API w dokumentacji Google Cloud.

gcloud

W poniższych poleceniach zastąp PROJECT_ID identyfikatorem swojego projektu.

• Utwórz nowy klucz: uruchom to polecenie i zastąp DISPLAY_NAME nazwą klucza.

  gcloud services api-keys create \
      --project="PROJECT_ID" \
      --display-name="DISPLAY_NAME" \
      --api-target=service=places.googleapis.com

  Więcej informacji o pakiecie SDK Google Cloud, instalacji pakietu SDK Cloud i tych poleceniach:

  • gcloud services api-keys create

• Użyj istniejącego klucza: uruchom to polecenie i zastąp KEY_ID identyfikatorem klucza. Flaga --append zachowuje interfejsy API, które klucz już dopuszcza. Bez niego polecenie zastępuje je.

  gcloud services api-keys update KEY_ID \
      --project="PROJECT_ID" \
      --append \
      --api-target=service=places.googleapis.com

  Więcej informacji o pakiecie SDK Google Cloud, instalacji pakietu SDK Cloud i tych poleceniach:

  • gcloud services api-keys update
  • gcloud services api-keys list

  Identyfikator klucza nie jest ciągiem klucza ani wyświetlaną nazwą. Aby go znaleźć, uruchom gcloud services api-keys list --project="PROJECT_ID". Identyfikator to ostatnia część pola name: projects/PROJECT_NUMBER/locations/global/keys/KEY_ID.

Aby zobaczyć ciąg klucza, uruchom gcloud services api-keys get-key-string KEY_ID --project="PROJECT_ID".

Wysyłanie żądania do interfejsu API

Wyślij żądanie do interfejsu Places API (New), aby uzyskać odpowiedź JSON na zapytanie Wyszukaj tekst „Spicy Vegetarian Food in Sydney, Australia” (Pikantne jedzenie wegetariańskie w Sydney, Australia). Musisz dołączyć ciąg alfanumeryczny klucza interfejsu API do każdego żądania i używać protokołu HTTPS w przypadku żądań zawierających klucz interfejsu API.

1. Kliknij API_KEY w poniższym kodzie, aby wstawić ciąg alfanumeryczny klucza:

   curl -X POST -d '{
     "textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
   }' \
   -H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
   -H 'X-Goog-FieldMask: places.displayName,places.formattedAddress,places.priceLevel' \
   'https://places.googleapis.com/v1/places:searchText'

2. Kliknij ikonę kopiowania w przykładowym kodzie , aby skopiować polecenie curl.
3. Wklej polecenie w oknie terminala i uruchom je.

Odpowiedzią jest obiekt JSON w formacie:

{
  "places": [
    {
      "name": "places/ChIJs5ydyTiuEmsR0fRSlU0C7k0",
      "id": "ChIJs5ydyTiuEmsR0fRSlU0C7k0",
      "types": [
        "vegan_restaurant",
        "vegetarian_restaurant",
        "meal_takeaway",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "nationalPhoneNumber": "0433 479 794",
      "internationalPhoneNumber": "[phone]",
      "formattedAddress": "29 King St, Sydney NSW 2000, Australia",
      "addressComponents": [
        {
          "longText": "29",
          "shortText": "29",
          "types": [
            "street_number"
          ],
          "languageCode": "en-US"
        },
  ...
}

Stosowanie ograniczeń klucza interfejsu API

Uwaga: nieograniczonego klucza interfejsu API można używać do wysyłania żądań do dowolnej usługi Google Maps Platform, w tym do Places API (New). Ponoszą Państwo odpowiedzialność finansową za opłaty spowodowane nadużyciem kluczy interfejsu API bez ograniczeń.

Google zdecydowanie zaleca ograniczenie kluczy interfejsu API przez ograniczenie ich użycia tylko do tych interfejsów API i aplikacji, które ich potrzebują. Ograniczenie kluczy interfejsu API zwiększa bezpieczeństwo aplikacji, chroniąc ją przed nieuzasadnionymi żądaniami. Klucze interfejsu API obsługują 2 rodzaje ograniczeń:

• Ograniczenia interfejsów API określają, które pakiety SDK i interfejsy API można wywoływać za pomocą klucza interfejsu API. Konsola i gcloud CLI wymagają co najmniej jednego ograniczenia interfejsu API podczas tworzenia klucza.
• Ograniczenia aplikacji określają, które witryny, adresy IP lub aplikacje mogą korzystać z klucza interfejsu API.

Więcej informacji o stosowaniu ograniczeń znajdziesz w artykule o ograniczaniu kluczy interfejsu API.

Tworzenie tokena OAuth

Places API (New) obsługuje uwierzytelnianie OAuth 2.0. Google obsługuje typowe scenariusze OAuth 2.0, takie jak scenariusze dotyczące serwera WWW.

W tym dokumencie opisujemy, jak przekazać token OAuth do wywołania interfejsu Places API (nowego) w środowisku programistycznym. Więcej informacji o używaniu protokołu OAuth w środowisku produkcyjnym znajdziesz w artykule o metodach uwierzytelniania w Google.

Interfejsy API Map Google możesz wywoływać bezpośrednio, wysyłając żądania do interfejsu API do serwera, lub możesz używać bibliotek klienta, aby uprościć kod. Mapy Google udostępniają biblioteki klienta dla języków Go, Java, Node.js i Python. Więcej informacji znajdziesz w artykule o bibliotekach klienta Places API (New).

Omówienie protokołu OAuth

Tokeny dostępu możesz tworzyć i zarządzać nimi za pomocą protokołu OAuth na kilka sposobów, w zależności od środowiska wdrażania.

Możesz używać protokołu OAuth 2.0 do interakcji między serwerami aplikacji i usługi Google. W tym scenariuszu używasz konta usługi powiązanego z aplikacją, a nie z konkretnym użytkownikiem. Możesz wysyłać żądania do interfejsu API za pomocą konta usługi bez bezpośredniego angażowania użytkowników. Więcej informacji o metodach uwierzytelniania znajdziesz w artykule o metodach uwierzytelniania w Google.

Możesz też zintegrować Places API (New) z aplikacją mobilną na Androida lub iOS. Więcej informacji o używaniu protokołu OAuth i zarządzaniu tokenami dostępu w różnych środowiskach wdrażania znajdziesz w artykule Używanie OAuth 2.0 do korzystania z interfejsów API Google.

zakresów protokołu OAuth

Aby używać protokołu OAuth z Places API (New), musisz przypisać tokenowi OAuth ten zakres:

https://www.googleapis.com/auth/cloud-platform

Przykład: wypróbuj wywołania interfejsu API REST w lokalnym środowisku programistycznym

Jeśli nie masz środowiska, które generuje tokeny, i chcesz wypróbować Places API (New) z tokenem OAuth, wykonaj procedurę opisaną w tej sekcji.

Ten przykład pokazuje, jak użyć tokena OAuth dostarczonego przez domyślne uwierzytelnianie aplikacji (ADC) do wykonania wywołania. Więcej informacji o używaniu ADC do wywoływania interfejsów API Google za pomocą bibliotek klienta znajdziesz w artykule na temat uwierzytelniania za pomocą bibliotek klienta.

Poniższej procedury REST używaj tylko do celów programistycznych lub testowych, a nie produkcyjnych.

Wymagania wstępne

Zanim wyślesz żądanie REST za pomocą domyślnych danych uwierzytelniających aplikacji, użyj interfejsu wiersza poleceń gcloud, aby przekazać dane uwierzytelniające do domyślnych danych uwierzytelniających aplikacji:

1. Zainstaluj i zainicjuj interfejs wiersza poleceń gcloud. Więcej informacji znajdziesz w artykule o instalowaniu gcloud CLI.

2. Uwierzytelnij się za pomocą interfejsu wiersza poleceń gcloud:

   gcloud auth application-default login

3. Dokończ proces logowania, aby zapisać dane logowania w lokalnym pliku danych logowania używanym przez ADC.

Więcej informacji znajdziesz w artykule o konfigurowaniu ADC w lokalnym środowisku programistycznym.

Wysyłanie żądania REST

W tym przykładzie przekazujesz 2 nagłówki żądania:

• Przekaż token OAuth w nagłówku Authorization, używając tego polecenia do wygenerowania tokena:

  gcloud auth application-default print-access-token

  Zwrócony token ma zakres https://www.googleapis.com/auth/cloud-platform.

• W nagłówku X-Goog-User-Project podaj identyfikator lub nazwę projektu Google Cloud, który ma włączone rozliczenia.

Aby wywołać Places API (New) za pomocą tokena OAuth, wykonaj te czynności:

1. W tym przykładowym kodzie zastąp PROJECT_ID identyfikatorem swojego projektu Google Cloud:

   curl -X POST -d '{
   "textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
   }' \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
   -H "X-Goog-User-Project: PROJECT_ID" \
   -H "X-Goog-FieldMask: places.displayName,places.formattedAddress" \
   "https://places.googleapis.com/v1/places:searchText"

2. Aby skopiować polecenie curl, kliknij Kopiuj w przykładowym kodzie.

3. Wklej polecenie w oknie terminala, a następnie je uruchom.

Odpowiedzią jest obiekt JSON:

{
  "places": [
    {
      "name": "places/ChIJs5ydyTiuEmsR0fRSlU0C7k0",
      "id": "ChIJs5ydyTiuEmsR0fRSlU0C7k0",
      "types": [
        "vegan_restaurant",
        "vegetarian_restaurant",
        "meal_takeaway",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "nationalPhoneNumber": "0433 479 794",
      "internationalPhoneNumber": "[phone]",
      "formattedAddress": "29 King St, Sydney NSW 2000, Australia",
      "addressComponents": [
        {
          "longText": "29",
          "shortText": "29",
          "types": [
            "street_number"
          ],
          "languageCode": "en-US"
        },
  ...
}

Rozwiązywanie problemów

Jeśli żądanie zwróci komunikat o błędzie informujący, że ten interfejs API nie obsługuje danych logowania użytkownika, zapoznaj się z artykułem Rozwiązywanie problemów z konfiguracją ADC.

Co dalej?

Teraz, gdy masz już włączony interfejs Places API (nowy) i skonfigurowany klucz interfejsu API, zapoznaj się z artykułem Informacje o interfejsie Places API (nowym), aby dowiedzieć się więcej o korzystaniu z tego interfejsu.