Actions API は、アクションの作成、管理、テストに役立つエンドポイントを提供します。
クライアント ライブラリ（Node.js）
サーバーに直接 HTTP リクエストを行うことによって Actions API RESTful サービスを使用することはできますが、Node.js からエンドポイントに簡単にアクセスできるクライアント ライブラリを提供しています。Actions API クライアント ライブラリを使用すると、さまざまなエンドポイントを使用してアクションを管理、テストできます。
たとえば、以下のコードは writePreview エンドポイントを呼び出して、提供されたモデルに基づいてユーザーのプロジェクト プレビューを更新します。
import {ActionsSdkClient} from '@assistant/actions';
import { promisify } from 'util';
import * as stream from 'stream';
const PROJECT_ID = '<PROJECT_ID>';
const VERSION = 123;
const projectPath = `projects/${PROJECT_ID}`;
const versionPath = `projects/${PROJECT_ID}/versions/${VERSION}`;
async function publishPreview(projectPath, versionPath) {
const request = {
parent: projectPath,
previewSettings: {sandbox: {value: true}},
submittedVersion: {version: versionPath}
};
const client = new ActionsSdkClient();
const stream = client.writePreview(()=>{});
stream.write(request);
stream.end();
const finished = promisify(stream.finished);
await finished(stream);
}
Actions API Node.js クライアント ライブラリのインストール手順とリファレンス資料については、ライブラリと Actions API REST リファレンスのドキュメントをご覧ください。
要件
Actions API に送信されるリクエストには、次の要件が適用されます。
リクエストのペイロード サイズ
Actions API に送信するリクエストは 10 MB 以下にする必要があります。これには、クライアント ストリーミング エンドポイントが含まれます。ストリーム内の各リクエストは 10 MB 以下にする必要があります。
ペイロードが 10 MB を超えると、Actions SDK サーバーから 400 エラーが返されます。
ベスト プラクティス
Actions API を使用する場合は、次のベスト プラクティスを強くおすすめします。
x-goog-user-project リクエスト ヘッダーを設定する
ユーザー向けにツールやアプリケーションを作成する場合、クライアント プロジェクトではなく、ユーザーのプロジェクトに対して課金を行い、割り当ての上限を設定することが必要な場合があります。課金と割り当ての目的のプロジェクトを指定するには、x-goog-user-project リクエスト ヘッダーを設定します。
| 有効な値 | 既存の Google Cloud プロジェクトのプロジェクト ID |
| 例 | x-goog-user-project: my-project |
| 詳細 | ヘッダーで指定されたプロジェクトは割り当て上限に使用され、リクエストに関連する料金が発生します。 |
ユーザー エージェント リクエスト ヘッダーを設定する
user-agent リクエスト ヘッダーを使用して、適切なユーザー エージェントを設定します。これにより、API がパートナーからのリクエストであるかどうかを判断できます。
既知の制限事項
このセクションでは、Actions API の既知の制限事項について説明します。
クライアント ストリーミング エンドポイントのタイムアウト
この制限は、クライアント ストリーミング エンドポイントに送信する HTTP リクエストにのみ適用されます。クライアント ライブラリを使用したリクエストは、この制限の影響を受けません。
HTTP リクエストを使用して WritePreview、CreateVersion、または WriteDraft を呼び出す場合は、失敗したリクエストを処理するためにタイムアウトを実装することをおすすめします。
200 以外のステータス コードを示すレスポンス ヘッダーを受信した場合、コードは一定時間後にストリームを終了する必要があります。この問題は、クライアント ストリーミング エンドポイントにのみ影響します。たとえば、Actions API を使用する gactions ツールには 5 秒のタイムアウトがあります。