Вызов API из проекта Google Cloud

1. Прежде чем начать

В этом практическом занятии показано, как создать проект Google Cloud, а затем вызывать API Google Cloud из этого проекта.

Предварительные требования

• Умение ориентироваться в консоли Google Cloud.

Что вы узнаете

• Как создать проект в Google Cloud.
• Как настроить платежный аккаунт.
• Как настроить Cloud Shell.
• Как включить API.
• Как авторизовать API с помощью ключа API.
• Как авторизовать API с помощью сервисного аккаунта.

Что вам понадобится

• Учетная запись Google, например, учетная запись Gmail или учетная запись Google Workspace .
• Для участия в программе бесплатного пробного периода вам потребуется учетная запись Cloud Billing или кредитная карта.

2. Настройка

В этом разделе показано, как создать проект Google Cloud, настроить платежный аккаунт и настроить Cloud Shell.

Создайте проект в Google Cloud и настройте учетную запись для выставления счетов.

Примечание: Если у вас еще нет учетной записи Gmail или Google Workspace , вам необходимо сначала их создать.

1. Войдите в Cloud Console и выберите или создайте проект.

Внимание: если вы используете один и тот же проект и выполняете это практическое задание, вы можете разрешить некоторым пользователям доступ к ресурсам этого проекта, если они не будут отключены после завершения работы.

Запомните идентификатор проекта, который отображается в поле « Название проекта» . Идентификатор — это уникальное имя для всех проектов Google Cloud (указанное выше имя уже занято), и далее в этом практическом задании он будет обозначаться как PROJECT_ID .

Примечание: Если вы используете учетную запись Gmail, вы можете оставить значение по умолчанию « Без организации» . Если вы используете учетную запись Google Workspace, выберите местоположение, которое подходит для вашей организации.

2. Далее, чтобы использовать ресурсы Google Cloud, включите оплату в Cloud Console.

Хотя выполнение этого практического задания не должно стоить дорого, следуйте инструкциям в разделе «Очистка ресурсов», чтобы отключить ресурсы и избежать дополнительных расходов после завершения задания. Обратите внимание, что новые пользователи Google Cloud имеют право на бесплатную пробную версию стоимостью 300 долларов США .

Настройте Cloud Shell

В этом практическом занятии вы будете использовать Cloud Shell — среду командной строки, работающую в Google Cloud. Cloud Shell — это виртуальная машина на базе Debian, оснащенная всеми необходимыми инструментами разработки. Она предоставляет постоянный домашний каталог размером 5 ГБ, что значительно повышает производительность сети и аутентификацию. Это означает, что для этого практического занятия вам понадобится только браузер.

Для активации Cloud Shell из облачной консоли:

1. Нажмите Активируйте Cloud Shell .

Подготовка и подключение к среде может занять несколько минут.

После подключения к Cloud Shell вы увидите, что ваша аутентификация пройдена и проект уже настроен на ваш PROJECT_ID .

2. Сгенерируйте список учетных записей, имеющих учетные данные:

gcloud auth list

Вы должны увидеть следующий результат:

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

Примечание: Инструмент командной строки gcloud предустановлен в Cloud Shell и помогает создавать и управлять ресурсами Google Cloud. Для получения дополнительной информации см. обзор инструмента gcloud .

3. Чтобы просмотреть список ваших проектов, введите эту команду.

gcloud config list project

Вы должны увидеть следующий результат:

[core]
project = <PROJECT_ID>

Если по какой-либо причине проект не создан, выполните эту команду, чтобы создать проект.

gcloud config set project <PROJECT_ID>

PROJECT_ID — это идентификатор, который вы использовали на этапах настройки. Вы также можете найти его на панели управления Cloud Console:

Cloud Shell также по умолчанию устанавливает некоторые переменные среды, что может быть полезно при выполнении будущих команд.

4. Чтобы увидеть идентификатор вашего проекта, введите следующую команду.

echo $GOOGLE_CLOUD_PROJECT

Вы должны увидеть следующий результат:

<PROJECT_ID>

5. Наконец, установите зону по умолчанию и конфигурацию проекта.

gcloud config set compute/zone us-central1-f

Вы можете выбрать различные зоны. Для получения дополнительной информации см. раздел «Регионы и зоны» .

Примечание: При запуске инструмента командной строки gcloud на вашем компьютере параметры конфигурации сохраняются между сессиями. Однако в Cloud Shell вам необходимо настраивать эти параметры для каждой новой сессии или повторного подключения.

3. Вызов API из проекта

В этом практическом занятии вы узнаете, как использовать пример API ( Patient Language API ) для поиска объектов (таких как люди, места и события) в тексте и как приблизительно оценить эмоциональную окраску (уровень одобрения) этого текста. Вы научитесь:

• Включите API Google Cloud.
• Получите авторизацию для доступа к API с помощью ключей API и учетных записей служб.
• Вызывайте API с помощью curl и клиентских библиотек.

Включить API

1. В главном меню консоли Cloud выберите «API и сервисы» .

2. Выберите пункт «+ ВКЛЮЧИТЬ API И СЕРВИСЫ» в верхней части экрана.

3. На этом этапе вы можете фильтровать и просматривать API или перейти непосредственно к нужному API с помощью поля поиска . Найдите Natural Language и выберите «Cloud Natural Language API» .

4. Нажмите «ПОПРОБОВАТЬ ЭТОТ API» .

Если кнопка «ПОПРОБОВАТЬ ЭТОТ API» не отображается, нажмите на один из перечисленных методов, чтобы попробовать его.

Создайте ключ API

Поскольку для отправки запроса к API обработки естественного языка используется curl , необходимо сгенерировать ключ API, который будет передаваться в URL-адресе запроса.

1. В консоли Cloud выберите меню «Навигация» > «API и сервисы» > «Учетные данные» .

2. Нажмите «СОЗДАТЬ УЧЕТНЫЕ ДАННЫЕ» , а затем выберите ключ API :

3. Скопируйте сгенерированный ключ API и нажмите «Закрыть» .

Используйте ключ API для вызова API.

1. В командной строке Cloud Shell экспортируйте свой API-ключ.

export API_KEY=<YOUR_API_KEY>

Замените <YOUR_API_KEY> на ключ, который вы сгенерировали ранее.

2. Создайте запрос к API в редакторе Cloud Shell или в редакторе Linux, например Vim или Emacs. Подробную информацию о параметрах можно найти в методе: documents.analyzeEntities . Сохраните результат в файл с именем 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. Вызовите API, указав информацию из запроса.

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

4. Повторно запустите команду, перенаправьте вывод в файл и изучите результат. Подробная информация о выводе в JSON-файле также содержится в методе: documents.analyzeEntities .
5. Чтобы изменить текст для анализа в файле request.json , замените значение content на текст по вашему выбору.

4. Авторизация с использованием служебного аккаунта.

Сервисные учетные записи часто предпочтительнее ключей API, поскольку они обеспечивают как аутентификацию, так и авторизацию. Сервисные учетные записи можно рассматривать как адреса электронной почты для вашего приложения.

1. Вернитесь в раздел «Учетные данные» меню «API и сервисы» .
2. Выберите «Создать учетные данные» , но на этот раз выберите «Учетная запись службы» .

3. Укажите имя учетной записи службы , описывающее ее назначение, например, « Natural Language Service Account ». Система предложит идентификатор. Вы также можете добавить описание. По мере изучения учетных записей служб вы будете предоставлять этой учетной записи доступ к проектам и разрешать пользователям доступ к ней, но пока просто нажмите «Готово» , чтобы создать учетную запись службы.
4. Чтобы создать пару ключей для использования учетной записью службы, нажмите здесь. для редактирования учетной записи службы.

Отображаются подробные сведения о вашем сервисном аккаунте.

5. Скопируйте адрес электронной почты учетной записи службы и вернитесь в Cloud Shell.
6. В Cloud Shell создайте пару ключей для вашей учетной записи службы и установите переменную среды, указывающую на нее:

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

Google Cloud использует эту переменную среды для поиска учетных данных, поэтому их не нужно включать в вызов API.

7. Теперь вы можете вызвать API с помощью команды:

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

Результат должен быть таким же, как и раньше.

Многие API имеют обширные клиентские библиотеки для извлечения этих данных. Подробнее о клиентских библиотеках см. в разделе «Облачные клиентские библиотеки» . Вы также можете ознакомиться с документацией к используемым вами API, чтобы узнать, какие клиентские библиотеки для них доступны.

5. Уборка

Использование неограниченного API-ключа для проектов — плохая практика . Если кто-то получит к нему доступ, он сможет использовать его без дополнительной аутентификации.

Чтобы удалить этот ключ API:

1. Нажмите Меню навигации > API и сервисы > Учетные данные .
2. В разделе «Ключи API» выберите ключ для удаления, а затем нажмите кнопку. Удалить .
3. Аналогично, вместо того чтобы беспокоиться о незащищенности закрытого ключа вашей служебной учетной записи, в разделе «Служебные учетные записи » выберите служебную учетную запись для удаления, а затем нажмите кнопку. Удалить .

6. Поздравляем!

Поздравляем! Вы научились создавать проекты в Google Cloud и вызывать API из этих проектов.