Запуск обработки событий из облачного хранилища с помощью функций Eventarc и Cloud Run

1. Обзор

В этой лабораторной работе вы узнаете, как использовать события в хранилище Cloud Storage и Eventarc для запуска обработки событий. Вы будете использовать функции Cloud Run для анализа данных и обработки изображений. Функция будет использовать Google Vision API и сохранять полученное изображение обратно в хранилище Cloud Storage.

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

Как построить конвейер обработки изображений.

• Настройка сегментов хранилища
• Создайте функции Cloud Run для чтения и записи объектов в Cloud Storage.
• Разверните триггер Eventarc.
• Интегрируйте Vision API для распознавания изображений продуктов питания.
• Протестируйте и подтвердите работоспособность комплексного решения.

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

• Для выполнения этой лабораторной работы предполагается знакомство с Cloud Console и командной оболочкой.
• Опыт работы с облачными хранилищами, функциями Cloud Run или Vision API будет полезен, но не обязателен.

2. Настройка и требования

Настройка облачного проекта

1. Войдите в консоль Google Cloud и создайте новый проект или используйте существующий. Если у вас еще нет учетной записи Gmail или Google Workspace, вам необходимо ее создать .

• Название проекта — это отображаемое имя участников данного проекта. Это строка символов, не используемая API Google. Вы всегда можете его изменить.
• Идентификатор проекта уникален для всех проектов Google Cloud и является неизменяемым (его нельзя изменить после установки). Консоль Cloud автоматически генерирует уникальную строку; обычно вам неважно, какая она. В большинстве практических заданий вам потребуется указать идентификатор вашего проекта (обычно обозначается как PROJECT_ID ). Если сгенерированный идентификатор вас не устраивает, вы можете сгенерировать другой случайный идентификатор. В качестве альтернативы вы можете попробовать свой собственный и посмотреть, доступен ли он. После этого шага его нельзя изменить, и он сохраняется на протяжении всего проекта.
• К вашему сведению, существует третье значение — номер проекта , которое используется некоторыми API. Подробнее обо всех трех значениях можно узнать в документации .

Внимание: Идентификатор проекта является уникальным во всем мире и не может быть использован кем-либо еще после того, как вы его выбрали. Вы являетесь единственным пользователем этого идентификатора. Даже если проект будет удален, идентификатор нельзя будет использовать снова.

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

2. Далее вам потребуется включить оплату в консоли Cloud для использования ресурсов/API Cloud. Выполнение этого практического задания не потребует больших затрат, если вообще потребует. Чтобы отключить ресурсы и избежать дополнительных расходов после завершения этого урока, вы можете удалить созданные ресурсы или удалить проект. Новые пользователи Google Cloud имеют право на бесплатную пробную версию стоимостью 300 долларов США .

Активировать Cloud Shell

Активируйте Cloud Shell, нажав на значок справа от строки поиска.

Настройка среды

1. Создайте переменные среды для проекта и ресурсов, выполнив приведенные ниже команды в терминале Cloud Shell.

export PROJECT_ID=$(gcloud config get-value project)
export PROJECT_NAME=$(gcloud config get-value project)
export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format='value(projectNumber)')
export REGION=us-east1 
export UPLOAD_BUCKET_NAME=menu-item-uploads-$PROJECT_ID
export UPLOAD_BUCKET=gs://menu-item-uploads-$PROJECT_ID
export BUCKET_THUMBNAILS=gs://menu-item-thumbnails-$PROJECT_ID
export MENU_SERVICE_NAME=menu-service
export USER_EMAIL=$(gcloud config list account --format "value(core.account)")

2. Включите API, необходимые для работы в лаборатории.

gcloud services enable \
    vision.googleapis.com \
    cloudfunctions.googleapis.com \
    pubsub.googleapis.com \
    cloudbuild.googleapis.com \
    logging.googleapis.com \
    eventarc.googleapis.com \
    artifactregistry.googleapis.com \
    run.googleapis.com \
    --quiet

3. Клонируйте репозиторий

git clone https://github.com/GoogleCloudPlatform/cymbal-eats.git && cd cymbal-eats/cloud-functions

3. Настройка сегментов облачного хранилища.

Создать корзины для хранения

Создавайте сегменты облачного хранилища для загрузки и создания миниатюр изображений для вашего конвейера обработки изображений.

Используйте команду gsutil mb и уникальное имя для создания двух корзин:

1. Корзина для загрузки, куда изображения будут загружаться в первую очередь.
2. Корзина для миниатюр, предназначенная для хранения сгенерированных изображений-миниатюр.

Создайте хранилище для загрузки новых изображений:

gsutil mb -p $PROJECT_ID -l $REGION $UPLOAD_BUCKET

Пример выходных данных:

Creating gs://menu-item-uploads-cymbal-eats-8399-3119/...

Создайте хранилище для сгенерированных эскизов:

gsutil mb -p $PROJECT_ID -l $REGION $BUCKET_THUMBNAILS

Пример выходных данных:

Creating gs://menu-item-thumbnails-cymbal-eats-8399-3119/...

Обновить права доступа к хранилищу.

Обновите права доступа к хранилищу, разрешив пользователям чтение.

Используйте команду gsutil iam ch, чтобы предоставить разрешения на чтение и запись объектов в вашем хранилище:

gsutil iam ch allUsers:objectViewer $UPLOAD_BUCKET
gsutil iam ch allUsers:objectViewer $BUCKET_THUMBNAILS

Внимание: Рекомендуется ограничивать доступ к хранилищам данных. В рамках данной лабораторной работы всем пользователям будет разрешен просмотр всех объектов. Для получения дополнительной информации о защите хранилищ данных ознакомьтесь с разделом «Использование разрешений IAM и лучшие практики для облачного хранилища».

Пример выходных данных

Updated IAM policy for project [cymbal-eats-8399-3119].
[...]

4. Настройка учетных записей служб

Создайте пользовательскую учетную запись службы для Cloud Function, чтобы она обрабатывала эскизы:

export CF_SERVICE_ACCOUNT=thumbnail-service-sa
gcloud iam service-accounts create ${CF_SERVICE_ACCOUNT}

Предоставьте роли artifactregistry.reader разрешение на операции чтения из реестра артефактов:

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member "serviceAccount:${CF_SERVICE_ACCOUNT}@${PROJECT_ID}.iam.gserviceaccount.com" \
  --role "roles/artifactregistry.reader"

Предоставьте роли storage.objectCreator разрешение на сохранение сгенерированных изображений в хранилище миниатюр:

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member "serviceAccount:${CF_SERVICE_ACCOUNT}@${PROJECT_ID}.iam.gserviceaccount.com" \
  --role "roles/storage.objectCreator"

Предоставьте роли run.invoker разрешение на вызов службы Cloud Run:

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member "serviceAccount:${CF_SERVICE_ACCOUNT}@${PROJECT_ID}.iam.gserviceaccount.com" \
  --role "roles/run.invoker"

Предоставьте роли eventarc.eventReceiver разрешение на получение событий от поставщиков:

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member "serviceAccount:${CF_SERVICE_ACCOUNT}@${PROJECT_ID}.iam.gserviceaccount.com" \
  --role "roles/eventarc.eventReceiver"

Предоставьте учетной записи службы Cloud Storage роль pubsub.publisher . Это позволит учетной записи службы публиковать события при загрузке изображений в хранилище.

GCS_SERVICE_ACCOUNT=$(gsutil kms serviceaccount -p $PROJECT_NUMBER)

gcloud projects add-iam-policy-binding $PROJECT_NUMBER \
    --member "serviceAccount:$GCS_SERVICE_ACCOUNT" \
    --role "roles/pubsub.publisher"

5. Обзор функций обработки изображений

Создайте функцию для загрузки изображения из Cloud Storage, изменения его размера и обратной загрузки в Cloud Storage. Функция будет вызывать API Vision для присвоения изображению метки описания. Функция будет проверять метку описания. Если метка идентифицирует изображение как «Еда», будет отправлено событие в службу меню для обновления изображения и миниатюры пункта меню.

Запуск функции

Функции облачного хранилища основаны на уведомлениях Pub/Sub от облачного хранилища и поддерживают аналогичные типы событий:

• завершить
• удалить
• архив
• обновление метаданных

В этой лабораторной работе вы развернете и запустите функцию, когда объект будет окончательно сформирован в облачном хранилище.

Завершение объекта

События завершения записи объекта срабатывают, когда операция «записи» в объект Cloud Storage успешно завершается. В частности, это означает, что создание нового объекта или перезапись существующего объекта запускают это событие. Операции архивирования и обновления метаданных игнорируются этим событием.

6. Интеграция облачного хранилища

Cloud Storage — это сервис для хранения ваших объектов в Google Cloud. Объект — это неизменяемый фрагмент данных, представляющий собой файл любого формата. Вы храните объекты в контейнерах, называемых корзинами (buckets). Все корзины связаны с проектом, и вы можете группировать свои проекты в рамках организации. Клиентские библиотеки и API упрощают интеграцию с Cloud Storage.

В этой лабораторной работе вы будете использовать клиентскую библиотеку для чтения и записи объектов в облачное хранилище.

Установка клиентской библиотеки

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

Использование клиентской библиотеки

Детали реализации во многом зависят от языка программирования. Чтобы использовать клиентскую библиотеку в своем приложении, первым шагом является импорт зависимостей Cloud Storage. Например, в проекте Node.js импорты добавляются в файл package.json. Приведенный ниже фрагмент кода показывает уведомление в файле package.json для этой лабораторной работы.

package.json

{
    "name": "thumbnail-service",
    "version": "0.1.0",
    "dependencies": {
      "@google-cloud/functions-framework": "^3.0.0",
      "@google-cloud/storage": "^5.18.2",
      "@google-cloud/vision": "^2.4.2",
        ...
    }
  }

В файле package.json google-cloud/storage указан как одна из зависимостей приложения.

Зависимость google-cloud/functions-framework используется для регистрации функции обратного вызова CloudEvent в Functions Framework, которая будет запускаться событиями Cloud Storage.

Для вызова API Vision и получения аннотаций к загруженным изображениям, позволяющих определить, являются ли они продуктами питания, будет использоваться зависимость google-cloud/vision.

Зарегистрируйте обратный вызов CloudEvent

Зарегистрируйте функцию обратного вызова CloudEvent в Functions Framework , которая будет запускаться Cloud Storage при загрузке нового изображения в хранилище.

index.js

functions.cloudEvent('process-thumbnails', async (cloudEvent) => {
    console.log(`Event ID: ${cloudEvent.id}`);
    console.log(`Event Type: ${cloudEvent.type}`);
    ...

Создание объекта ссылки на хранилище

После импорта клиентских библиотек вам потребуется создать новый клиент хранилища и корзины, с которыми будет взаимодействовать ваше приложение.

index.js

const storage = new Storage();
const bucket = storage.bucket(file.bucket);
const thumbBucket = storage.bucket(process.env.BUCKET_THUMBNAILS);

Приведённый выше код создаёт клиент хранилища с именем "storage" и две ссылки на сегменты хранилища, которые будут использоваться в качестве ссылок переменными "bucket" и "thumbBucket".

Загрузить объекты облачного хранилища

index.js

await bucket.file(file.name).download({
            destination: originalFile
        });

Используя этот базовый алгоритм загрузки, вы можете возобновить прерванные загрузки, а также применять более сложные стратегии загрузки, такие как загрузка фрагментов данных и потоковая загрузка .

Загрузка объектов в облачное хранилище.

Вы можете отправлять запросы на загрузку в Cloud Storage тремя способами: один запрос, возобновляемая загрузка или многокомпонентная загрузка через XML API. Для больших файлов или потоковой загрузки используйте возобновляемую загрузку. При использовании XML API файлы загружаются по частям и собираются в один объект. Для небольших объектов используйте один запрос на загрузку.

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

index.js

const thumbnailImage = await thumbBucket.upload(thumbFile);

7. Интеграция Vision API

Cloud Vision позволяет разработчикам легко интегрировать функции распознавания изображений в приложения, включая маркировку изображений, распознавание лиц и ориентиров, оптическое распознавание символов (OCR) и разметку контента откровенного характера.

Установка клиентской библиотеки

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

Создать клиент для аннотирования изображений

Для доступа к API Google с помощью официальных клиентских SDK необходимо создать объект сервиса на основе документа обнаружения API, описывающего API для SDK. Вам потребуется получить его из службы обнаружения Vision API, используя свои учетные данные.

index.js

const client = new vision.ImageAnnotatorClient();

По умолчанию клиент будет проходить аутентификацию с использованием файла учетных записей служб, указанного переменной среды GOOGLE_APPLICATION_CREDENTIALS.

Создайте запрос к API Vision.

API Vision может выполнять обнаружение признаков в файле изображения, отправляя содержимое файла изображения в виде строки, закодированной в base64, в теле запроса.

Для создания запроса к ресурсу images с целью аннотирования изображения. Запрос к этому API представляет собой объект со списком запросов. Каждый элемент этого списка содержит два бита информации:

• Данные изображения, закодированные в формате base64.
• Список характеристик, которые вы хотели бы добавить к этому изображению.

index.js

        const client = new vision.ImageAnnotatorClient();
        const visionRequest = {
            image: { source: { imageUri: `gs://${file.bucket}/${file.name}` } },
            features: [
                { type: 'LABEL_DETECTION' },
            ]
        };
        const visionPromise = client.annotateImage(visionRequest);

8. Развертывание функций Cloud Run

Этот сервис изменения размера изображений является частью более крупной системы Cymbal Eats. В этом разделе вы развернете только компоненты, связанные с функцией обработки изображений. Полная установка включает в себя пользовательский интерфейс для загрузки изображения и последующий запрос для сохранения полученных метаданных. Эти возможности не устанавливаются в рамках данной лабораторной работы.

В процессе развертывания функции будут созданы следующие компоненты:

• Функции Cloud Run
• Eventarc trigger
• Тема публикации/подраздела и подписка

В терминале CloudShell выполните следующую команду для развертывания функций Cloud Run с триггером для корзины, указанной в menu-item-uploads-$PROJECT_ID :

Для развертывания функций Cloud Run непосредственно в Cloud Run сначала необходимо развернуть функцию, а затем создать для нее триггер.

Разверните облачные функции запуска:

gcloud beta run deploy process-thumbnails \
      --source=thumbnail \
      --function process-thumbnails \
      --region $REGION \
      --base-image google-22-full/nodejs20 \
      --no-allow-unauthenticated \
      --project=$PROJECT_ID \
--service-account="${CF_SERVICE_ACCOUNT}@${PROJECT_ID}.iam.gserviceaccount.com" \
--set-env-vars=BUCKET_THUMBNAILS=$BUCKET_THUMBNAILS,MENU_SERVICE_URL=$MENU_SERVICE_URL \
  --max-instances=1 \
  --quiet

Пример выходных данных:

Done.                                                                                                                                                                                    
Service [process-thumbnails] revision [process-thumbnails-00001-abc] has been deployed and is serving 100 percent of traffic.
Service URL: https://process-thumbnails-000000000.us-east1.run.app

Создайте триггер:

gcloud eventarc triggers create process-thumbnails-trigger \
     --location=$REGION \
     --destination-run-service=process-thumbnails \
    --destination-run-region=$REGION \
     --event-filters="type=google.cloud.storage.object.v1.finalized" \
     --event-filters="bucket=$UPLOAD_BUCKET_NAME" \
     --service-account="${CF_SERVICE_ACCOUNT}@${PROJECT_ID}.iam.gserviceaccount.com"

Пример выходных данных:

Creating trigger [process-thumbnails-trigger] in project [qwiklabs-gcp-02-53f8532696e1], location [us-east1]...done.                                                                     
WARNING: It may take up to 2 minutes for the new trigger to become active.

Если развертывание триггера не удалось из-за проблемы с правами доступа, пожалуйста, подождите, пока изменения IAM, внесенные на предыдущем шаге, распространятся. Обычно это занимает 1-2 минуты, после чего повторите попытку развертывания.

Пример сообщения об ошибке:

...If you recently started to use Eventarc, it may take a few minutes before all necessary permissions are propagated to the Service Agent...
[...] 

В консоли Cloud проверьте службу Cloud Run , созданную для данной функции:

В консоли Cloud просмотрите триггер Eventarc , созданный для данной функции:

В консоли Cloud просмотрите тему и подписку Pub/Sub, созданные для триггера Eventarc:

9. Протестируйте и подтвердите работоспособность комплексного решения.

Загрузите новую фотографию в облачное хранилище и отслеживайте ход обработки изображений. Вы протестируете комплексное решение, отслеживая журналы облачных функций.

Загрузка изображения

Примечание: Фотография Тома Диллона на Unsplash разрешена для свободного использования в соответствии с лицензией Unsplash.

1. Сохраните это изображение на свой локальный компьютер.
2. Переименуйте файл 1.jpg
3. Откройте консоль облачного хранилища .
4. Нажмите на пункт меню «Загрузки»…
5. Нажмите «Загрузить файлы».
6. Загрузите файл 1.jpg в хранилище.
7. В консоли Cloud перейдите в раздел Cloud Run.
8. Нажмите на «Обработка эскизов».
9. Нажмите на вкладку «ЖУРНАЛЫ» .

Примечание: Функция выполнилась успешно и загрузила изображение в папку с миниатюрами. На основании меток Vision API для загруженного изображения статус пункта меню будет установлен на «Готово». Это означает, что Vision API присвоил изображению аннотацию «Еда».

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

10. Перейдите в меню - пункт - миниатюры - $PROJECT_ID Cloud Storage
11. Убедитесь, что миниатюрное изображение создано в папке с миниатюрами.

Загрузка изображения, не относящегося к продуктам питания.

Для проверки корректной работы функции вам необходимо загрузить изображение, не содержащее объектов, которые могли бы быть отнесены к категории «Еда».

Примечание: Фотография Инсун Юн на Unsplash разрешена для свободного использования в соответствии с лицензией Unsplash.

1. Сохраните это изображение на свой локальный компьютер.
2. Переименуйте файл в 2.jpg.
3. Откройте консоль облачного хранилища .
4. Нажмите на пункт меню «Загрузки»…
5. Нажмите «Загрузить файлы».
6. Загрузите файл 2.jpg в хранилище.
7. В консоли Cloud перейдите в раздел Cloud Run.
8. Нажмите на «Обработка эскизов».
9. Нажмите на вкладку «ЖУРНАЛЫ» .

Примечание: Функция выполнилась успешно и загрузила изображение в папку с миниатюрами. На основании меток Vision API для загруженного изображения статус пункта меню будет установлен на «Неудачно». Это означает, что Vision API не пометил изображение как «Еда».

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

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

Поздравляем, вы завершили лабораторную работу!

Что дальше:

Ознакомьтесь с другими обучающими материалами Cymbal Eats:

• Запуск облачных рабочих процессов с помощью Eventarc
• Подключение к частному серверу CloudSQL из Cloud Run
• Подключение к полностью управляемым базам данных из Cloud Run
• Защита бессерверного приложения с помощью прокси-сервера с поддержкой идентификации (IAP)
• Запуск заданий Cloud Run с помощью Cloud Scheduler
• Безопасное развертывание в облаке
• Обеспечение безопасности входящего трафика облачных сервисов
• Подключение к частной базе данных AlloyDB из GKE Autopilot

Уборка

Чтобы избежать списания средств с вашего аккаунта Google Cloud за ресурсы, используемые в этом руководстве, либо удалите проект, содержащий эти ресурсы, либо сохраните проект и удалите отдельные ресурсы.

Удаление проекта

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