Node.js Cloud クライアント ライブラリを使う

※この投稿は米国時間 2022 年 6 月 22 日に、Google Cloud blog に投稿されたものの抄訳です。

Google Cloud は、グローバルな規模でミッション クリティカルなサーバーレス アプリを実行できるだけでなく、アプリに価値ある機能を追加する多種多様なプロダクトを提供しています。Node.js Cloud クライアント ライブラリを使用することで、アプリケーション プログラミング インターフェース（API）からプロダクトにアクセスするために記述しなくてはならない JavaScript や TypeScript のコードを減らしたり簡易化したりできます。

問題

Google Cloud API を使用する Node.js サービスを作成する必要があります。

解決方法

100 を超える Node.js Cloud クライアント ライブラリのリストから適切なライブラリを使用して、特定の API に接続します。

説明

Google Cloud クライアント ライブラリ チームは、以下を実現するために Node.js のライブラリを作成しています。

• 下位レベル通信に関する詳細を効率的に処理する（API リクエストの認証など）

• 「ベスト プラクティス」に基づいた汎用的で一貫性のある JavaScript と TypeScript のプログラミング体験を提供する

開始方法

いずれかの Node.js Cloud クライアント ライブラリを使用することで、わずか数行のコードで Cloud API にアクセスできます。各 Cloud API のライブラリは、同じ初期化パターンに従います。

1. 使用する Cloud API を探す

最初に Node.js Cloud クライアント ライブラリのリファレンス ページで任意の API のライブラリを探します。

このデモでは、Cloud Translation ライブラリを使用します。[ライブラリ] テーブルのリンク、または左側のサイドバーのリンク（「translate」）をクリックすると、各リファレンス ページに移動します。

2. 「始める前に」セクションの最初の 3 つの手順を踏む

各ライブラリのリファレンス ページには始める前にというセクションがあります。最初の 3 つの手順は次のとおりです。

1. Cloud Platform プロジェクトを選択または作成する。

2. プロジェクトに対して課金を有効にする（Google の無料枠の詳細をご確認ください）。

3. Cloud Translation API を有効にする。

手順 4 は省略します。この記事では、ローカルテストは扱いません。

3. Cloud Build と Cloud Run API を有効にする

次の API を有効にして、アプリのコンテナ イメージを構築および保存できるようにしてから、Cloud Run でアプリコンテナを実行します。

1. Cloud Build API

2. Artifact Registry API

3. Cloud Run Admin API

4. 任意の API クライアント ライブラリをインストールする

ライブラリ リファレンス ページでは、インストールの必要なライブラリを見つけることができます。Translate クライアントの場合は次を入力します。

npm install @google-cloud/translate

5. クライアント ライブラリをコードに追加する

const {Translate} = require('@google-cloud/translate').v2;

または、TypeScript（もしくは最新の JavaScript モジュールのサポート）の import 構文を使用します。

import {v2} from '@google-cloud/translate';

const {Translate} = v2;

6. クライアント ライブラリを使用する

前の手順 2.1 で作成した Google Cloud プロジェクトのプロジェクト ID が必要です。もう一度探す必要がある場合は、Cloud プロジェクトのダッシュボードに移動します。

API クライアント インスタンスを作成します。

const projectId = 'tpujals-node-client-demo';

const client = new Translate({projectId});

これで、クライアントでメソッドを呼び出せるようになりました。Translate クライアントの場合、translate メソッドはいくつかあります。以下は、試し用のとても単純な translate メソッドです。

const text = 'Hello, world!';

const targetLanguage = 'ja';

console.log(`${text} => ${translation}`);

リファレンス ドキュメントにあるように、translate メソッドは Promise を返して（すべてのクライアントのメソッドで同じ）、結果を非同期で取得します。

この例では、確認する結果はタプルの最初の要素です（翻訳された文字列）。Promise が完了したら、分割代入構文を使用して翻訳変数を設定します。

ここでエラーの可能性がいくつか生じます（接続できない、認証の失敗、不正な引数を渡すなど）。本番環境のコードの場合は、呼び出しを適切な try-catch ステートメントでラップします。

デモを起動する（Cloud Run にデプロイされている Node.js + Express + Angular アプリ）

前のセクションの開始手順を実行したら、あとはデモの起動です。このデモ用 GitHub リポジトリは、Translation API 用に Node.js クライアント ライブラリを使用するアプリの構築方法を示しています。

アプリ バックエンド（src/server の下）は Node.js サーバーで Express フレームワークを使用します。フロントエンド（src/client の下）は Angular クライアントです。

アプリケーションの大半は標準のボイラープレートです。理解すべき重要な点は次のとおりです。

• Express サーバーは、翻訳リクエストを行うユーザー インターフェースと API（/api/translate）にサービスを提供します。API リクエストを処理するボイラープレート以外の翻訳コードは、開始方法セクションに示したものと基本的に同じです。

• フロントエンドは Angular サービス（translate.service.ts）を実行します。ユーザー インターフェースがこのサービスを使用してバックエンドと通信し、翻訳をリクエストします。フロントエンドは、バックエンド サーバーの public ディレクトリから静的なシングルページ アプリケーション（SPA）として提供されます。location.origin を使って翻訳をリクエストするための実際の URL を作成している点に注目してください。これにより、ローカルホストと Cloud Run のどちらからサービスを提供されてもアプリが動作するようになっています。

フロントエンドから投稿された引数は翻訳用のテキストとターゲット（言語コード）です。レスポンスのステータスに応じて、レスポンス データには翻訳またはエラー メッセージが含まれます。

デモリポジトリのクローンを作成する

ターミナルでデモリポジトリのクローンを作成して、ディレクトリをそのクローンに変更します。

git clone https://github.com/subfuzion/demo-nodejs-cloud-client.git

cd demo-nodejs-cloud-client

Angular クライアントを構築する

クライアント UI を変更する場合は、次のコマンドを入力するだけです。それ以外の場合は、この手順を省略できます。

./scripts/ng-build

サービスを Cloud Run にデプロイする

プロジェクト ID、リージョン、使用するサービス名が必要です。たとえば、us-central1 の demo-project にデプロイして translate-demo という Cloud Run サービスを作成するには、ターミナルに次のコマンドを入力します。

export PROJECT=demo-project

export REGION=us-central1

export SERVICE=translate-demo

./scripts/run-deploy

以下のプロンプトが表示され、アプリイメージを保存する Artifact Registry を作成するよう求められます。

Deploying from source requires an Artifact Registry Docker repository to store built containers. A repository named [cloud-run-source-deploy] in region 

[us-central1] will be created.

Do you want to continue (Y/n)?

続行するには「Y」と入力します（または Enter キーを押します）。

次のように出力されます。

Building using Dockerfile and deploying container to Cloud Run service [translate-demo] in project [demo-project] region [us-central1]

✓ Building and deploying new service... Done. 

✓ Uploading sources... 

✓ Building Container...

Logs are available at 

[https://console.cloud.google.com/cloud-build/builds/f9eeb697-...?project=...].

✓ Creating Revision...

✓ Routing traffic...

✓ Setting IAM Policy... Done.

Service [translate-demo] revision [translate-demo-00001-pid] has been deployed and is serving 100 percent of traffic. 

Service URL: https://translate-demo-ao23awv5ca-uc.a.run.app

Service URL には実行中のアプリへのリンクが含まれています。ここで、アプリが正常に動作していることを確認できます。

Google Cloud API にアクセスする他の方法

他の方法もあります。ただし、Google Cloud API へのアクセスでは、Node.js Cloud クライアント ライブラリの適切なライブラリを使用することが推奨されます。Google Cloud の専任チームがこれらのライブラリの最適化、テスト、維持に対応しています。

これらのライブラリは gRPC を使用して Google Cloud API にアクセスするため、通信が効率的に行われ、認証と通信詳細が簡素化されます。ほとんどの Cloud API は、gRPC インターフェースを介した場合、スループットと CPU 使用率の面でパフォーマンスが大幅に向上します。gRPC を使用して API にアクセスすると、標準的な REST API と比較して CPU あたりのスループットが 10 倍増大します。Node.js Cloud クライアント ライブラリの使用は、このようなパフォーマンス向上を実現する最も簡単な方法です。

Google API Node.js クライアント

サポートされている Cloud クライアント ライブラリとして提供されていない API（マップや YouTube など）にアクセスする必要がある場合は、代わりに Google API Node.js クライアントを使用できることがあります。これは古いクライアント（ただし、まだ積極的に維持されています）で、Google API エンドポイント仕様から自動生成されます（Google APIs Explorer を参照）。

ただし、Google API の Node.js クライアントでサポートされているのは REST インターフェースによる通信のみで、gRPC インターフェースによる通信はサポートされないことにご注意ください。また、REST インターフェース コードは自動生成されるため、一般的にこのクライアントとの連携は、専用に手作業で作成された Cloud クライアント ライブラリほどの直感性と汎用性がありません。

Cloud API に直接アクセスする

HTTP コード上に独自の JSON を記述して、別の Cloud API が公開している REST インターフェースにアクセスできます。gRPC が有効な Cloud API では、API のプロトコル バッファ サービス定義を使用して独自の gRPC クライアントを生成できます（GitHub リポジトリを参照）。

ただし、Cloud API は TLS 暗号化を使用したセキュアなリクエストのみを受け入れるため、Google との認証と Cloud クライアント ライブラリでは自動で処理される多くの下位レベルの通信詳細の処理に、ご自身で対応する必要があります。関連する詳細事項については、HTTP ガイドラインと gRPC 認証をご覧ください。

まとめ

Node.js Cloud クライアント ライブラリはパフォーマンス向上を目的に作られ、基本的な下位レベルのプロトコル、認証、信頼性、エラー処理管理を簡素化します。

リンク

Node.js Cloud クライアント ライブラリ

Google Cloud のサンプルのブラウザ

デモのソースコード