Timeline: insert

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

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

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

يجب أن تكون العبارة قصيرة أو بسيطة، مثل "البريد الإلكتروني" أو "رسالة نصية" أو "آخر الأخبار اليومية على الكوكب".

ننصح باستخدام هذا الحقل لكل عنصر في المخطط الزمني، حتى إذا كان العنصر لا يحتوي على نص يمكن قوله أو حتى لا يتمكن المستخدم من معرفة نوع العنصر بدون النظر إلى الشاشة.		 قابلة للكتابة
text string محتوى النص لهذا العنصر. قابلة للكتابة
title string عنوان هذا العنصر. قابلة للكتابة

الإجابة

إذا نجحت هذه الطريقة، فإنها تعرض مورد المخطط الزمني في نص الاستجابة.

أمثلة

ملاحظة: إنّ الأمثلة المرتبطة بالرموز والمتوفرة لهذه الطريقة لا تمثّل كل لغات البرمجة المتوافقة (يُرجى مراجعة صفحة مكتبات البرامج للاطّلاع على قائمة باللغات المتوافقة).

لغة 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--