Timeline: insert

يتطلّب تفويضًا

إدراج عنصر جديد في المخطط الزمني. اطّلِع على مثال.

تتوافق هذه الطريقة مع معرّف الموارد المنتظم (URI) /upload وتقبل الوسائط التي تم تحميلها بالخصائص التالية:

  • الحد الأقصى لحجم الملف: 10 ميغابايت
  • أنواع 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 معرِّف الحزمة لهذه السلعة. يمكن للخدمات تحديد packageId لتجميع العديد من العناصر معًا. وتظهر تحت عنصر واحد من المستوى الأعلى على الجهاز. قابل للكتابة
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 المحظورة: تتم إزالة هذه العناصر ومحتواها من حمولات 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 تمثّل هذه السمة وصفًا شفهيًا لنوع هذا العنصر. يتم إشعار المستخدم بذلك قبل قراءة محتوى العنصر في الحالات التي يكون فيها السياق الإضافي مفيدًا، على سبيل المثال عندما يطلب المستخدم قراءة العنصر بصوت عالٍ بعد تلقّي إشعار.

يجب أن تكون هذه العبارة اسمية قصيرة وبسيطة مثل "البريد الإلكتروني" أو "رسالة نصية" أو "موجز أخبار Daily Planet".

ننصح باستخدام 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

تستخدم مكتبة برامج 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.

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