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 חסומים: הרכיבים האלה והתוכן שלהם יוסרו ממטענים ייעודיים (payloads) של 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.

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

זה צריך להיות ביטוי שם עצם קצר ופשוט, כמו "Email", "הודעת טקסט" או "Daily Planet News Update".

מומלץ להשתמש ב-Glass כדי לאכלס את השדה הזה בכל פריט בציר הזמן, גם אם הפריט לא מכיל טקסט 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

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

##
# 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--