작업 요청 처리

작업 선언에 설명된 대로 사용자가 인앱 작업과 상호작용하면 Google에서는 작업에 선언된 URL로 HTTP 요청을 전송합니다.

다음 예시에서는 비용 보고서에 관한 이메일에 ConfirmAction 버튼을 추가합니다.

<script type="application/ld+json">
{
  "@context": "http://schema.org",
  "@type": "EmailMessage",
  "potentialAction": {
    "@type": "ConfirmAction",
    "name": "Approve Expense",
    "handler": {
      "@type": "HttpActionHandler",
      "url": "https://myexpenses.com/approve?expenseId=abc123"
    }
  },
  "description": "Approval request for John's $10.13 expense for office supplies"
}
</script>

<div itemscope itemtype="http://schema.org/EmailMessage">
  <div itemprop="potentialAction" itemscope itemtype="http://schema.org/ConfirmAction">
    <meta itemprop="name" content="Approve Expense"/>
    <div itemprop="handler" itemscope itemtype="http://schema.org/HttpActionHandler">
      <link itemprop="url" href="https://myexpenses.com/approve?expenseId=abc123"/>
    </div>
  </div>
  <meta itemprop="description" content="Approval request for John's $10.13 expense for office supplies"/>
</div>

사용자가 버튼을 클릭하면 Google에서 서비스로 HTTP 요청이 전송되어 확인을 기록합니다. 서비스가 Google로부터 다음 HTTP 요청을 수신합니다.

POST /approve?expenseId=abc123 HTTP/1.1
Host: your-domain.com
Authorization: Bearer AbCdEf123456
Content-Type: application/x-www-form-urlencoded
User-Agent: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/1.0 (KHTML, like Gecko; Gmail Actions)

confirmed=Approved

이 페이지의 나머지 부분에서는 https://your-domain.com/approve?expenseId=abc123의 서비스가 작업을 제대로 처리하기 위해 실행해야 하는 작업을 설명합니다. 여기에는 다음이 포함됩니다.

• 요청 확인
• 페이로드 처리
• 응답 코드 반환

1단계: 요청 확인

https://your-domain.com/approve?expenseId=abc123의 서비스는 다음을 확인하는 것이 좋습니다.

• 사용이 제한된 액세스 토큰 - 재전송 공격으로부터 보호합니다.
• 사용자 에이전트: Google에서 보낸 요청인지 확인합니다.
• Bearer 토큰 - Google의 요청이 서비스에 전송되도록 보장합니다.

모든 작업 요청의 사용자 에이전트는 Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/1.0 (KHTML, like Gecko; Gmail Actions)입니다.

모든 확인을 통과하면 서비스가 다음 단계로 진행할 수 있습니다.

2단계: 작업 처리

서비스는 URL 매개변수에 지정된 대로 작업과 사용자로부터 수집된 추가 정보를 처리해야 합니다.

사용자의 추가 정보는 요청 본문에 있으며, x-www-form-urlecoded 인코딩을 사용하여 인코딩됩니다. 이 정보는 이름이 Action의 속성과 일치하는 속성에서 설정됩니다. 예를 들어 ConfirmAction에는 confirmed 속성이 있습니다.

3단계: 응답 코드 반환

서비스가 작업을 성공적으로 처리하고 기록하면 응답 코드 200 (OK)이 반환됩니다. 오류 상황에서는 다음 응답 코드를 사용할 수 있습니다.

영구적으로 실패하는 경우 Google은 사용자에게 작업이 실패했으며 사용자는 이메일에 포함된 다른 안내를 따라야 한다고 알립니다.

추가 자료

• 작업 보안 설정