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

1. Обзор

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

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

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

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

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

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

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

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

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

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

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

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

2. Затем вам необходимо включить выставление счетов в Cloud Console, чтобы использовать облачные ресурсы/API. Прохождение этой кодовой лаборатории не будет стоить много, если вообще что-то стоить. Чтобы отключить ресурсы и избежать выставления счетов за пределами этого руководства, вы можете удалить созданные вами ресурсы или удалить проект. Новые пользователи 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. Настройте сегменты облачного хранилища.

Создание сегментов хранения

Создайте сегменты Cloud Storage для загрузки и эскизов для вашего конвейера обработки изображений.

Используйте команду 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"

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

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. Функция вызовет Vision API, чтобы присвоить изображению метку описания. Функция проверит метку описания. Если метка идентифицирует изображение как «Еда», в службу меню будет отправлено событие для обновления изображения и миниатюры пункта меню.

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

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

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

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

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

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

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

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

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

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

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

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

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

пакет.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.

Зависимость google-cloud/vision будет использоваться для вызова API 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);

Приведенный выше код создает клиент хранилища под названием «хранилище» и две ссылки на сегменты хранилища, на которые будут ссылаться переменные «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.

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

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

Чтобы создать запрос с использованием ресурса изображений для аннотации вашего изображения. Запрос к этому 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. В этом разделе вы развернете только компоненты, связанные с функцией обработки изображений. Полная установка включает в себя пользовательский интерфейс для загрузки изображения и последующий запрос на сохранение полученных метаданных. Эти возможности не устанавливаются в рамках данной лабораторной работы.

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

• Функции облачного запуска
• Триггер Eventarc
• Тема Pub/Sub и подписка

В терминале 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 Run , созданную для этой функции:

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

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

9. Протестируйте и подтвердите комплексное решение

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

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

Примечание. Фото Тома Диллона на Unsplash можно использовать бесплатно по лицензии Unsplash.

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

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

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

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

Загрузка изображения непродовольственной продукции

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

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

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

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

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

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

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

Что дальше:

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

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

Очистить

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

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

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