Pic-a-daily: ラボ 1 - 画像を保存、分析する

1. 概要

最初のコードラボでは、バケットに画像をアップロードします。これにより、関数によって処理されるファイル作成イベントが生成されます。この関数は Vision API を呼び出して画像分析を行い、結果をデータストアに保存します。

学習内容

Cloud Storage
Cloud Functions
Cloud Vision API
Cloud Firestore

2. 設定と要件

セルフペース型の環境設定

Google Cloud Console にログインして、プロジェクトを新規作成するか、既存のプロジェクトを再利用します。Gmail アカウントも Google Workspace アカウントもまだお持ちでない場合は、アカウントを作成してください。

プロジェクト名は、このプロジェクトの参加者に表示される名称です。Google API では使用されない文字列です。この設定はいつでも変更できます。
プロジェクト ID は、すべての Google Cloud プロジェクトにおいて一意でなければならず、不変です（設定後は変更できません）。Cloud コンソールでは一意の文字列が自動生成されます。通常は、この内容を意識する必要はありません。ほとんどの Codelab では、プロジェクト ID（通常は PROJECT_ID と識別されます）を参照する必要があります。生成された ID が好みではない場合は、ランダムに別の ID を生成できます。または、ご自身で試して、利用可能かどうかを確認することもできます。このステップ以降は変更できず、プロジェクトを通して同じ ID になります。
なお、3 つ目の値として、一部の API が使用するプロジェクト番号があります。これら 3 つの値について詳しくは、こちらのドキュメントをご覧ください。

次に、Cloud のリソースや API を使用するために、Cloud コンソールで課金を有効にする必要があります。この Codelab の操作をすべて行って、費用が生じたとしても、少額です。このチュートリアルの終了後に請求が発生しないようにリソースをシャットダウンするには、作成したリソースを削除するか、プロジェクト全体を削除します。Google Cloud の新規ユーザーは、300 米ドル分の無料トライアルプログラムをご利用いただけます。

Cloud Shell の起動

Google Cloud はノートパソコンからリモートで操作できますが、この Codelab では、Google Cloud Shell（Cloud 上で動作するコマンドライン環境）を使用します。

Google Cloud Console で、右上のツールバーにある Cloud Shell アイコンをクリックします。

プロビジョニングと環境への接続にはそれほど時間はかかりません。完了すると、次のように表示されます。

この仮想マシンには、必要な開発ツールがすべて用意されています。永続的なホームディレクトリが 5 GB 用意されており、Google Cloud で稼働します。そのため、ネットワークのパフォーマンスと認証機能が大幅に向上しています。この Codelab での作業はすべて、ブラウザ内から実行できます。インストールは不要です。

3. API を有効にする

このラボでは、Cloud Functions と Vision API を使用しますが、まず Cloud Console または gcloud で有効にする必要があります。

Cloud Console で Vision API を有効にするには、検索バーで Cloud Vision API を検索します。

Cloud Vision API のページが表示されます。

[ENABLE] ボタンをクリックします。

または、gcloud コマンドラインツールを使用して Cloud Shell で有効にすることもできます。

Cloud Shell で、次のコマンドを実行します。

gcloud services enable vision.googleapis.com

オペレーションが正常に完了したことを確認します。

Operation "operations/acf.12dba18b-106f-4fd2-942d-fea80ecc5c1c" finished successfully.

Cloud Functions も有効にします。

gcloud services enable cloudfunctions.googleapis.com

4. バケットを作成する（コンソール）

写真用のストレージバケットを作成します。この操作は、Google Cloud Platform コンソール（console.cloud.google.com）または Cloud Shell やローカル開発環境の gsutil コマンドラインツールを使用して行うことができます。

[ストレージ] に移動

ハンバーガーメニュー（☰）から Storage ページに移動します。

バケットに名前を付ける

[CREATE BUCKET] ボタンをクリックします。

[CONTINUE] をクリックします。

場所を選択

任意のリージョン（ここでは Europe）にマルチリージョンバケットを作成します。

[CONTINUE] をクリックします。

デフォルトのストレージクラスを選択する

データの Standard ストレージクラスを選択します。

[CONTINUE] をクリックします。

アクセス制御を設定する

一般公開されている画像を扱うため、このバケットに保存されているすべての画像に同じ均一なアクセス制御を設定します。

Uniform アクセス制御オプションを選択します。

[CONTINUE] をクリックします。

Set Protection/Encryption

独自の暗号鍵を使用しないため、デフォルト（Google-managed key)）のままにします。

CREATE をクリックして、バケットの作成を完了します。

allUsers をストレージビューアとして追加

[Permissions] タブに移動します。

次のように、Storage > Storage Object Viewer ロールを持つ allUsers メンバーをバケットに追加します。

[SAVE] をクリックします。

5. バケットを作成する（gsutil）

Cloud Shell で gsutil コマンドラインツールを使用してバケットを作成することもできます。

Cloud Shell で、一意のバケット名の変数を設定します。Cloud Shell では、GOOGLE_CLOUD_PROJECT が一意のプロジェクト ID に設定されています。これをバケット名の末尾に追加できます。

次に例を示します。

export BUCKET_PICTURES=uploaded-pictures-${GOOGLE_CLOUD_PROJECT}

ヨーロッパに標準のマルチリージョンゾーンを作成します。

gsutil mb -l EU gs://${BUCKET_PICTURES}

均一なバケットレベルのアクセスを確保します。

gsutil uniformbucketlevelaccess set on gs://${BUCKET_PICTURES}

バケットを公開します。

gsutil iam ch allUsers:objectViewer gs://${BUCKET_PICTURES}

コンソールの Cloud Storage セクションに移動すると、公開 uploaded-pictures バケットが表示されます。

前の手順で説明したように、バケットに写真をアップロードでき、アップロードした写真が一般公開されていることをテストします。

6. バケットへの公開アクセスをテストする

ストレージブラウザに戻ると、バケットがリストに表示され、アクセス権が [公開] になっています（バケットのコンテンツに誰でもアクセスできることを示す警告アイコンも表示されます）。

これで、バケットで写真を受け取れるようになりました。

バケット名をクリックすると、バケットの詳細が表示されます。

ここで、Upload files ボタンを試して、バケットに写真を追加できることをテストします。ファイル選択ポップアップが表示され、ファイルの選択を求められます。選択すると、バケットにアップロードされ、この新しいファイルに自動的に割り当てられた public アクセス権が再び表示されます。

Public アクセスラベルの横に、小さなリンクアイコンも表示されます。クリックすると、ブラウザはその画像の公開 URL に移動します。この URL の形式は次のようになります。

https://storage.googleapis.com/BUCKET_NAME/PICTURE_FILE.png

BUCKET_NAME は、バケットに選択したグローバルに一意の名前と、写真のファイル名です。

画像名の横にあるチェックボックスをオンにすると、DELETE ボタンが有効になり、最初の画像を削除できます。

7. 関数を作成する

このステップでは、写真のアップロードイベントに応答する関数を作成します。

Google Cloud コンソールの Cloud Functions セクションに移動します。このページにアクセスすると、Cloud Functions サービスが自動的に有効になります。

Create function をクリックします。

名前を選択します（例: picture-uploaded）とリージョン（バケットのリージョン選択と一致させる必要があります）。

関数には次の 2 種類があります。

URL（ウェブ API など）で呼び出すことができる HTTP 関数。
イベントによってトリガーできるバックグラウンド関数。

Cloud Storage バケットに新しいファイルがアップロードされたときにトリガーされるバックグラウンド関数を作成します。

バケットでファイルが作成または更新されたときにトリガーされるイベントである Finalize/Create イベントタイプに関心があります。

前に作成したバケットを選択して、この特定のバケットでファイルが作成または更新されたときに通知されるように Cloud Functions に指示します。

Select をクリックして、前に作成したバケットを選択し、Save をクリックします。

[次へ] をクリックする前に、[ランタイム、ビルド、接続、セキュリティの設定] でデフォルト（256 MB のメモリ）を開いて変更し、1 GB に更新できます。

Next をクリックすると、ランタイム、ソースコード、エントリポイントを調整できます。

この関数の Inline editor を保持します。

次のいずれかの Node.js ランタイムを選択します。

ソースコードは、index.js JavaScript ファイルと、さまざまなメタデータと依存関係を提供する package.json ファイルで構成されています。

デフォルトのコードスニペットはそのままにします。アップロードされた写真のファイル名がログに記録されます。

ここでは、テスト用に実行する関数の名前を helloGCS にします。

Deploy をクリックして関数を作成し、デプロイします。デプロイが成功すると、関数のリストに緑色の丸で囲まれたチェックマークが表示されます。

8. 関数をテストする

このステップでは、関数がストレージイベントに応答することを確認します。

ハンバーガー（☰）メニューから Storage ページに戻ります。

画像バケットをクリックし、Upload files をクリックして画像をアップロードします。

Cloud コンソール内で再度移動して、Logging > Logs Explorer ページに移動します。

Log Fields セレクタで Cloud Function を選択して、関数専用のログを表示します。[ログフィールド] を下にスクロールすると、特定の関数を選択して、関数に関連するログの詳細なビューを表示することもできます。picture-uploaded 関数を選択します。

関数の作成、関数の開始時間と終了時間、実際のログステートメントに関するログ項目が表示されます。

ログステートメントは Processing file: pic-a-daily-architecture-events.png となっています。これは、この写真の作成と保存に関連するイベントが想定どおりにトリガーされたことを意味します。

9. データベースを準備する

Vision API から提供された画像に関する情報は、高速、フルマネージド、サーバーレス、クラウドネイティブの NoSQL ドキュメントデータベースである Cloud Firestore データベースに保存します。Cloud Console の Firestore セクションに移動して、データベースを準備します。

Native mode または Datastore mode の 2 つのオプションがあります。ネイティブモードを使用します。ネイティブモードでは、オフラインサポートやリアルタイム同期などの追加機能を利用できます。

SELECT NATIVE MODE をクリックします。

マルチリージョンを選択します（ここではヨーロッパですが、理想的には関数とストレージバケットと同じリージョンを少なくとも選択します）。

[CREATE DATABASE] ボタンをクリックします。

データベースが作成されると、次のようになります。

+ START COLLECTION ボタンをクリックして、新しいコレクションを作成します。

名前のコレクション pictures。

ドキュメントを作成する必要はありません。新しい写真が Cloud Storage に保存され、Vision API によって分析されると、それらの写真がプログラムで追加されます。

[Save] をクリックします。

Firestore は、新しく作成されたコレクションに最初のデフォルトドキュメントを作成します。このドキュメントには有用な情報は含まれていないため、安全に削除できます。

コレクションにプログラムで作成されるドキュメントには、次の 4 つのフィールドが含まれます。

name（文字列）: アップロードされた写真のファイル名。ドキュメントのキーでもあります。
labels（文字列の配列）: Vision API によって認識されたアイテムのラベル
color（文字列）: ドミナントカラーの 16 進数カラーコード（例: #ab12ef)
created（日付）: この画像のメタデータが保存されたときのタイムスタンプ
thumbnail（ブール値）: この写真のサムネイル画像が生成された場合に存在し、true になる省略可能なフィールド

Firestore で検索してサムネイルが利用可能な写真を見つけ、作成日で並べ替えるため、検索インデックスを作成する必要があります。

Cloud Shell で次のコマンドを使用してインデックスを作成できます。

gcloud firestore indexes composite create \
  --collection-group=pictures \
  --field-config field-path=thumbnail,order=descending \
  --field-config field-path=created,order=descending

または、Cloud コンソールで、左側のナビゲーション列の Indexes をクリックし、次のように複合インデックスを作成することもできます。

Create をクリックします。インデックスの作成には数分かかることがあります。

10. 関数を更新する

Functions ページに戻り、Vision API を呼び出して写真を分析し、メタデータを Firestore に保存するように関数を更新します。

ハンバーガーメニュー（☰）から Cloud Functions セクションに移動し、関数名をクリックして Source タブを選択し、EDIT ボタンをクリックします。

まず、Node.JS 関数の依存関係が列挙されている package.json ファイルを編集します。Cloud Vision API NPM 依存関係を追加するようにコードを更新します。

{
  "name": "picture-analysis-function",
  "version": "0.0.1",
  "dependencies": {
    "@google-cloud/storage": "^1.6.0",
    "@google-cloud/vision": "^1.8.0",
    "@google-cloud/firestore": "^3.4.1"
  }
}

依存関係が最新の状態になったので、index.js ファイルを更新して、関数のコードを操作します。

index.js 内のコードを次のコードで置き換えます。これについては次のステップで説明します。

const vision = require('@google-cloud/vision');
const Storage = require('@google-cloud/storage');
const Firestore = require('@google-cloud/firestore');

const client = new vision.ImageAnnotatorClient();

exports.vision_analysis = async (event, context) => {
    console.log(`Event: ${JSON.stringify(event)}`);

    const filename = event.name;
    const filebucket = event.bucket;

    console.log(`New picture uploaded ${filename} in ${filebucket}`);

    const request = {
        image: { source: { imageUri: `gs://${filebucket}/${filename}` } },
        features: [
            { type: 'LABEL_DETECTION' },
            { type: 'IMAGE_PROPERTIES' },
            { type: 'SAFE_SEARCH_DETECTION' }
        ]
    };

    // invoking the Vision API
    const [response] = await client.annotateImage(request);
    console.log(`Raw vision output for: ${filename}: ${JSON.stringify(response)}`);

    if (response.error === null) {
        // listing the labels found in the picture
        const labels = response.labelAnnotations
            .sort((ann1, ann2) => ann2.score - ann1.score)
            .map(ann => ann.description)
        console.log(`Labels: ${labels.join(', ')}`);

        // retrieving the dominant color of the picture
        const color = response.imagePropertiesAnnotation.dominantColors.colors
            .sort((c1, c2) => c2.score - c1.score)[0].color;
        const colorHex = decColorToHex(color.red, color.green, color.blue);
        console.log(`Colors: ${colorHex}`);

        // determining if the picture is safe to show
        const safeSearch = response.safeSearchAnnotation;
        const isSafe = ["adult", "spoof", "medical", "violence", "racy"].every(k => 
            !['LIKELY', 'VERY_LIKELY'].includes(safeSearch[k]));
        console.log(`Safe? ${isSafe}`);

        // if the picture is safe to display, store it in Firestore
        if (isSafe) {
            const pictureStore = new Firestore().collection('pictures');
            
            const doc = pictureStore.doc(filename);
            await doc.set({
                labels: labels,
                color: colorHex,
                created: Firestore.Timestamp.now()
            }, {merge: true});

            console.log("Stored metadata in Firestore");
        }
    } else {
        throw new Error(`Vision API error: code ${response.error.code}, message: "${response.error.message}"`);
    }
};

function decColorToHex(r, g, b) {
    return '#' + Number(r).toString(16).padStart(2, '0') + 
                 Number(g).toString(16).padStart(2, '0') + 
                 Number(b).toString(16).padStart(2, '0');
}

11. 関数を調べる

それでは、さまざまな興味深い部分を詳しく見ていきましょう。

まず、Vision、Storage、Firestore に必要なモジュールを require します。

const vision = require('@google-cloud/vision');
const Storage = require('@google-cloud/storage');
const Firestore = require('@google-cloud/firestore');

次に、Vision API のクライアントを準備します。

const client = new vision.ImageAnnotatorClient();

次に、関数の構造を示します。Node.js 8 で導入された async / await 機能を使用しているため、非同期関数にします。

exports.vision_analysis = async (event, context) => {
    ...
    const filename = event.name;
    const filebucket = event.bucket;
    ...
}

シグネチャだけでなく、Cloud Functions をトリガーしたファイルとバケットの名前を取得する方法にも注目してください。

参考までに、イベントペイロードの例を以下に示します。

{
  "bucket":"uploaded-pictures",
  "contentType":"image/png",
  "crc32c":"efhgyA==",
  "etag":"CKqB956MmucCEAE=",
  "generation":"1579795336773802",
  "id":"uploaded-pictures/Screenshot.png/1579795336773802",
  "kind":"storage#object",
  "md5Hash":"PN8Hukfrt6C7IyhZ8d3gfQ==",
  "mediaLink":"https://www.googleapis.com/download/storage/v1/b/uploaded-pictures/o/Screenshot.png?generation=1579795336773802&alt=media",
  "metageneration":"1",
  "name":"Screenshot.png",
  "selfLink":"https://www.googleapis.com/storage/v1/b/uploaded-pictures/o/Screenshot.png",
  "size":"173557",
  "storageClass":"STANDARD",
  "timeCreated":"2020-01-23T16:02:16.773Z",
  "timeStorageClassUpdated":"2020-01-23T16:02:16.773Z",
  "updated":"2020-01-23T16:02:16.773Z"
}

Vision クライアント経由で送信するリクエストを準備します。

const request = {
    image: { source: { imageUri: `gs://${filebucket}/${filename}` } },
    features: [
        { type: 'LABEL_DETECTION' },
        { type: 'IMAGE_PROPERTIES' },
        { type: 'SAFE_SEARCH_DETECTION' }
    ]
};

Vision API の 3 つの主要な機能をリクエストしています。

ラベル検出: 写真の内容を理解する
画像プロパティ: 画像の興味深い属性（画像のドミナントカラー）を取得します。
セーフサーチ: 画像を表示しても安全かどうかを判断します（アダルトコンテンツ、医療コンテンツ、わいせつなコンテンツ、暴力的なコンテンツが含まれていないかどうかを判断します）。

この時点で、Vision API を呼び出すことができます。

const [response] = await client.annotateImage(request);

参考までに、Vision API からのレスポンスは次のようになります。

{
  "faceAnnotations": [],
  "landmarkAnnotations": [],
  "logoAnnotations": [],
  "labelAnnotations": [
    {
      "locations": [],
      "properties": [],
      "mid": "/m/01yrx",
      "locale": "",
      "description": "Cat",
      "score": 0.9959855675697327,
      "confidence": 0,
      "topicality": 0.9959855675697327,
      "boundingPoly": null
    },
    ✄ - - - ✄
  ],
  "textAnnotations": [],
  "localizedObjectAnnotations": [],
  "safeSearchAnnotation": {
    "adult": "VERY_UNLIKELY",
    "spoof": "UNLIKELY",
    "medical": "VERY_UNLIKELY",
    "violence": "VERY_UNLIKELY",
    "racy": "VERY_UNLIKELY",
    "adultConfidence": 0,
    "spoofConfidence": 0,
    "medicalConfidence": 0,
    "violenceConfidence": 0,
    "racyConfidence": 0,
    "nsfwConfidence": 0
  },
  "imagePropertiesAnnotation": {
    "dominantColors": {
      "colors": [
        {
          "color": {
            "red": 203,
            "green": 201,
            "blue": 201,
            "alpha": null
          },
          "score": 0.4175916016101837,
          "pixelFraction": 0.44456374645233154
        },
        ✄ - - - ✄
      ]
    }
  },
  "error": null,
  "cropHintsAnnotation": {
    "cropHints": [
      {
        "boundingPoly": {
          "vertices": [
            { "x": 0, "y": 118 },
            { "x": 1177, "y": 118 },
            { "x": 1177, "y": 783 },
            { "x": 0, "y": 783 }
          ],
          "normalizedVertices": []
        },
        "confidence": 0.41695669293403625,
        "importanceFraction": 1
      }
    ]
  },
  "fullTextAnnotation": null,
  "webDetection": null,
  "productSearchResults": null,
  "context": null
}

エラーが返されなかった場合は、次に進むことができます。そのため、次のような if ブロックがあります。

if (response.error === null) {
    ...
} else {
    throw new Error(`Vision API error: code ${response.error.code},  
                     message: "${response.error.message}"`);
}

写真で認識されたもの、カテゴリ、テーマのラベルを取得します。

const labels = response.labelAnnotations
    .sort((ann1, ann2) => ann2.score - ann1.score)
    .map(ann => ann.description)

ラベルはスコアの高い順に並べ替えます。

写真のドミナントカラーを知りたいとします。

const color = response.imagePropertiesAnnotation.dominantColors.colors
    .sort((c1, c2) => c2.score - c1.score)[0].color;
const colorHex = decColorToHex(color.red, color.green, color.blue);

ここでも、スコアで色を並べ替えて、最初の色を取得しています。

また、ユーティリティ関数を使用して、赤 / 緑 / 青の値を CSS スタイルシートで使用できる 16 進数のカラーコードに変換しています。

写真を表示しても安全かどうかを確認しましょう。

const safeSearch = response.safeSearchAnnotation;
const isSafe = ["adult", "spoof", "medical", "violence", "racy"]
    .every(k => !['LIKELY', 'VERY_LIKELY'].includes(safeSearch[k]));

アダルト / スプーフィング / 医療 / 暴力 / 際どいコンテンツの属性をチェックし、可能性が低いか可能性が非常に低いかを確認します。

セーフサーチの結果が問題なければ、メタデータを Firestore に保存できます。

if (isSafe) {
    const pictureStore = new Firestore().collection('pictures');
            
    const doc = pictureStore.doc(filename);
    await doc.set({
        labels: labels,
        color: colorHex,
        created: Firestore.Timestamp.now()
    }, {merge: true});
}

12. 関数をデプロイする

関数をデプロイします。

DEPLOY ボタンを押すと、新しいバージョンがデプロイされます。進行状況は次のとおりです。

13. 関数を再度テストする

関数が正常にデプロイされたら、Cloud Storage に写真を投稿し、関数が呼び出されたかどうか、Vision API が何を返すか、メタデータが Firestore に保存されているかどうかを確認します。

Cloud Storage に戻り、ラボの開始時に作成したバケットをクリックします。

バケットの詳細ページで、Upload files ボタンをクリックして写真をアップロードします。

ハンバーガー（☰）メニューから、Logging > Logs エクスプローラに移動します。

ログのリストを見ると、関数が呼び出されたことがわかります。

ログには、関数実行の開始と終了が示されます。その間には、console.log() ステートメントで関数に配置したログが表示されます。次のような出力が表示されます。

関数をトリガーするイベントの詳細。
Vision API 呼び出しの未加工の結果。
アップロードした写真で見つかったラベル、
ドミナントカラーの情報、
写真を表示しても安全かどうか、
最終的に、写真に関するメタデータは Firestore に保存されます。

もう一度ハンバーガーメニュー（☰）から Firestore セクションに移動します。Data サブセクション（デフォルトで表示）に、新しく追加されたドキュメントを含む pictures コレクションが表示されます。これは、先ほどアップロードした写真に対応しています。

14. クリーンアップ（省略可）

シリーズの他のラボを続行する予定がない場合は、リソースをクリーンアップして費用を節約し、クラウドのマナーを守りましょう。リソースを個別にクリーンアップするには、次の操作を行います。

バケットを削除します。

gsutil rb gs://${BUCKET_PICTURES}

関数を削除します。

gcloud functions delete picture-uploaded --region europe-west1 -q

コレクションから [コレクションを削除] を選択して、Firestore コレクションを削除します。

または、プロジェクト全体を削除することもできます。

gcloud projects delete ${GOOGLE_CLOUD_PROJECT}

15. 完了

おめでとうございます！プロジェクトの最初の主要なサービスを実装できました。

学習した内容

Cloud Storage
Cloud Functions
Cloud Vision API
Cloud Firestore

次のステップ

Pic-a-daily: ラボ 2 - 大きな写真のサムネイルを作成する

Pic-a-daily: ラボ 1 - 画像を保存、分析する

1. 概要

学習内容

2. 設定と要件

セルフペース型の環境設定

Cloud Shell の起動

3. API を有効にする

4. バケットを作成する（コンソール）

[ストレージ] に移動

バケットに名前を付ける

場所を選択

デフォルトのストレージ クラスを選択する

アクセス制御を設定する

Set Protection/Encryption

allUsers をストレージ ビューアとして追加

5. バケットを作成する（gsutil）

6. バケットへの公開アクセスをテストする

7. 関数を作成する

8. 関数をテストする

9. データベースを準備する

10. 関数を更新する

11. 関数を調べる

12. 関数をデプロイする

13. 関数を再度テストする

14. クリーンアップ（省略可）

15. 完了

学習した内容

次のステップ

デフォルトのストレージクラスを選択する

allUsers をストレージビューアとして追加