דוגמה מקצה לקצה

במאמר הזה נסביר איך ליצור אפליקציית App Engine ב-Python ששולחת למשתמשים אימיילים עם הערות ומבקשת מהם לאשר את ההרשמה לרשימת תפוצה ישירות מתיבת הדואר הנכנס שלהם, ואיך לאסוף את ההרשמות ב-Datastore.

דרישות מוקדמות והגדרת הפרויקט

המדריך הזה מיועד למשתמשים שכבר התקינו את App Engine SDK ויודעים איך ליצור, להריץ ולפרסם פרויקטים של App Engine.

קודם יוצרים ספרייה לפרויקט. ממקמים את כל הקבצים של האפליקציה בספרייה הזו.

מעתיקים את הקוד הבא לקובץ בשם app.yaml ומחליפים את ה-placeholder‏ {{ APPID }} במזהה הייחודי של האפליקציה ב-App Engine:

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

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

libraries:
- name: jinja2
  version: latest

יוצרים קובץ בשם main.py בתיקיית הפרויקט של App Engine ומעתיקים את הקוד הבא כדי להגדיר את ה-handlers לאיסוף ולרישום של מינויים, ולשליחה של אימיילים עם הערות:

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>

אתם יכולים להוסיף נתונים מובְנים באחד מהפורמטים הנתמכים (JSON-LD או מיקרו נתונים) לhead של האימייל כדי להגדיר את המסעדה ולהוסיף 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. ה-handler של הפעולה הוא HttpActionHandler ששולח בקשות POST לכתובת ה-URL שצוינה במאפיין url.

שליחת בקשות להרשמה למשתמשים

מעתיקים את הקוד הבא לקובץ בשם emailsender.py בתיקיית הפרויקט של App Engine:

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, מחליפה את ה-placeholder‏ confirm_url בכתובת ה-URL הבסיסית של אפליקציית App Engine‏ (https://APP-ID.appspot.com) ושולחת את האימייל למשתמש שמחובר כרגע לחשבון, כאילו הוא שלח אותו בעצמו.

איסוף ורישום של מינויים

מעתיקים את הקוד הבא לקובץ בשם subscribe.py בתיקיית הפרויקט של App Engine:

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 נשלח חזרה ל-Gmail כדי לציין שהבקשה הצליחה. אם הבקשה לא כוללת את השדה הנדרש, רכיב ה-handler של הבקשה יחזיר קוד תגובה HTTP 400, שמציין שהבקשה לא תקינה.

בקשות GET לכתובת ה-URL הבסיסית של האפליקציה משמשות לרישום המינויים שנאספו. קודם, רכיב ה-handler של הבקשה מאחזר את כל המינויים מ-Datastore ואז מדפיס אותם בדף, יחד עם מונה פשוט.

בדיקת האפליקציה

פורסים את האפליקציה ב-App Engine ונכנסים לכתובת https://APP-ID.appspot.com/email (מחליפים את APP-ID במזהה האפליקציה ב-App Engine) כדי לשלוח לעצמכם את האימייל עם ההערות.

פעולות ב-Gmail

אחרי שפורסים את האפליקציה ומוסיפים לה מינויים, נכנסים לאפליקציה בכתובת https://APP-ID.appspot.com כדי לראות דף עם סיכום של המינויים.