Timeline: insert

נדרשת הרשאה

הוספת פריט חדש לציר הזמן. לעיון בדוגמה

השיטה הזו תומכת ב-URI של /upload ומקבלת קובצי מדיה שהועלו באמצעות המאפיינים הבאים:

  • גודל הקובץ המקסימלי: 10MB
  • סוגים מקובלים של MIME מדיה: image/* , audio/* , video/*

אם צירפתם את המדיה שהעליתם כקובץ מצורף לפריט בציר הזמן.

שליחת בקשה

בקשת HTTP

השיטה הזו מספקת פונקציונליות להעלאת מדיה באמצעות שני URI נפרדים. לפרטים נוספים, עיינו במסמך בנושא העלאת מדיה.

  • URI להעלאה, עבור בקשות להעלאת מדיה: 
    POST https://www.googleapis.com/upload/mirror/v1/timeline
  • URI של מטא-נתונים, עבור בקשות למטא-נתונים בלבד: 
    POST https://www.googleapis.com/mirror/v1/timeline

פרמטרים

שם הפרמטר ערך תיאור
פרמטרים נדרשים של שאילתה
uploadType string סוג בקשת ההעלאה ל-URI של /upload. ערכים קבילים:
  • media – העלאה פשוטה. מעלים את המדיה בלבד, ללא מטא-נתונים.
  • multipart – העלאה בכמה חלקים. העלאת המדיה והמטא-נתונים שלה בבקשה אחת.
  • resumable – ניתן להמשיך את ההעלאה. יש להעלות את הקובץ באופן שניתן לחידוש ולהשתמש בסדרה של שתי בקשות לפחות, שבהן הבקשה הראשונה כוללת את המטא-נתונים.

הרשאה

לבקשה הזו נדרשת הרשאה עם לפחות אחד מהיקפי ההרשאות הבאים (מידע נוסף על אימות והרשאה).

היקף
https://www.googleapis.com/auth/glass.timeline
https://www.googleapis.com/auth/glass.location

גוף הבקשה

בגוף הבקשה, יש לספק משאב של ציר הזמן עם המאפיינים הבאים בתור המטא-נתונים. מידע נוסף זמין במסמך בנושא העלאת מדיה.

שם הנכס ערך תיאור הערות
מאפיינים אופציונליים
bundleId string מזהה החבילה של הפריט הזה. השירותים יכולים לציין BundleId לקיבוץ פריטים רבים יחד. הן מופיעות מתחת לפריט אחד ברמה העליונה במכשיר. ניתן לכתיבה
canonicalUrl string כתובת URL קנונית שמפנה לגרסה הקנונית/האיכותית של הנתונים שמיוצגים על ידי הפריט בציר הזמן. ניתן לכתיבה
creator nested object המשתמש או הקבוצה שיצרו את הפריט הזה. ניתן לכתיבה
displayTime datetime הזמן שאמור להופיע כאשר הפריט מוצג בציר הזמן, בפורמט בהתאם ל-RFC 3339. ציר הזמן של המשתמש הזה ממוין באופן כרונולוגי בעת הצגתו, כך שגם הוא יקבע היכן הפריט יוצג בציר הזמן. אם השירות לא הוגדר, זמן התצוגה יהיה ברירת המחדל של השעה updated. ניתן לכתיבה
html string תוכן HTML של הפריט הזה. אם מציינים גם את text וגם את html עבור הפריט, html יוצג בציר הזמן.

רכיבי HTML מותרים – אפשר להשתמש ברכיבים האלה בכרטיסי ציר הזמן.

  • כותרות: h1, h2, h3, h4, h5, h6
  • תמונות: img
  • רשימות: li, ol, ul
  • סמנטי HTML5: article, aside, details, figure, figcaption, footer, header, nav, section, summary, time
  • מבני: blockquote, br, div, hr, p, span
  • סגנון: b, big, center, em, i, u, s, small, strike, strong, style, sub, sup
  • טבלאות: table, tbody, td, tfoot, th, thead, tr

רכיבי HTML חסומים: הרכיבים האלה והתוכן שלהם נמחקים ממטענים ייעודיים (payload) של HTML.

  • כותרות המסמכים: head, title
  • הטמעות: audio, embed, object, source, video
  • מסגרות: frame, frameset
  • כתיבת סקריפטים: applet, script

רכיבים אחרים: אלמנטים שאינם רשומים מוסרים, אבל התוכן שלהם נשמר.

 ניתן לכתיבה
isBundleCover boolean האם הפריט הזה הוא עטיפת חבילה.

אם פריט מסומן ככיסוי חבילה, הוא ישמש כנקודת הכניסה לחבילת הפריטים שיש להם bundleId זהה לפריט הזה. הוא יוצג רק בציר הזמן הראשי – לא בחבילה הפתוחה.

בציר הזמן הראשי, הפריטים המוצגים הם:
  • פריטים שהמאפיין isBundleCover מוגדר בהם true
  • פריטים שאין להם bundleId
בציר זמן של חבילה, הפריטים המוצגים הם:
  • פריטים שבהם bundleId הנדונים וגם isBundleCover הוגדרו כ-false
ניתן לכתיבה
location nested object המיקום הגיאוגרפי המשויך לפריט זה. ניתן לכתיבה
notification nested object שליטה באופן שבו מוצגות התראות על הפריט הזה במכשיר. אם הפרמטר הזה חסר, לא תיווצר התראה. ניתן לכתיבה
notification.deliveryTime datetime השעה שבה ההודעה אמורה להישלח. ניתן לכתיבה
notification.level string מתאר את מידת החשיבות של ההתראה. הערכים המותרים הם:
  • DEFAULT – התראות על חשיבות ברירת המחדל. יושמע צלצול כדי לשלוח התראה למשתמשים.
 ניתן לכתיבה
recipients[] list רשימה של משתמשים או קבוצות שאיתם הפריט שותף. ניתן לכתיבה
sourceItemId string מחרוזת אטומה שבה ניתן להשתמש כדי למפות פריט של ציר זמן לנתונים בשירות שלך. ניתן לכתיבה
speakableText string הגרסה שניתנת להקראה של תוכן הפריט הזה. יחד עם האפשרות בתפריט READ_ALOUD, השתמשו בשדה הזה כדי להוסיף טקסט שיהיה ברור יותר בזמן הקריאה בקול, או כדי לספק מידע מורחב למה שמוצג באופן חזותי ב-Glass.

כלי הזכוכית צריך גם לציין את שדה ה-SpeakableType, שיוקרא לפני הטקסט הזה במקרים שבהם ההקשר הנוסף שימושי, לדוגמה כאשר המשתמש מבקש שפריט יוקרא בקול לאחר התראה.
 ניתן לכתיבה
speakableType string תיאור של סוג הפריט, שניתן לבטא אותו. הוא יודיע למשתמש לפני קריאת תוכן הפריט במקרים שבהם ההקשר הנוסף שימושי, למשל כאשר המשתמש מבקש להקריא את הפריט לאחר קבלת הודעה.

עליו להיות ביטוי קצר ופשוט של שם עצם, כגון "אימייל", "הודעת טקסט", או "עדכון יומי של כוכבי לכת".

מומלץ להזין את Glassware עבור השדה הזה עבור כל פריט בציר הזמן, גם אם הפריט לא מכיל SpeakableText או טקסט כדי שהמשתמש יוכל ללמוד את סוג הפריט בלי להסתכל במסך.		 ניתן לכתיבה
text string תוכן הטקסט של הפריט הזה. ניתן לכתיבה
title string הכותרת של פריט זה. ניתן לכתיבה

תשובה

אם הצלחת, השיטה הזו מחזירה משאב של ציר זמן בגוף התגובה.

דוגמאות

הערה: דוגמאות הקוד הזמינות לשיטה זו לא מייצגות את כל שפות התכנות הנתמכות (רשימת השפות הנתמכות זמינה בדף של ספריות המשתמשים).

Java

משתמש בספריית הלקוחות של Java.

import com.google.api.client.http.InputStreamContent;
import com.google.api.services.mirror.Mirror;
import com.google.api.services.mirror.model.NotificationConfig;
import com.google.api.services.mirror.model.TimelineItem;

import java.io.IOException;
import java.io.InputStream;

public class MyClass {
  // ...

  /**
   * Insert a new timeline item in the user's glass with an optional
   * notification and attachment.
   * 
   * @param service Authorized Mirror service.
   * @param text timeline item's text.
   * @param contentType Optional attachment's content type (supported content
   *        types are "image/*", "video/*" and "audio/*").
   * @param attachment Optional attachment stream.
   * @param notificationLevel Optional notification level, supported values are
   *        {@code null} and "AUDIO_ONLY".
   * @return Inserted timeline item on success, {@code null} otherwise.
   */
  public static TimelineItem insertTimelineItem(Mirror service, String text, String contentType,
      InputStream attachment, String notificationLevel) {
    TimelineItem timelineItem = new TimelineItem();
    timelineItem.setText(text);
    if (notificationLevel != null && notificationLevel.length() > 0) {
      timelineItem.setNotification(new NotificationConfig().setLevel(notificationLevel));
    }
    try {
      if (contentType != null && contentType.length() > 0 && attachment != null) {
        // Insert both metadata and attachment.
        InputStreamContent mediaContent = new InputStreamContent(contentType, attachment);
        return service.timeline().insert(timelineItem, mediaContent).execute();
      } else {
        // Insert metadata only.
        return service.timeline().insert(timelineItem).execute();
      }
    } catch (IOException e) {
      System.err.println("An error occurred: " + e);
      return null;
    }
  }

  // ...
}

‎.NET

משתמש בספריית הלקוח מסוג .NET

using System;
using System.IO;

using Google.Apis.Mirror.v1;
using Google.Apis.Mirror.v1.Data;

public class MyClass {
  // ...

  /// <summary>
  /// Insert a new timeline item in the user's glass with an optional
  /// notification and attachment.
  /// </summary>
  /// <param name='service'>Authorized Mirror service.</param>
  /// <param name='text'>Timeline Item's text.</param>
  /// <param name='contentType'>
  /// Optional attachment's content type (supported content types are
  /// "image/*", "video/*" and "audio/*").
  /// </param>
  /// <param name='attachment'>Optional attachment stream</param>
  /// <param name='notificationLevel'>
  /// Optional notification level, supported values are null and
  /// "AUDIO_ONLY".
  /// </param>
  /// <returns>
  /// Inserted timeline item on success, null otherwise.
  /// </returns>
  public static TimelineItem InsertTimelineItem(MirrorService service,
      String text, String contentType, Stream attachment,
      String notificationLevel) {
    TimelineItem timelineItem = new TimelineItem();
    timelineItem.Text = text;
    if (!String.IsNullOrEmpty(notificationLevel)) {
      timelineItem.Notification = new NotificationConfig() {
        Level = notificationLevel
      };
    }
    try {
      if (!String.IsNullOrEmpty(contentType) && attachment != null) {
        // Insert both metadata and media.
        TimelineResource.InsertMediaUpload request = service.Timeline.Insert(
            timelineItem, attachment, contentType);
        request.Upload();
        return request.ResponseBody;
      } else {
        // Insert metadata only.
        return service.Timeline.Insert(timelineItem).Fetch();
      }
    } catch (Exception e) {
      Console.WriteLine("An error occurred: " + e.Message);
      return null;
    }
  }

  // ...
}

PHP

משתמש בספריית הלקוח של PHP.

/**
 * Insert a new timeline item in the user's glass with an optional
 * notification and attachment.
 *
 * @param Google_MirrorService $service Authorized Mirror service.
 * @param string $text timeline item's text.
 * @param string $contentType Optional attachment's content type (supported
 *                            content types are "image/*", "video/*"
 *                            and "audio/*").
 * @param string $attachment Optional attachment content.
 * @param string $notificationLevel Optional notification level,
 *                                  supported values are {@code null}
 *                                  and "AUDIO_ONLY".
 * @return Google_TimelineItem Inserted timeline item on success, otherwise.
 */
function insertTimelineItem($service, $text, $contentType, $attachment,
                            $notificationLevel) {
  try {
    $timelineItem = new Google_TimelineItem();
    $timelineItem->setText($text);
    if ($notificationlevel != null) {
      $notification = new Google_NotificationConfig();
      $notification->setLevel($notificationLevel);
      $timelineItem->setNotification($notification);
    }
    $optParams = array();
    if ($contentType != null && $attachment != null) {
      $optParams['data'] = $attachment;
      $optParams['mimeType'] = $contentType;
    }
    return $service->timeline->insert($timelineItem, $optParams);
  } catch (Exception $e) {
    print 'An error occurred: ' . $e->getMessage();
    return null;
  }
}

Python

משתמש בספריית הלקוחות של Python.

import io

from apiclient import errors
from apiclient.http import MediaIoBaseUpload
# ...

def insert_timeline_item(service, text, content_type=None, attachment=None,
                         notification_level=None):
  """Insert a new timeline item in the user's glass.

  Args:
    service: Authorized Mirror service.
    text: timeline item's text.
    content_type: Optional attachment's content type (supported content types
                  are 'image/*', 'video/*' and 'audio/*').
    attachment: Optional attachment as data string.
    notification_level: Optional notification level, supported values are None
                        and 'AUDIO_ONLY'.

  Returns:
    Inserted timeline item on success, None otherwise.
  """
  timeline_item = {'text': text}
  media_body = None
  if notification_level:
    timeline_item['notification'] = {'level': notification_level}
  if content_type and attachment:
    media_body = MediaIoBaseUpload(
        io.BytesIO(attachment), mimetype=content_type, resumable=True)
  try:
    return service.timeline().insert(
        body=timeline_item, media_body=media_body).execute()
  except errors.HttpError, error:
    print 'An error occurred: %s' % error

Ruby

משתמש בספריית הלקוחות של Rubby.

##
# Insert a new Timeline Item in the user's glass.
#
# @param [Google::APIClient] client
#   Authorized client instance.
# @param [String] text
#   Timeline item's text.
# @param [String] content_type
#   Optional attachment's content type (supported content types are 'image/*',
#   'video/*' and 'audio/*').
# @param [String] filename
#   Optional attachment's filename.
# @param [String] notification_level
#   Optional notification level, supported values are nil and 'AUDIO_ONLY'.
# @return [Google::APIClient::Schema::Mirror::V1::TimelineItem]
#   Timeline item instance if successful, nil otherwise.
def insert_timeline_item(client, text, content_type, filename,
                         notification_level)
  mirror = client.discovered_api('mirror', 'v1')
  timeline_item = mirror.timeline.insert.request_schema.new({ 'text' => text })
  if notification_level
    timeline_item.notification = { 'level' => notification_level }
  end
  result = nil
  if filename
    media = Google::APIClient::UploadIO.new(filename, content_type)
    result = client.execute(
      :api_method => mirror.timeline.insert,
      :body_object => timeline_item,
      :media => media,
      :parameters => {
        'uploadType' => 'multipart',
        'alt' => 'json'})
  else
    result = client.execute(
      :api_method => mirror.timeline.insert,
      :body_object => timeline_item)
  end
  if result.success?
    return result.data
  else
    puts "An error occurred: #{result.data['error']['message']}"
  end
end

Go

נעשה שימוש בספריית הלקוחות של Go.

import (
	"code.google.com/p/google-api-go-client/mirror/v1"
	"fmt"
	"io"
)

// InsertTimelineItem inserts a new timeline item in the user's glass with an
// optional notification and attachment.
func InsertTimelineItem(g *mirror.Service, text string, attachment io.Reader,
	notificationLevel string) (*mirror.TimelineItem, error) {
	t := &mirror.TimelineItem{Text: text}
	if notificationLevel != "" {
		t.Notification = &mirror.NotificationConfig{Level: notificationLevel}
	}
	req := g.Timeline.Insert(t)
	if attachment != nil {
		// Add attachment to the timeline item.
		req.Media(attachment)
	}
	r, err := req.Do()
	if err != nil {
		fmt.Printf("An error occurred: %v\n", err)
		return nil, err
	}
	return r, nil
}

HTTP גולמי

לא נעשה שימוש בספריית לקוח.

## A very simple timeline item

POST /mirror/v1/timeline HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer auth token
Content-Type: application/json
Content-Length: 26

{ "text": "Hello world" }

## A more complete timeline item with an attachment

POST /mirror/v1/timeline HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer auth token
Content-Type: multipart/related; boundary="mymultipartboundary"
Content-Length: length

--mymultipartboundary
Content-Type: application/json; charset=UTF-8

{
 "text": "Hello world",
 "menuItems": [
   { "action": "REPLY" },
   {
     "action": "CUSTOM",
     "id": "complete"
     "values": [{
       "displayName": "Complete",
       "iconUrl": "http://example.com/icons/complete.png"
     }]
   }
}
--mymultipartboundary
Content-Type: image/jpeg
Content-Transfer-Encoding: binary

binary image data
--mymultipartboundary--