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

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

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

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

• Возможность навигации по Google Cloud Console.

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

• Как создать проект 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. Затем включите биллинг в Cloud Console, чтобы использовать ресурсы Google Cloud.

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

Настройте Cloud Shell

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

Чтобы активировать Cloud Shell из Cloud Console:

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

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

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

2. Создайте список проверенных учетных записей:

gcloud auth list

Вы должны увидеть этот вывод:

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

Примечание. Инструмент gcloud CLI предустановлен в 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

Вы можете выбрать множество различных зон. Дополнительные сведения см. в разделе Регионы и зоны .

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

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

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

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

Включить API

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

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

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

4. Нажмите ПОПРОБУЙТЕ ЭТОТ API .

Если кнопка ПОПРОБУЙТЕ ЭТОТ API не отображается, щелкните один из перечисленных методов, чтобы попробовать этот метод.

Создать ключ API

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

1. В Cloud Console выберите Меню навигации > API и службы > Учетные данные .

2. Нажмите CREATE CREDENTIALS и затем выберите ключ 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. Подробную информацию о параметрах можно найти в методе: document.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 также приведены в методе: document.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 из проекта.