Wywoływanie interfejsów API z projektu Google Cloud

1. Zanim zaczniesz

Z tego laboratorium dowiesz się, jak utworzyć projekt Google Cloud, a następnie wywoływać z niego interfejsy API Google Cloud.

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, np. konto Gmail lub konto Google Workspace;
• Dostęp do konta rozliczeniowego Cloud lub karty kredytowej, której można użyć do zarejestrowania się w programie bezpłatnej wersji próbnej.

2. Konfiguracja

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

Tworzenie projektu Google Cloud i konfigurowanie konta rozliczeniowego

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

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

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

Zapamiętaj identyfikator projektu, który jest widoczny pod polem Nazwa projektu. Identyfikator to unikalna nazwa we wszystkich projektach Google Cloud (podana wyżej nazwa jest już zajęta). W dalszej części tego samouczka będzie on oznaczany jako PROJECT_ID.

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

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

Ten przewodnik nie powinien kosztować wiele, ale jeśli chcesz uniknąć opłat po jego ukończeniu, wykonaj instrukcje z sekcji Czyszczenie, aby zamknąć zasoby. Pamiętaj, że nowi użytkownicy Google Cloud mogą skorzystać z bezpłatnego okresu próbnego, w którym mają do dyspozycji środki w wysokości 300 USD.

Konfigurowanie Cloud Shell

W tym module użyjesz Cloud Shell, czyli środowiska wiersza poleceń działającego w Google Cloud. Cloud Shell to oparta na Debianie maszyna wirtualna zawierająca wszystkie potrzebne narzędzia dla programistów. Zawiera również stały katalog domowy o pojemności 5 GB, co znacznie zwiększa wydajność sieci i usprawnia proces uwierzytelniania. Oznacza to, że do ukończenia tego ćwiczenia potrzebujesz tylko przeglądarki.

Aby aktywować Cloud Shell w konsoli Cloud:

1. Kliknij  Aktywuj Cloud Shell.

Udostępnienie środowiska i połączenie się z nim może chwilę potrwać.

Po połączeniu z Cloud Shell zobaczysz, że uwierzytelnianie zostało już przeprowadzone, a projekt jest już ustawiony na Twój identyfikator PROJECT_ID.

2. Wygeneruj listę kont z danymi logowania:

gcloud auth list

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

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

Uwaga: narzędzie CLI gcloud jest wstępnie zainstalowane w Cloud Shell i pomaga tworzyć zasoby Google Cloud oraz nimi zarządzać. Więcej informacji znajdziesz w omówieniu 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 ustawiony, uruchom to polecenie, aby go skonfigurować.

gcloud config set project <PROJECT_ID>

PROJECT_ID to identyfikator użyty w krokach konfiguracji. Możesz też sprawdzić go w panelu konsoli Google Cloud:

Cloud Shell domyślnie ustawia też niektóre zmienne środowiskowe, które mogą być przydatne podczas wykonywania kolejnych poleceń.

4. Aby wyświetlić identyfikator projektu, wpisz to 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 uruchamiasz narzędzie CLI gcloud na swoim komputerze, ustawienia konfiguracji są zachowywane między sesjami. W Cloud Shell musisz jednak konfigurować te ustawienia dla każdej nowej sesji lub połączenia.

3. Wywoływanie interfejsu API z projektu

W tym module dowiesz się, jak za pomocą przykładowego interfejsu API (Natural Language API) wyszukiwać w tekście encje (np. osoby, miejsca i wydarzenia) oraz określać nastawienie (poziom przychylności) tego tekstu. Dowiesz się, jak:

• Włącz interfejsy Google Cloud API.
• Uzyskaj autoryzację dostępu do interfejsu API za pomocą kluczy interfejsu API i kont usługi.
• Wywołuj interfejs API za pomocą curl i bibliotek klienta.

Włączanie API

1. W menu głównym w konsoli Cloud wybierz Interfejsy API i usługi.

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 wybranego interfejsu API, korzystając z pola Wyszukaj. Wyszukaj Natural Language i wybierz Cloud Natural Language API.

4. Kliknij WYPRÓBUJ TEN INTERFEJS API.

Jeśli nie widzisz przycisku WYPRÓBUJ TEN INTERFEJS API, kliknij jedną z metod na liście, aby ją wypróbować.

Tworzenie klucza interfejsu API

Ponieważ w celu wysłania żądania do interfejsu Natural Language API będziesz korzystać z narzędzia curl, musisz wygenerować klucz interfejsu API, aby przekazać go w URL żądania.

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

2. Kliknij UTWÓRZ DANE LOGOWANIA, a potem wybierz Klucz interfejsu API:

3. Skopiuj wygenerowany klucz interfejsu API, a potem kliknij Zamknij.

Używanie klucza interfejsu API do wywoływania interfejsu API

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

export API_KEY=<YOUR_API_KEY>

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

2. Utwórz żądanie do interfejsu API w edytorze Cloud Shell lub w edytorze systemu Linux, np. Vim lub Emacs. Szczegóły parametrów znajdziesz w metodzie documents.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 z informacjami 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 ponownie polecenie i przekieruj dane wyjściowe do pliku, a następnie sprawdź wynik. Szczegóły dotyczące danych wyjściowych pliku JSON znajdziesz też w sekcji Metoda: documents.analyzeEntities.
5. Aby zmienić tekst do analizy w pliku request.json, zastąp wartość content wybranym tekstem.

4. Autoryzacja za pomocą konta usługi

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

1. Wróć do sekcji Dane logowania w menu Interfejsy API i usługi.
2. Kliknij Utwórz dane logowania, ale tym razem wybierz Konto usługi.

3. Podaj nazwę konta usługi, która opisuje jego przeznaczenie, np. „Natural Language Service Account”. System zaproponuje identyfikator. Możesz też dodać opis. Gdy dowiesz się więcej o kontach usługi, przyznasz im dostęp do projektów i udostępnisz je użytkownikom. Na razie kliknij Gotowe, aby utworzyć konto usługi.
4. Aby utworzyć parę kluczy, której będzie używać konto usługi, kliknij , aby edytować konto usługi.

Wyświetlą się szczegóły konta usługi.

5. Skopiuj adres e-mail konta usługi i wróć do Cloud Shell.
6. W Cloud Shell utwórz parę kluczy dla konta usługi i ustaw zmienną środowiskową, aby wskazywała tę parę:

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. Teraz możesz 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 poprzednio.

Wiele interfejsów API ma rozbudowane 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 sprawdzić, jakie biblioteki klienta są dla nich dostępne.

5. Czyszczenie danych

Nie zalecamy używania w projektach klucza interfejsu API bez ograniczeń. Jeśli ktoś uzyska do niego dostęp, będzie mógł go używać bez konieczności dalszego uwierzytelniania.

Aby usunąć ten klucz interfejsu API:

1. Kliknij  Menu nawigacyjne > Interfejsy API i usługi > Dane logowania.
2. W sekcji Klucze API wybierz klucz do usunięcia, a potem kliknij Usuń.
3. Podobnie, zamiast martwić się o brak ochrony klucza prywatnego konta usługi, w sekcji Konta usługi wybierz konto usługi, które chcesz usunąć, a następnie kliknij Usuń.

6. Gratulacje

Gratulacje! Wiesz już, jak utworzyć projekt Google Cloud i jak wywołać interfejs API w tym projekcie.