アクションの宣言で説明したように、ユーザーがアプリ内アクションを操作すると、Google はそのアクションで宣言された URL に HTTP リクエストを送信します。
次の例では、経費報告書に関するメールに ConfirmAction
ボタンを追加します。
JSON-LD
<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>
microdata
<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 から送信されていることを確認するため。
- 署名なしトークン - Google からのリクエストが、サービス宛てであることを保証します。
すべてのアクション リクエストのユーザー エージェントは Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/1.0 (KHTML, like Gecko; Gmail Actions)
です。
すべてのチェックに合格すると、サービスは次のステップに進みます。
ステップ 2: アクションを処理する
サービスは、URL パラメータで指定されたアクションと、ユーザーから収集した追加情報を処理する必要があります。
ユーザーからの追加情報はリクエストの本文にあり、x-www-form-urlecoded エンコードを使用してエンコードされます。この情報は、アクションのプロパティに対応する名前を持つプロパティに設定されます。たとえば、ConfirmAction には confirmed
プロパティがあります。
ステップ 3: レスポンス コードを返す
サービスは、アクションを正常に処理して記録すると、レスポンス コード 200 (OK)
を返します。エラーの場合は、次のレスポンス コードを使用できます。
レスポンス コード | 処置 |
---|---|
400(不正なリクエスト) | Google はこのアクションを失敗させます。 |
401(未承認) | Google はこのアクションを失敗させます。 |
404(ファイル未検出) | Google はこのアクションを失敗させます。 |
408(リクエスト タイムアウト) | しばらくしてからもう一度お試しください。 |
永続的なエラーが発生した場合は、Google からユーザーに、操作が失敗したことと、メールに記載された別の手順を行う必要があることが通知されます。