端對端範例

本文說明如何利用 Python 建構 App Engine 應用程式，以便將附有註解的電子郵件，讓使用者直接從收件匣確認郵寄清單訂閱，並且收集資料儲存庫中的訂閱。

事前準備和專案設定

本指南假設您已安裝 App Engine SDK，也瞭解如何建立、執行及發布 App Engine 專案。

首先，請建立專案的目錄。將應用程式的所有檔案放入這個目錄中。

將下列程式碼複製到名為 app.yaml 的檔案，並將 {{ APPID }} 預留位置改成您專屬的 App Engine 應用程式 ID：

application: {{ APPID }}
version: 1
runtime: python27
api_version: 1
threadsafe: true

handlers:
- url: /.*
  script: main.app

libraries:
- name: jinja2
  version: latest

在 App Engine 專案資料夾中建立名為 main.py 的檔案，然後複製下列程式碼，以設定處理常式來收集和列出訂閱，以及傳送已加註的電子郵件：

import webapp2

from emailsender import EmailSender
from subscribe import SubscribeHandler

app = webapp2.WSGIApplication([('/', SubscribeHandler), ('/email', EmailSender)], debug=True)

為電子郵件新增結構化資料

我們先從簡單的電子郵件開始，要求使用者確認訂閱郵寄清單：

<html>
  <head>
    <title>Please confirm your subscription to Mailing-List XYZ?</title>
  </head>
  <body>
    <p>
      Dear John, please confirm that you wish to be subscribed to the
      mailing list XYZ
    </p>
  </body>
</html>

您可以在電子郵件的 head 中加入其中一種支援格式 (JSON-LD 或微資料) 的結構化資料，藉此定義餐廳並新增 OneClickAction。Gmail 支援 OneClickAction，並向使用者顯示特定的使用者介面，方便使用者在收件匣中確認訂閱。

將下列標記複製到名為 mail_template.html 的檔案中：

JSON-LD

<html>
  <head>
  <title>Please confirm your subscription to Mailing-List XYZ?</title>
  </head>
  <body>
    <script type="application/ld+json">
    {
      "@context": "http://schema.org",
      "@type": "EmailMessage",
      "potentialAction": {
        "@type": "ConfirmAction",
        "name": "Confirm Subscription",
        "handler": {
          "@type": "HttpActionHandler",
          "url": "{{ confirm_url }}",
          "method": "http://schema.org/HttpRequestMethod/POST",
        }
      },
      "description": "Confirm subscription to mailing list XYZ"
    }
    </script>
    <p>
      Dear John, please confirm that you wish to be subscribed to the mailing list XYZ.
    </p>
  </body>
</html>

微資料

<html>
  <head>
    <title>Please confirm your subscription to Mailing-List XYZ?</title>
  </head>
  <body>
    <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"/>
          <meta itemprop="url" content="{{ confirm_url }}"/>
          <link itemprop="method" href="http://schema.org/HttpRequestMethod/POST"/>
        </div>
      </div>
      <meta itemprop="description" content="Approval request for John's $10.13 expense for office supplies"/>
    </div>
    <p>
      Dear John, please confirm that you wish to be subscribed to the mailing list XYZ.
    </p>
  </body>
</html>

上方的結構化資料是名為「XYZ」的郵寄清單和 ConfirmAction。動作的處理常式是 HttpActionHandler，可將 POST 要求傳送至 url 屬性中指定的網址。

將訂閱要求傳送給使用者

將下列程式碼複製到 App Engine 專案資料夾中名為 emailsender.py 的檔案：

import jinja2
import os
import webapp2

from google.appengine.api import mail
from google.appengine.api import users

from urlparse import urlparse

class EmailSender(webapp2.RequestHandler):

  def get(self):
    # require users to be logged in to send emails
    user = users.get_current_user()
    if not user:
      self.redirect(users.create_login_url(self.request.uri))
      return

    email = user.email()

    # The confirm url corresponds to the App Engine app url
    pr = urlparse(self.request.url)
    confirm_url = '%s://%s?user=%s' % (pr.scheme, pr.netloc, user.user_id())

    # load the email template and replace the placeholder with the confirm url
    jinja_environment = jinja2.Environment(
        loader=jinja2.FileSystemLoader(os.path.dirname(__file__)))
    template = jinja_environment.get_template('mail_template.html')
    email_body = template.render({'confirm_url': confirm_url})

    message = mail.EmailMessage(
        sender = email,
        to = email,
        subject = 'Please confirm your subscription to Mailing-List XYZ',
        html = email_body)

    try:
      message.send()
      self.response.write('OK')
    except:
      self.error(500)

EmailSender 類別會要求使用者登入，系統才能擷取其電子郵件地址。接著，它會從 mail_template.html 載入電子郵件內文，將其中的 confirm_url 預留位置取代為 App Engine 應用程式的根網址 (https://APP-ID.appspot.com)，然後同樣傳送電子郵件給目前登入的使用者。

收集及列出訂閱項目

將下列程式碼複製到 App Engine 專案資料夾中名為 subscribe.py 的檔案：

import webapp2

from emailsender import EmailSender
from google.appengine.ext import db


class SubscribeHandler(webapp2.RequestHandler):

  def post(self):
    user_id = self.request.get('user')

    # insert the subscription into the Datastore
    subscription = Subscription(user_id=user_id)
    subscription.put()

  def get(self):
    # retrieve up to 1000 subscriptions from the Datastore
    subscriptions = Subscription.all().fetch(1000)

    if not subscriptions:
      self.response.write('No subscriptions')
      return

    count = len(subscriptions)

    for s in subscriptions:
      self.response.write('%s subscribed<br/>' % (s.user_id))

    self.response.write('<br/>')
    self.response.write('%d subscriptions.' % (count))


class Subscription(db.Model):
    user_id = db.TextProperty(required=True)

對應至使用者的 SubscribeHandlerclass listens to bothPOSTandGETrequests sent to the app root url (https://APP-ID.appspot.com).POSTrequests are used by Gmail to insert new subscriptions including theuser_id` 參數，如以下範例所示：

https://subscribe.appspot.com/?user_id=123abcd

要求處理常式只會檢查是否已定義必要的 user_id，然後將訂閱項目儲存至 Datastore。系統將傳回 HTTP 200 回應代碼，用於表示要求成功，如果要求中沒有必要的欄位，要求處理常式將傳回 HTTP 400 回應代碼，指出無效的要求。

系統會使用對應用程式根網址發出的 GET 要求，列出已收集的訂閱項目。要求處理常式會先從 Datastore 擷取所有訂閱項目，然後透過簡易計數器，在頁面中列印這些訂閱項目。

測試應用程式

將應用程式部署至 App Engine，然後前往 https://APP-ID.appspot.com/email (使用您的 App Engine 應用程式 ID 取代 APP-ID)，將已加註的電子郵件傳送給自己。

在 Gmail 中的動作

部署應用程式並插入某些訂閱項目後，請前往 https://APP-ID.appspot.com 開啟應用程式，以取得訂閱項目摘要頁面