2023년 6월 13일에 대화형 작업이 종료되기 전에 2023년 5월 3일에 Transactions API가 지원 중단됩니다. 자세한 내용은 대화 작업 지원 중단을 참고하세요.

이 페이지는 Cloud Translation API를 통해 번역되었습니다.

빌드 예약

이 가이드에서는 작업 프로젝트를 개발하는 과정을 안내합니다. 예약하기 위한 API입니다.

거래 흐름

작업 프로젝트가 예약을 처리할 때 다음과 같은 흐름을 사용합니다.

거래 요건 확인 (선택사항) - 거래 내역을 사용합니다. 요구사항 도우미에 추가하여 사용자가 거래를 수행할 수 있습니다.
주문하기 - 사용자에게 '장바구니 조립' 예약의 세부정보를 빌드하는 곳입니다.
주문 제안: '장바구니'에서 완료되면 'order' 예약 제안 ~ 사용자가 맞는지 확인할 수 있습니다. 예약이 확인되면 예약 세부정보가 포함된 응답을 받을 수 있습니다.
주문 완료 및 영수증 보내기 - 주문이 확인되면 영수증을 전송하고 사용자에게 영수증을 전송합니다
주문 업데이트 전송 - 예약의 수명 동안 PATCH 요청을 전송하여 사용자 예약 상태 업데이트를 Orders API를 참조하세요.

제한사항 및 검토 가이드라인

단, Orders API에 액세스할 수 있습니다 작업을 검토하는 데 최대 6주가 걸릴 수 있습니다. 따라서 출시 일정을 계획할 때 이 시간을 고려하세요. 원활한 검토를 위해 거래 정책 및 가이드라인 을 검토하세요.

다음 국가에서만 Orders API를 사용하는 작업을 배포할 수 있습니다.

오스트레일리아
브라질
캐나다
인도네시아

일본
멕시코
카타르
러시아

싱가포르
스위스
태국
터키
영국
미국

프로젝트 빌드

거래 대화의 광범위한 예는 거래 샘플 참고

설정

작업을 만들 때 트랜잭션 수행 여부를 지정해야 합니다. Actions 콘솔을 참조하세요.

프로젝트 및 처리를 설정하려면 다음을 수행합니다.

새 프로젝트를 만들거나 기존 프로젝트를 가져옵니다.
배포 > 디렉터리 정보.
추가 정보 > 거래 > '작업 수행' 체크박스를 선택합니다. Transactions API를 사용하여 실제 상품의 거래를 할 수 있나요?"라는 질문이 포함됩니다.

거래 요건 확인(선택사항)

사용자가 예약을 원한다고 표현하면 바로 예약을 요청할 수 있습니다 예를 들어 작업이 호출되면 다음과 같이 질문합니다. "좌석을 예약하시겠어요?" 사용자가 '예'라고 하면 계속 진행할 수 있는지 확인하고 설정을 수정할 기회를 주세요. 거래를 계속할 수 없게 합니다. 이렇게 하려면 장면으로 전환할 수 있습니다.

거래 요구사항 확인 장면 만들기

Scenes 탭에서 다음 이름으로 새 장면을 추가합니다. TransactionRequirementsCheck입니다.
슬롯 채우기에서 +를 클릭하여 새 슬롯을 추가합니다.
유형 선택에서 actions.type.TransactionRequirementsCheckResult를 선택합니다. 입니다.
슬롯 이름 입력란에 슬롯 이름을 TransactionRequirementsCheck로 지정합니다.
슬롯 값 다시 쓰기 맞춤설정 체크박스를 사용 설정합니다 (기본적으로 사용 설정됨).
저장을 클릭합니다.

거래 요건 확인 결과는 다음 중 한 가지 결과로 이어집니다.

요구사항이 충족되면 세션 매개변수가 성공적으로 설정됩니다. 조건을 지정하여 사용자 주문 만들기를 진행할 수 있습니다.
요구사항을 하나 이상 충족할 수 없는 경우 세션 매개변수는 실패 조건으로 설정됩니다 이 경우 대화를 방향을 전환해야 합니다. 거래 경험에서 벗어나거나 대화를 종료하는 것이 중요합니다.
- 장애 상태를 초래하는 오류를 사용자가 수정할 수 있는 경우 기기에서 이러한 문제를 해결하라는 메시지가 표시됩니다. 만약 대화가 음성 전용 환경에서 이루어지는 경우 핸드오프는 시작됩니다.

거래 요건 확인 결과 처리

Scenes(장면) 탭에서 새로 만든 이미지를 선택합니다. TransactionRequirementsCheck 장면입니다.
조건에서 +를 클릭하여 새 조건을 추가합니다.

텍스트 필드에 다음 조건 구문을 입력하여 성공 조건:

scene.slots.status == "FINAL" && session.params.TransactionRequirementsCheck.resultType == "CAN_TRANSACT"

방금 추가한 조건 위로 커서를 가져간 다음 위쪽 화살표를 클릭합니다. if scene.slots.status == "FINAL" 앞에 배치합니다.

메시지 보내기를 사용 설정하고 사용자에게 알리는 간단한 메시지를 제공합니다. 거래를 할 준비가 되었습니다.

candidates:
  - first_simple:
      variants:
        - speech: >-
            Looks like you're good to go!.

전환에서 다른 장면을 선택하여 사용자가 계속 진행할 수 있도록 합니다. 거래를 진행합니다.
조건 else if scene.slots.status == "FINAL"을 선택합니다.
메시지 보내기를 사용 설정하고 사용자에게 알리는 간단한 메시지를 제공합니다. 거래할 수 없는 경우:
```
candidates:
  - first_simple:
      variants:
        - speech: Transaction requirements check failed.
```
전환에서 대화 종료를 선택하여 대화를 종료합니다. 거래할 수 없는 경우

주문 만들기

필요한 사용자 정보가 있으면 '장바구니'를 만드세요. assembly" 환경을 제공합니다. 매회 작업의 적절한 장바구니 조립 흐름은 있습니다.

기본 장바구니 조립 환경에서 사용자가 추가할 옵션을 목록에서 선택 사용자의 예약에 응하도록 할 수 있지만, 사용자가 편리하게 대화할 수 있도록 있습니다. 예를 들어 고객이 Google 쇼핑에서 사용자가 간단한 예 또는 아니요 질문으로 월간 예약을 예약할 수 있습니다. 사용자에게 '추천' 캐러셀 또는 목록 카드를 표시할 수도 있습니다. 예약할 수 있습니다.

리치 응답을 사용하여 사용자의 옵션을 시각적으로 보여줄 뿐만 아니라 사용자는 자신의 음성만으로도 장바구니를 빌드할 수 있습니다. 일부 권장사항 및 장바구니 조립 환경의 예시는 디자인 가이드라인을 참고하세요.

주문 만들기

대화 전반에서 사용자의 예약 세부정보를 수집한 다음 Order 객체를 구성합니다.

Order에는 최소한 다음이 포함되어야 합니다.

buyerInfo - 구매하는 사용자에 관한 정보입니다.
transactionMerchant: 주문을 지원한 판매자에 관한 정보입니다.
contents - lineItems로 표시되는 주문의 실제 콘텐츠입니다.

를 통해 개인정보처리방침을 정의할 수 있습니다.

Order를 참고하세요. 응답 문서를 참조하여 장바구니를 구성하세요. 페이지에 다른 필드를 표시할 수도 있습니다

아래 샘플 코드는 선택 필드를 포함하여 전체 예약 주문을 보여줍니다.

const order = {
   createTime: '2019-09-24T18:00:00.877Z',
   lastUpdateTime: '2019-09-24T18:00:00.877Z',
   merchantOrderId: orderId, // A unique ID String for the order
   userVisibleOrderId: orderId,
   transactionMerchant: {
     id: 'http://www.example.com',
     name: 'Example Merchant',
   },
   contents: {
     lineItems: [
       {
         id: 'LINE_ITEM_ID',
         name: 'Dinner reservation',
         description: 'A world of flavors all in one destination.',
         reservation: {
           status: 'PENDING',
           userVisibleStatusLabel: 'Reservation is pending.',
           type: 'RESTAURANT',
           reservationTime: {
             timeIso8601: '2020-01-16T01:30:15.01Z',
           },
           userAcceptableTimeRange: {
             timeIso8601: '2020-01-15/2020-01-17',
           },
           partySize: 6,
           staffFacilitators: [
             {
               name: 'John Smith',
             },
           ],
           location: {
             zipCode: '94086',
             city: 'Sunnyvale',
             postalAddress: {
               regionCode: 'US',
               postalCode: '94086',
               administrativeArea: 'CA',
               locality: 'Sunnyvale',
               addressLines: [
                 '222, Some other Street',
               ],
             },
           },
         },
       },
     ],
   },
   buyerInfo: {
     email: 'janedoe@gmail.com',
     firstName: 'Jane',
     lastName: 'Doe',
     displayName: 'Jane Doe',
   },
   followUpActions: [
     {
       type: 'VIEW_DETAILS',
       title: 'View details',
       openUrlAction: {
         url: 'http://example.com',
       },
     },
     {
       type: 'CALL',
       title: 'Call us',
       openUrlAction: {
         url: 'tel:+16501112222',
       },
     },
     {
       type: 'EMAIL',
       title: 'Email us',
       openUrlAction: {
         url: 'mailto:person@example.com',
       },
     },
   ],
   termsOfServiceUrl: 'http://www.example.com'
 };

순서 및 프레젠테이션 옵션 만들기

const orderOptions = {
      'requestDeliveryAddress': false,
    };

const presentationOptions = {
      'actionDisplayName': 'RESERVE'
    };

세션 매개변수에 주문 데이터 저장

처리에서 주문 데이터를 세션 매개변수에 저장합니다. 주문 객체가 동일한 세션의 장면 전체에서 사용됩니다.

conv.session.params.order = {
    '@type': 'type.googleapis.com/google.actions.transactions.v3.TransactionDecisionValueSpec',
    order: order,
    orderOptions: orderOptions,
    presentationOptions: presentationOptions
};

주문 제안

예약 주문을 생성한 후에는 사용자에게 제시해야 합니다. 동의 또는 거부를 선택하세요. 이렇게 하려면 트랜잭션을 실행하는 장면으로 전환해야 합니다. 결정이 내려질 수 있습니다

Transaction Decision(거래 결정) 장면 만들기

Scenes 탭에서 이름이 TransactionDecision인 새 장면을 추가합니다.
슬롯 채우기에서 +를 클릭하여 새 슬롯을 추가합니다.
유형 선택에서 다음 유형으로 actions.type.TransactionDecisionValue를 선택합니다. 슬롯 유형
슬롯 이름 입력란에 슬롯 이름을 TransactionDecision로 지정합니다.
슬롯 값 다시 쓰기 맞춤설정 체크박스를 사용 설정합니다 (기본적으로 사용 설정됨).
슬롯 구성의 드롭다운에서 세션 매개변수 사용을 선택합니다.
슬롯 구성에서 주문을 텍스트 필드 (예: $session.params.order)에 저장합니다.
저장을 클릭합니다.

TransactionDecisionValue 슬롯을 채우기 위해 어시스턴트가 전달한 Order가 '장바구니 미리보기 카드'를 선택했습니다 사용자가 "예약 예약"이라고 말하거나 거래를 거부하거나 예약 세부정보 변경을 요청할 수 있습니다

이 시점에서 사용자가 주문 변경을 요청할 수도 있습니다. 이 경우 처리에서 주문 변경 요청을 처리할 수 있는지 마무리하는 단계입니다

거래 결정 결과 처리

TransactionDecisionValue 슬롯이 채워지면 트랜잭션 결정은 세션 매개변수에 저장됩니다. 이 값에는 다음과 같습니다.

ORDER_ACCEPTED
ORDER_REJECTED
CART_CHANGE_REQUESTED
USER_CANNOT_TRANSACT.

트랜잭션 결정 결과를 처리하는 방법은 다음과 같습니다.

Scenes 탭에서 새로 만든 TransactionDecision 장면을 선택합니다.
조건에서 +를 클릭하여 새 조건을 추가합니다.

텍스트 필드에 다음 조건 구문을 입력하여 성공 조건:

scene.slots.status == "FINAL" && session.params.TransactionDecision.transactionDecision == "ORDER_ACCEPTED"

방금 추가한 조건 위로 커서를 가져간 다음 위쪽 화살표를 클릭합니다. if scene.slots.status == "FINAL" 앞에 배치합니다.

메시지 보내기를 사용 설정하고 사용자에게 알리는 간단한 메시지를 제공합니다. 예약이 완료됩니다.

candidates:
  - first_simple:
      variants:
        - speech: >-
            Transaction completed! Your reservation
            $session.params.TransactionDecision.order.merchantOrderId is all
            set!

전환에서 대화 종료를 선택하여 대화를 종료합니다.
조건에서 +를 클릭하여 새 조건을 추가합니다.

텍스트 필드에 다음 조건 구문을 입력하여 장애 조건:

  scene.slots.status == "FINAL" && session.params.TransactionDecision.transactionDecision == "ORDER_REJECTED"

방금 추가한 조건 위로 커서를 가져간 다음 위쪽 화살표를 클릭합니다. if scene.slots.status == "FINAL" 앞에 배치합니다.

메시지 보내기를 사용 설정하고 사용자에게 다음과 같은 간단한 메시지를 제공합니다. 거부된 주문:

candidates:
  - first_simple:
      variants:
        - speech: Looks like you don't want to set up a reservation. Goodbye.

전환에서 대화 종료를 선택하여 대화를 종료합니다.
조건 else if scene.slots.status == "FINAL"을 선택합니다.

메시지 보내기를 사용 설정하고 사용자에게 알리는 간단한 메시지를 제공합니다. 거래할 수 없는 경우:

candidates:
  - first_simple:
      variants:
        - speech: >-
            Transaction failed with status
            $session.params.TransactionDecision.transactionDecision

전환에서 대화 종료를 선택하여 대화를 종료합니다. 거래할 수 없는 경우

예약 완료 및 영수증 보내기

TransactionDecisionValue 슬롯이 ORDER_ACCEPTED 결과를 반환하면 요청을 수락하기 위해 필요한 작업을 예약 (예: 자체 데이터베이스에 보존)

간단한 응답을 보내 대화를 계속 이어갑니다. 사용자는 "접힌 영수증 카드" 답변도 함께 첨부합니다

최초 주문 업데이트를 보내려면 다음 단계를 따르세요.

Scenes 탭에서 TransactionDecision 장면을 선택합니다.

조건에서 성공 결과를 확인하는 조건을 선택합니다. ORDER_ACCEPTED:

scene.slots.status == "FINAL" && session.params.TransactionDecision.transactionDecision == "ORDER_ACCEPTED"

이 조건의 경우 웹훅 호출을 사용 설정하고 인텐트를 제공합니다. 핸들러 이름(예: update_order)

웹훅 코드에서 초기 주문 업데이트를 전송하기 위한 인텐트 핸들러를 추가합니다.

app.handle('update_order', conv => {
  const currentTime = new Date().toISOString();
  let order = conv.session.params.TransactionDecision.order;
  conv.add(new OrderUpdate({
    'updateMask': {
      'paths': [
        'reservation.status',
        'reservation.user_visible_status_label',
        'reservation.confirmation_code'
      ]
    },
    'order': {
      'merchantOrderId': order.merchantOrderId,
      'lastUpdateTime': currentTime,
      'reservation': {
        'status': 'CONFIRMED',
        'userVisibleStatusLabel': 'Reservation confirmed',
        'confirmationCode': '123ABCDEFGXYZ',
      },
    },
    'reason': 'Reason string'
  }));
});

주문 업데이트 보내기

예약 상태는 전체 기간 동안 변경됩니다. 사용자 보내기 Orders API에 대한 HTTP PATCH 요청으로 예약 주문 업데이트( 주문 상태 및 세부정보

Orders API에 대한 비동기 요청 설정

Orders API에 대한 주문 업데이트 요청이 액세스 권한으로 승인됨 토큰입니다. Orders API로 주문 업데이트를 PATCH하려면 JSON을 다운로드하세요. Actions Console 프로젝트와 연결된 서비스 계정 키를 생성한 다음 교환합니다. 여기에 전달할 수 있는 Bearer 토큰의 서비스 계정 키입니다. HTTP 요청의 Authorization 헤더입니다.

서비스 계정 키를 가져오려면 다음 단계를 수행합니다.

Google Cloud 콘솔에서 메뉴 ❯ >로 이동합니다. API 및 서비스 > 사용자 인증 정보 > 사용자 인증 정보 만들기 > 서비스 계정 키.
서비스 계정에서 새 서비스 계정을 선택합니다.
서비스 계정을 service-account로 설정합니다.
역할을 프로젝트 > 소유자를 선택합니다.
키 유형을 JSON으로 설정합니다.
만들기를 선택합니다.
비공개 JSON 서비스 계정 키가 로컬 머신에 다운로드됩니다.

주문 업데이트 코드에서 서비스 키를 Bearer 토큰으로 교환 Google API 클라이언트 라이브러리 및 "https://www.googleapis.com/auth/actions.order.developer" 범위입니다. 다음에서 확인할 수 있습니다. API 클라이언트 라이브러리의 설치 단계 및 예제 GitHub 페이지

Node.js 샘플에서 order-update.js 참조 살펴보겠습니다

주문 업데이트 보내기

서비스 계정 키를 OAuth Bearer 토큰으로 교환한 후 다음을 전송합니다. Orders API에 대한 승인된 PATCH 요청으로 업데이트를 주문합니다.

Orders API URL: <ph type="x-smartling-placeholder">PATCH https://actions.googleapis.com/v3/orders/${orderId}</ph>

요청에 다음 헤더를 제공합니다.

"Authorization: Bearer token"를 OAuth Bearer 토큰으로 바꿉니다. 서비스 계정 키를 교환한 경우에 사용합니다
"Content-Type: application/json".

PATCH 요청은 다음 형식의 JSON 본문을 사용해야 합니다.

{ "orderUpdate": OrderUpdate }

OrderUpdate 객체는 다음과 같은 최상위 필드로 구성됩니다.

updateMask - 업데이트할 주문의 필드입니다. 예약 상태, 값을 reservation.status, reservation.userVisibleStatusLabel로 설정합니다.
order - 업데이트 콘텐츠입니다. 예약 콘텐츠의 내용을 변경하려면 업데이트된 Order 객체로 값을 설정합니다. 예약 상태를 업데이트하는 경우 (예: "PENDING"에서 "FULFILLED"까지) 다음 필드를 포함해야 합니다.
- merchantOrderId - Order 객체에 설정한 것과 동일한 ID입니다.
- lastUpdateTime - 이 업데이트의 타임스탬프입니다.
- purchase - 다음을 포함하는 객체입니다. <ph type="x-smartling-placeholder">
  - status - 주문의 상태(ReservationStatus)입니다. 예: 'CONFIRMED' 또는 'CANCELLED'.
  - userVisibleStatusLabel - 다음에 관한 세부정보를 제공하는 사용자 대상 라벨입니다. 주문 상태(예: '예약이 확인되었습니다')
userNotification (선택사항) - userNotification 이 업데이트가 전송될 때 사용자 기기에 표시될 수 있는 객체입니다. 참고 이 객체를 포함한다고 해서 알림이 반드시 사용자의 기기에서 시작됩니다.

다음 샘플 코드는 OrderUpdate FULFILLED에 예약 주문 상태를 전송합니다.

// Import the 'googleapis' module for authorizing the request.
const {google} = require('googleapis');
// Import the 'request-promise' module for sending an HTTP POST request.
const request = require('request-promise');
// Import the OrderUpdate class from the client library.
const {OrderUpdate} = require('@assistant/conversation');

// Import the service account key used to authorize the request.
// Replacing the string path with a path to your service account key.
// i.e. const serviceAccountKey = require('./service-account.json')

// Create a new JWT client for the Actions API using credentials
// from the service account key.
let jwtClient = new google.auth.JWT(
   serviceAccountKey.client_email,
   null,
   serviceAccountKey.private_key,
   ['https://www.googleapis.com/auth/actions.order.developer'],
   null,
);

// Authorize the client
let tokens = await jwtClient.authorize();

// Declare the ID of the order to update.
const orderId = '<UNIQUE_MERCHANT_ORDER_ID>';

// Declare order update
const orderUpdate = new OrderUpdate({
   updateMask: {
     paths: [
       'contents.lineItems.reservation.status',
       'contents.lineItems.reservation.userVisibleStatusLabel'
     ]
   },
   order: {
     merchantOrderId: orderId, // Specify the ID of the order to update
     lastUpdateTime: new Date().toISOString(),
     contents: {
       lineItems: [
         {
           reservation: {
             status: 'FULFILLED',
             userVisibleStatusLabel: 'Reservation fulfilled',
           },
         }
       ]
     },
   },
   reason: 'Reservation status was updated to fulfilled.',
});

// Set up the PATCH request header and body,
// including the authorized token and order update.
let options = {
 method: 'PATCH',
 uri: `https://actions.googleapis.com/v3/orders/${orderId}`,
 auth: {
   bearer: tokens.access_token,
 },
 body: {
   header: {
     isInSandbox: true,
   },
   orderUpdate,
 },
 json: true,
};

// Send the PATCH request to the Orders API.
try {
 await request(options);
} catch (e) {
 console.log(`Error: ${e}`);
}

예약 상태 설정

주문 업데이트 ReservationStatus 주문의 현재 상태를 설명해야 합니다. 업데이트의 order.ReservationStatus 필드에서 다음 값 중 하나를 사용합니다.

PENDING - 예약이 '생성'되었습니다. 사용자의 작업 또는 백엔드에서 추가 처리를 거쳐야 합니다
CONFIRMED: 일정 백엔드에서 예약이 확인되었습니다.
CANCELLED - 사용자가 예약을 취소했습니다.
FULFILLED - 서비스에서 사용자의 예약을 처리했습니다.
CHANGE_REQUESTED - 사용자가 예약 변경을 요청했으며 변경이 다음과 같음 있습니다.
REJECTED - 처리할 수 없거나 기타 방법으로 처리할 수 없는 경우 예약을 확인합니다

판매자와 관련된 각 상태에 대한 주문 업데이트를 예약입니다. 예를 들어 예약에 수동 처리가 필요한 경우 요청한 다음 예약을 확인하고, 다음 시점까지 PENDING 주문 업데이트를 전송합니다. 추가 처리가 이루어집니다. 모든 예약에 모든 상태 값이 필요한 것은 아닙니다.

프로젝트 테스트

프로젝트를 테스트할 때 Actions 콘솔에서 샌드박스 모드를 사용 설정할 수 있습니다. 을 사용하면 결제 수단에 요금을 청구하지 않고 작업을 테스트할 수 있습니다. 샌드박스 모드를 사용 설정하려면 다음 단계를 따르세요.

Actions 콘솔의 탐색 메뉴에서 Test를 클릭합니다.
설정을 클릭합니다.
개발 샌드박스 옵션을 사용 설정합니다.

실제 거래의 경우 다음에서 isInSandbox 필드를 true로 설정할 수도 있습니다. 확인할 수 있습니다 이 작업은 다음에서 샌드박스 모드 설정을 사용 설정하는 것과 같으며 확인할 수 있습니다 isInSandbox를 사용하는 코드 스니펫을 보려면 다음을 참고하세요. 주문 업데이트 보내기 섹션.

문제 해결

테스트 중에 문제가 발생하면 문제 해결 단계를 참고하세요. 100% 업타임 체크를 제공합니다