10.5. API בקרה למצלמה

הבעלים צריך להגדיר את רגישות מזהה התנועה מכל מקום – הרוח מניעה עצים יותר ביום סוער. משמעות הדבר היא מסלולים שמהם לוח הבקרה יכול לקרוא את ההגדרות הנוכחיות ואליהם לשלוח שינויים.

dict קטן של מצב משותף במודול מספיק כדי להחזיק את הכפתורים. דפים מאוחרים יותר מוסיפים לו עוד מפתחות; לעת עתה יש אחד:

state = {
    'threshold': 12,
    'frame_count': 0,
    'trigger_count': 0,
}

10.5.1. GET לקריאה, POST לכתיבה

צמד מסלולים – אחד get, אחד post – מעניק ללוח הבקרה גישת קריאה/כתיבה אל state:

from microdot import abort

@app.get('/config')
async def get_config(request):
    return state

@app.post('/config')
async def set_config(request):
    body = request.json
    if not body or 'threshold' not in body:
        abort(400, 'missing threshold')
    try:
        threshold = int(body['threshold'])
    except (TypeError, ValueError):
        abort(400, 'threshold must be an integer')
    if not 0 <= threshold <= 100:
        abort(400, 'threshold out of range')
    state['threshold'] = threshold
    return {'ok': True, 'threshold': threshold}

microdot.Request.json מחזיר את הגוף מנותח כ-JSON, או None אם Content-Type לא היה application/json. המטפל post עובר על כל מצב כשל – מפתח חסר, סוג שגוי, מחוץ לטווח – ונסוג עם microdot.abort(), המעלה microdot.HTTPException כדי לקצר את המטפל עם הסטטוס וההודעה הנתונים.

10.5.2. GET, POST, PUT, DELETE

get() ו-post() הן השתיים שבהן נשתמש הכי הרבה. put() ו-delete() קיימות עבור מקרים העוקבים אחר מוסכמות REST – PUT /events/42 כדי להחליף את אירוע 42, DELETE /events/42 כדי להסירו. מלבד זאת המטפל זהה.

10.5.3. קריאת מחרוזות שאילתה וטפסים

לוח הבקרה שולח JSON, ולכן request.json הוא מה שאנו רוצים. שתי דרכים אחרות שבהן המצלמה עשויה לקבל נתונים:

• args – מחרוזת השאילתה. ?foo=1&bar=2 הופך ל-microdot.MultiDict שאותו ניתן לקרוא עם request.args.get('foo').

• form – טופס HTML שנשלח כ-application/x-www-form-urlencoded. אותו סוג MultiDict.

ה-MultiDict הוא דמוי-dict אך מאפשר למפתח אחד לשאת ערכים מרובים (?tag=cat&tag=dog הוא שני ערכי tag); ראה microdot.MultiDict עבור הממשק המלא.

10.5.4. מקטעי URL דינמיים

נתיב מסלול יכול להכריז על placeholders מוטיפסים ש-microdot מעביר למטפל כארגומנטים נוספים:

@app.get('/events/<int:event_id>')
async def get_event(request, event_id):
    return {'id': event_id, 'msg': 'placeholder'}

הממירים הנתמכים הם <int:>, <re:> עבור regex מותאם אישית, <path:> עבור מקטע שיכול להכיל לוכסנים, וברירת המחדל (ללא קידומת) עבור ”התאם כל דבר עד הלוכסן הבא.“ <int:event_id> מקבל /events/42 ודוחה /events/abc – הדחייה הופכת ל-404 מבלי שהמטפל ירוץ.

10.5.5. תגובות שגיאה מותאמות אישית

ה-404 שברירת המחדל ש-microdot שולח הוא Not found פשוט. לוח הבקרה מצפה ל-JSON עבור כל תגובה; דרוס את מטפל ה-404 כך שיחזיר גם הוא JSON:

@app.errorhandler(404)
async def not_found(request):
    return {'error': 'not found', 'path': request.path}, 404

errorhandler() מקבל או קוד סטטוס (תופס כל שגיאה של אותו סטטוס) או מחלקת חריגה (תופס כל מטפל שהעלה את אותה חריגה). הצמד (body, status) מקצר את התגובה מבלי לבנות Response.

המצלמה כעת חושפת את מצבה ומקבלת עריכות.