Wywoływanie interfejsów API z projektu Google Cloud

1. Zanim zaczniesz

Dzięki temu ćwiczeniu w Codelabs dowiesz się, jak utworzyć projekt Google Cloud i wywołać interfejsy Google Cloud APIs z tego projektu.

Wymagania wstępne

• Umiejętność poruszania się po konsoli Google Cloud.

Czego się nauczysz

• Jak utworzyć projekt Google Cloud.
• Jak skonfigurować konto rozliczeniowe
• Jak skonfigurować Cloud Shell.
• Jak włączyć interfejs API.
• Jak autoryzować interfejs API za pomocą klucza interfejsu API.
• Jak autoryzować interfejs API za pomocą konta usługi.

Czego potrzebujesz

• Konto Google, na przykład konto Gmail lub konto Google Workspace.
• Dostęp do konta rozliczeniowego Cloud lub karty kredytowej, za pomocą których możesz zarejestrować się w programie bezpłatnego okresu próbnego.

2. Konfiguracja

W tej sekcji dowiesz się, jak utworzyć projekt Google Cloud oraz skonfigurować konto rozliczeniowe i Cloud Shell.

Utwórz projekt Google Cloud i skonfiguruj konto rozliczeniowe

Uwaga: jeśli nie masz jeszcze konta Gmail ani konta Google Workspace, musisz je najpierw utworzyć.

1. Zaloguj się w konsoli Google Cloud i wybierz lub utwórz projekt.

Ostrzeżenie: jeśli użyjesz ponownie projektu i wykonasz to ćwiczenie w programowaniu, możesz zezwolić niektórym użytkownikom na dostęp do zasobów w tym projekcie, o ile nie zostaną wyłączone po zakończeniu tego ćwiczenia.

Zapamiętaj identyfikator projektu, który jest widoczny pod polem Nazwa projektu. Identyfikator jest niepowtarzalną nazwą we wszystkich projektach Google Cloud (powyższa nazwa jest już zajęta), a w dalszej części tego ćwiczenia w Codelabs będzie nazywany PROJECT_ID.

Uwaga: jeśli używasz konta Gmail, jako domyślną lokalizację możesz pozostawić ustawienie Brak organizacji. Jeśli używasz konta Google Workspace, wybierz lokalizację odpowiednią dla Twojej organizacji.

2. Następnie włącz płatności w Cloud Console, aby korzystać z zasobów Google Cloud.

Ćwiczenie z programowania nie powinno kosztować, ale możesz wykonać czynności opisane w sekcji Czyszczenie, aby wyłączyć zasoby i uniknąć kosztów. Pamiętaj, że nowi użytkownicy Google Cloud mogą skorzystać z bezpłatnego okresu próbnego o wartości 300 USD.

Konfigurowanie Cloud Shell

W tym ćwiczeniu w Codelabs wykorzystasz Cloud Shell – środowisko wiersza poleceń działające w Google Cloud. Cloud Shell to oparta na Debianie maszyna wirtualna, która oferuje wszystkie potrzebne narzędzia dla programistów. Zawiera stały katalog domowy o pojemności 5 GB, który znacznie zwiększa wydajność sieci i uwierzytelnianie. Oznacza to, że do tego ćwiczenia z programowania potrzebujesz jedynie przeglądarki.

Aby aktywować Cloud Shell z poziomu konsoli Cloud:

1. Kliknij Aktywuj Cloud Shell.

Uzyskanie dostępu do środowiska i połączenie się z nim może zająć kilka chwil.

Po nawiązaniu połączenia z Cloud Shell powinno pojawić się potwierdzenie, że użytkownik jest już uwierzytelniony, a projekt jest już ustawiony na PROJECT_ID.

2. Wygeneruj listę kont z dostępem do danych:

gcloud auth list

Powinny się wyświetlić te dane wyjściowe:

Credentialed accounts:
 - <MY_ACCOUNT>@<MY_DOMAIN>.com (active)

Uwaga: narzędzie wiersza poleceń gcloud jest wstępnie zainstalowane w Cloud Shell i pomaga tworzyć zasoby Google Cloud oraz nimi zarządzać. Więcej informacji znajdziesz w artykule Omówienie narzędzia gcloud.

3. Aby wyświetlić listę projektów, wpisz to polecenie.

gcloud config list project

Powinny się wyświetlić te dane wyjściowe:

[core]
project = <PROJECT_ID>

Jeśli z jakiegoś powodu projekt nie jest skonfigurowany, uruchom to polecenie, aby go skonfigurować.

gcloud config set project <PROJECT_ID>

PROJECT_ID to identyfikator użyty podczas konfiguracji. Możesz je też wyszukać w panelu Cloud Console:

Cloud Shell ustawia też domyślnie niektóre zmienne środowiskowe, które może być przydatne podczas uruchamiania przyszłych poleceń.

4. Aby zobaczyć identyfikator projektu, wpisz następujące polecenie.

echo $GOOGLE_CLOUD_PROJECT

Powinny się wyświetlić te dane wyjściowe:

<PROJECT_ID>

5. Na koniec ustaw domyślną strefę i konfigurację projektu.

gcloud config set compute/zone us-central1-f

Możesz wybrać różne strefy. Więcej informacji znajdziesz w artykule Regiony i strefy.

Uwaga: gdy uruchomisz na komputerze narzędzie interfejsu wiersza poleceń gcloud, ustawienia konfiguracji będą zachowywane między sesjami. Musisz jednak skonfigurować te ustawienia w Cloud Shell dla każdej nowej sesji lub połączenia.

3. Wywoływanie interfejsu API z projektu

Dzięki temu ćwiczeniu w Codelabs dowiesz się, jak używać przykładowego interfejsu API (Natural Language API) do znajdowania elementów (takich jak osoby, miejsca i wydarzenia) w tekście oraz jak określać nastawienie (poziom pozytywnego nastawienia) do tego tekstu. Dowiesz się, jak:

• Włącz interfejsy Google Cloud APIs.
• Uzyskaj autoryzację interfejsu API za pomocą kluczy interfejsu API i kont usługi.
• Wywołaj interfejs API za pomocą biblioteki curl i bibliotek klienta.

Włączanie API

1. Wybierz Interfejsy API i Usług w menu głównym konsoli Cloud.

2. U góry ekranu kliknij + WŁĄCZ INTERFEJSY API I USŁUGI.

3. W tym momencie możesz filtrować i przeglądać interfejsy API lub przejść bezpośrednio do interfejsu API za pomocą pola wyszukiwania. Wyszukaj Natural Language i wybierz Cloud Natural Language API.

4. Kliknij WYPRÓBUJ TEN INTERFEJS API.

Jeśli przycisk WYPRÓBUJ TEN interfejs API nie jest widoczny, kliknij jedną z wymienionych metod, aby wypróbować tę metodę.

Tworzenie klucza interfejsu API

Ponieważ używasz curl do wysyłania żądań do interfejsu Natural Language API, musisz wygenerować klucz interfejsu API, aby przekazać URL żądania.

1. W konsoli Cloud wybierz Menu nawigacyjne > Interfejsy API Usługi > Dane logowania.

2. Kliknij UTWÓRZ DANE LOGOWANIA i wybierz Klucz interfejsu API:

3. Skopiuj wygenerowany klucz interfejsu API i kliknij Zamknij.

Wywoływanie interfejsu API przy użyciu klucza interfejsu API

1. W wierszu poleceń Cloud Shell wyeksportuj klucz interfejsu API.

export API_KEY=<YOUR_API_KEY>

Zastąp <YOUR_API_KEY> kluczem wygenerowanym wcześniej.

2. Utwórz żądanie do interfejsu API w edytorze Cloud Shell lub w edytorze systemu Linux, takim jak Vim lub Emacs. Szczegółowe informacje o parametrach znajdziesz w sekcji Metoda: document.analyzeEntities. Zapisz dane wyjściowe w pliku o nazwie request.json:

{
  "document":{
    "type":"PLAIN_TEXT",
    "content":"Google, headquartered in Mountain View (1600 Amphitheatre Pkwy, Mountain View, CA 940430), unveiled the new Android phone for $799 at the Consumer Electronic Show. Sundar Pichai said in his keynote that users love their new Android phones."
  },
  "encodingType":"UTF8"
}

3. Wywołaj interfejs API i podaj informacje o żądaniu.

curl "https://language.googleapis.com/v1/documents:analyzeEntities?key=${API_KEY}" \
  -s -X POST -H "Content-Type: application/json" --data-binary @request.json

4. Uruchom polecenie jeszcze raz, przekieruj dane wyjściowe do pliku i sprawdź wynik. Szczegóły danych wyjściowych pliku JSON znajdziesz też w sekcji Metoda: document.analyzeEntities.
5. Aby zmienić tekst do analizy w pliku request.json, zastąp wartość content wybranym przez siebie tekstem.

4. Autoryzuj za pomocą konta usługi

Konta usługi są często preferowane przed kluczami interfejsu API, ponieważ zapewniają zarówno uwierzytelnianie, jak i autoryzację. Można je traktować jak adresy e-mail aplikacji.

1. Wróć do sekcji Dane logowania na stronie Interfejsy API i Menu Usługi.
2. Wybierz Create Credentials (Utwórz dane logowania), ale tym razem wybierz Service Account (Konto usługi).

3. Podaj nazwę konta usługi opisującą jego przeznaczenie, np. „Natural Language Service Account”. System zasugeruje identyfikator. Możesz też dodać opis. W miarę jak dowiadujesz się więcej o kontach usługi, przyznasz kontu usługi dostęp do projektów, a użytkownikom – przyznasz dostęp do niego. Na razie po prostu kliknij Gotowe, aby utworzyć konto usługi.
4. Jeśli chcesz utworzyć parę kluczy, której chcesz używać dla konta usługi, kliknij , co pozwoli Ci edytować konto usługi.

Pojawią się szczegóły Twojego konta usługi.

5. Skopiuj adres e-mail konta usługi i wróć do Cloud Shell.
6. W Cloud Shell utwórz parę kluczy konta usługi i ustaw zmienną środowiskową wskazującą ją:

gcloud iam service-accounts keys create ~/key.json \
  --iam-account <your service account email>
export GOOGLE_APPLICATION_CREDENTIALS="/home/$USER/key.json"

Google Cloud używa tej zmiennej środowiskowej do znajdowania danych logowania, więc nie trzeba ich uwzględniać w wywołaniu interfejsu API.

7. Możesz teraz wywołać interfejs API za pomocą polecenia:

gcloud ml language analyze-entities --content="Michelangelo Caravaggio, Italian painter, is known for 'The Calling of Saint Matthew'." 

Wynik powinien być taki sam jak wcześniej.

Wiele interfejsów API ma obszerne biblioteki klienta, z których można wyodrębnić te szczegóły. Więcej informacji o bibliotekach klienta znajdziesz w artykule Biblioteki klienta Cloud. Możesz też zapoznać się z dokumentacją używanych interfejsów API, aby dowiedzieć się, jakie biblioteki klienta są dla nich dostępne.

5. Czyszczenie danych

Stosowanie klucza interfejsu API bez ograniczeń jest niewskazane na potrzeby projektów. Jeśli ktoś uzyska do niego dostęp, będzie mógł z niego korzystać bez konieczności uwierzytelniania.

Aby usunąć ten klucz interfejsu API:

1. Kliknij Menu nawigacyjne > Interfejsy API Usługi > Dane logowania.
2. W sekcji API Keys (Klucze interfejsu API) wybierz klucz, który chcesz usunąć, a następnie kliknij Usuń.
3. Zamiast obawiać się, że Twój klucz prywatny konta usługi nie będzie chroniony, w sekcji Konta usługi wybierz konto usługi, które chcesz usunąć, i kliknij Usuń.

6. Gratulacje

Gratulacje! Wiesz już, jak utworzyć projekt Google Cloud i jak wywołać interfejs API z poziomu projektu.