Actions API

Actions API는 작업을 빌드, 관리, 테스트하는 데 도움이 되는 엔드포인트를 제공합니다.

클라이언트 라이브러리 (Node.js)

서버에 직접 HTTP 요청을 전송하여 Actions API RESTful 서비스를 사용할 수 있지만, Google에서는 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에 대한 요청은 10MB 이하여야 합니다. 여기에는 클라이언트 스트리밍 엔드포인트가 포함되며, 스트림의 각 요청이 10MB 이하여야 합니다.

페이로드가 10MB를 초과하면 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초입니다.