این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

کارت های استاتیک

شما می‌توانید با استفاده از APIهای ساده REST، کارت‌های استاتیک را وارد، به‌روزرسانی، خوانده و حذف کنید. علاوه بر این، می‌توانید اشیاء را به یک کارت استاتیک، مانند یک مکان یا رسانه، پیوست کنید.

چگونه کار می‌کنند

کارت‌های ایستا به طور پیش‌فرض در سمت راست ساعت شیشه‌ای قرار دارند و اطلاعات مربوط به کاربر را در زمان تحویل نمایش می‌دهند. با این حال، آنها مانند کارت‌های زنده به توجه فوری نیاز ندارند و کاربران می‌توانند در اوقات فراغت خود کارت را بخوانند یا روی آن عمل کنند.

وقتی Glassware کارت‌های استاتیک را در جدول زمانی قرار می‌دهد، ممکن است Glass یک صدای اعلان برای هشدار به کاربران پخش کند. تمام کارت‌های استاتیک قبلی نیز به سمت راست تغییر مکان می‌دهند و پس از ۷ روز یا زمانی که ۲۰۰ کارت جدیدتر می‌شوند، از جدول زمانی ناپدید می‌شوند.

چه زمانی از آنها استفاده کنیم

کارت‌های استاتیک برای ارسال اعلان‌های دوره‌ای به کاربران هنگام وقوع اتفاقات مهم عالی هستند. به عنوان مثال، یک سرویس ارسال خبر که اخبار مهم را همزمان با وقوع ارسال می‌کند. کارت‌های استاتیک Mirror API همچنین می‌توانند از طریق آیتم منوی OPEN_URI کارت‌های زنده یا غوطه‌وری را شروع کنند. این به شما امکان می‌دهد تعاملات ترکیبی ایجاد کنید که از کارت‌های استاتیک به عنوان اعلان و یک کارت زنده یا غوطه‌وری برای یک تجربه تعاملی‌تر استفاده می‌کنند.

برای فهرست کاملی از عملیات ممکن برای موارد جدول زمانی، به مستندات مرجع مراجعه کنید.

وارد کردن کارت‌های استاتیک

برای درج کارت‌های استاتیک (آیتم‌های تایم‌لاین)، یک نمایش JSON از یک آیتم تایم‌لاین را به نقطه پایانی REST ارسال کنید.

بیشتر فیلدهای یک آیتم جدول زمانی اختیاری هستند. در ساده‌ترین شکل، یک آیتم جدول زمانی فقط شامل یک پیام متنی کوتاه است، مانند این مثال:

HTTP خام

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

جاوا

TimelineItem timelineItem = new TimelineItem();
timelineItem.setText("Hello world");
service.timeline().insert(timelineItem).execute();

پایتون

timeline_item = {'text': 'Hello world'}
service.timeline().insert(body=timeline_item).execute()

در صورت موفقیت، کد پاسخ 201 Created را به همراه یک کپی کامل از آیتم ایجاد شده دریافت خواهید کرد. برای مثال قبلی، یک پاسخ موفقیت‌آمیز ممکن است به این شکل باشد:

HTTP خام

HTTP/1.1 201 Created
Date: Tue, 25 Sep 2012 23:30:11 GMT
Content-Type: application/json
Content-Length: 303

{
 "kind": "glass#timelineItem",
 "id": "1234567890",
 "selfLink": "https://www.googleapis.com/mirror/v1/timeline/1234567890",
 "created": "2012-09-25T23:28:43.192Z",
 "updated": "2012-09-25T23:28:43.192Z",
 "etag": "\"G5BI0RWvj-0jWdBrdWrPZV7xPKw/t25selcGS3uDEVT6FB09hAG-QQ\"",
 "text": "Hello world"
}

آیتم درج‌شده که در تایم‌لاین کاربر ظاهر می‌شود، به شکل زیر خواهد بود:

درج یک آیتم جدول زمانی با پیوست

یک تصویر به اندازه هزار کلمه ارزش دارد، که خیلی بیشتر از آن چیزی است که بتوانید در یک آیتم تایم‌لاین جا دهید. برای این منظور، می‌توانید تصاویر و ویدیو را نیز به یک آیتم تایم‌لاین پیوست کنید. در اینجا مثالی از نحوه درج یک آیتم تایم‌لاین با پیوست عکس آورده شده است:

HTTP خام

POST /upload/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": "A solar eclipse of Saturn. Earth is also in this photo. Can you find it?" }
--mymultipartboundary
Content-Type: image/jpeg
Content-Transfer-Encoding: binary

[binary image data]
--mymultipartboundary--

جاوا

TimelineItem timelineItem = new TimelineItem();
timelineItem.setText("Hello world");
InputStreamContent mediaContent = new InputStreamContent(contentType, attachment);
service.timeline().insert(timelineItem, mediaContent).execute();

پایتون

timeline_item = {'text': 'Hello world'}
media_body = MediaIoBaseUpload(
    io.BytesIO(attachment), mimetype=content_type, resumable=True)
service.timeline().insert(body=timeline_item, media_body=media_body).execute()

یک آیتم تایم‌لاین با تصویر پیوست شده، روی گلس چیزی شبیه به این است:

پیوست کردن ویدیو

اگر فایل‌های ویدیویی را به آیتم‌های تایم‌لاین خود پیوست می‌کنید، توصیه می‌کنیم به جای آپلود کل فایل به صورت یکجا، ویدیو را پخش کنید. API گوگل میرور از پخش زنده HTTP، دانلود پیشرفته و پروتکل پخش همزمان (RTSP) پشتیبانی می‌کند. RTSP اغلب توسط فایروال‌ها مسدود می‌شود، بنابراین در صورت امکان از گزینه‌های دیگر استفاده کنید.

برای پخش ویدئو، از آیتم منوی داخلی PLAY_VIDEO استفاده کنید و URL ویدئو را به عنوان payload آیتم منو مشخص کنید. برای اطلاعات بیشتر به بخش افزودن آیتم‌های منوی داخلی و فرمت‌های رسانه‌ای پشتیبانی شده مراجعه کنید.

صفحه بندی

شما می‌توانید آیتم‌های جدول زمانی را که در یک کارت جدول زمانی واحد جای نمی‌گیرند، اما باید به یک کارت مرتبط باشند، صفحه‌بندی کنید. آیتم‌های صفحه‌بندی‌شده همگی timeline.id یکسانی دارند و بنابراین مجموعه آیتم‌های منوی یکسانی دارند. وقتی کاربر روی یک آیتم جدول زمانی صفحه‌بندی‌شده ضربه می‌زند، یک آیتم منوی «ادامه مطلب» ظاهر می‌شود.

Glass به طور خودکار آیتم‌های جدول زمانی که text نمایش می‌دهند، صفحه‌بندی می‌کند. برای اینکه Glass به طور خودکار html را صفحه‌بندی کند، از تگ article با ویژگی کلاس آن که روی auto-paginate تنظیم شده است، مانند مثال زیر استفاده کنید:

<article class="auto-paginate">
 <h3>Very long list</h3>
 <ul>
   <li>First item</li>
   <li>Second item</li>
   <li>Third item</li>
   <li>Fourth item</li>
   <li>Fifth item</li>
   <li>Sixth item</li>
   <li>...</li>
 </ul>
<article>

برای صفحه‌بندی دستی، از تگ article برای محتوایی که می‌خواهید در هر کارت نمایش داده شود استفاده کنید. Glass محتوای هر تگ article را در یک کارت sub-timeline جداگانه نمایش می‌دهد. برای مثال، می‌توانید با استفاده از HTML زیر یک آیتم timeline صفحه‌بندی شده ایجاد کنید:

<article>
 <section>
   <p>First page</p>
 </section>
</article>

<article>
 <section>
   <p>Second page</p>
 </section>
</article>

<article>
 <section>
   <p>Third page</p>
 </section>
</article>

به طور پیش‌فرض، اولین کارت آیتم صفحه‌بندی‌شده‌ی جدول زمانی به عنوان کارت جلد نمایش داده می‌شود و هنگامی که کاربر آیتم منوی «ادامه مطلب» را انتخاب می‌کند، دوباره نمایش داده می‌شود. برای جلوگیری از نمایش مجدد کارت اول پس از ضربه زدن روی «ادامه مطلب» ، می‌توانید کلاس CSS cover-only برای اولین برچسب <article> مشخص کنید:

<article class="cover-only">
...

کلاس cover-only همچنین از آیتم‌های جدول زمانی با صفحه‌بندی خودکار پشتیبانی می‌کند:

<article class="auto-paginate cover-only">
...

بسته‌بندی

دسته‌بندی به شما امکان می‌دهد موارد مرتبط اما متمایز را با هم گروه‌بندی کنید، مانند پیام‌های جداگانه در یک رشته ایمیل. بسته‌ها دارای یک کارت جلد اصلی هستند که کاربر با ضربه زدن روی آن، یک جدول زمانی فرعی که شامل کارت‌های دیگر موجود در بسته است را نمایش می‌دهد. بسته‌ها با یک تاخوردگی گوشه‌ای در گوشه سمت راست بالای کارت جلد بسته، از کارت‌های جدول زمانی معمولی متمایز می‌شوند.

برای دسته‌بندی آیتم‌های جدول زمانی، آن‌ها را با مقدار یکسان برای bundleId ایجاد کنید. جدیدترین آیتم اضافه شده، کارت کاور (cover card) آن دسته است.

تصاویر زیر یک کارت جلد دسته‌ای را نشان می‌دهند که تای گوشه در گوشه بالا سمت راست قرار دارد و دو کارت دسته‌ای در زیر آن قرار دارند.

خواندن موارد جدول زمانی

سرویس شما می‌تواند به تمام آیتم‌های جدول زمانی که ایجاد کرده و تمام آیتم‌های جدول زمانی که با آن به اشتراک گذاشته شده‌اند، دسترسی داشته باشد. در اینجا نحوه فهرست کردن آیتم‌های جدول زمانی که برای سرویس شما قابل مشاهده هستند، آورده شده است.

HTTP خام

GET /mirror/v1/timeline HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer {auth token}

جاوا

TimelineItem timelineItem = new TimelineItem();
service.timeline().list().execute();

پایتون

service.timeline().list().execute()

شما می‌توانید از سایر عملیات REST برای دریافت ، به‌روزرسانی و حذف آیتم‌های جدول زمانی استفاده کنید.

دسترسی به پیوست‌ها

You can access attachments to a timeline item through an array property named attachments . You can then obtain the binary data of an attachment through the contentUrl property of the attachment or with the attachments endpoint .

HTTP خام

GET /mirror/v1/timeline/{itemId}/attachments/{attachmentId} HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer {auth token}

جاوا

TimelineItem item = service.timeline().get(itemId).execute();
String attachmentId = item.getAttachments().get(0).getId();
service.attachments().get(itemId, attachmentId).executeAsInputStream();

ایجاد آیتم‌های منو

آیتم‌های منو به کاربران اجازه می‌دهند اقداماتی را که مربوط به کارت جدول زمانی است درخواست کنند و در دو نوع ارائه می‌شوند: آیتم‌های منوی داخلی و آیتم‌های منوی سفارشی.

آیتم‌های منوی داخلی، دسترسی به قابلیت‌های ویژه ارائه شده توسط عینک گوگل، مانند خواندن کارت تایم‌لاین با صدای بلند، پیمایش به یک مکان، اشتراک‌گذاری تصویر یا پاسخ دادن به یک پیام را فراهم می‌کنند:

آیتم‌های منوی سفارشی به برنامه شما اجازه می‌دهند رفتاری را که مختص Glassware شماست، نمایش دهد و همچنین می‌توانید یک آیکون برای آیتم منو ارائه دهید تا با برند شما مطابقت داشته باشد.

شما می‌توانید با پر کردن menuItems array هنگام درج آیتم‌های منوی داخلی، آنها را به آیتم‌های جدول زمانی خود اضافه کنید. برای استفاده از یک آیتم منوی داخلی، فقط باید action هر menuItem را پر کنید.

HTTP خام

HTTP/1.1 201 Created
Date: Tue, 25 Sep 2012 23:30:11 GMT
Content-Type: application/json
Content-Length: 303

{
  "text": "Hello world",
  "menuItems": [
    {
      "action": "REPLY"
    }
  ]
}

تعریف آیتم‌های منوی سفارشی

اگر آیتم‌های منوی داخلی برای شما کار نمی‌کنند، می‌توانید با انجام موارد زیر هنگام درج یا به‌روزرسانی یک آیتم جدول زمانی، آیتم‌های منوی سفارشی را با اقدامات خودتان ایجاد کنید:

برای menuItem.action CUSTOM مشخص کنید.
یک menuItem.id مشخص کنید. وقتی کاربران روی آیتم منوی سفارشی ضربه می‌زنند، Glassware شما یک اعلان با menuItem.id پر شده دریافت می‌کند. این به شما امکان می‌دهد منبع اعلان را تعیین کنید.
برای افزودن iconUrl و displayName که روی Glass ظاهر می‌شوند، menuItem.values مشخص کنید. برای iconUrl به یک تصویر PNG با ابعاد ۵۰ در ۵۰ اشاره کنید که به رنگ سفید و پس‌زمینه شفاف باشد.
displayTime مشخص کنید. اگر displayTime مشخص نکنید، هر زمان که کاربران روی آیتم منوی سفارشی ضربه بزنند، آیتم خط زمانی به جلوی خط زمانی منتقل می‌شود.

HTTP خام

HTTP/1.1 201 Created
Date: Tue, 25 Sep 2012 23:30:11 GMT
Content-Type: application/json
Content-Length: 303

{
  "text": "Hello world",
  "displayTime": "2013-08-08T22:47:31-07:00",
  "menuItems": [
    {
      "action": "CUSTOM",
      "id": "complete"
      "values": [{
        "displayName": "Complete",
        "iconUrl": "http://example.com/icons/complete.png"
      }]
    }
  ]
}

به کاربران اجازه دهید کارت جدول زمانی شما را پین کنند

شما می‌توانید یک آیتم منو ایجاد کنید که به کاربران شما اجازه می‌دهد کارت جدول زمانی را پین کنند، که به طور دائم کارت جدول زمانی را در سمت چپ کارت ساعت اصلی نمایش می‌دهد. کاربران می‌توانند با استفاده از همان آیتم منو، کارت را نیز از پین خارج کنند.

آیتم منوی پین کردن یک آیتم منوی داخلی است، بنابراین تنها کاری که باید انجام دهید این است که action TOGGLE_PINNED را برای یک menuItem فراهم کنید.

HTTP خام

HTTP/1.1 201 Created
Date: Tue, 25 Sep 2012 23:30:11 GMT
Content-Type: application/json
Content-Length: 303

{
  "text": "You can pin or unpin this card.",
 "menuItems": [
    {
      "action": "TOGGLE_PINNED"
    }
  ...
 ]
}

اشتراک‌ها

API آینه‌ای به شما امکان می‌دهد در اعلان‌هایی که هنگام انجام اقدامات خاص توسط کاربر روی یک آیتم جدول زمانی یا به‌روزرسانی موقعیت مکانی کاربر ارسال می‌شوند، مشترک شوید. وقتی در یک اعلان مشترک می‌شوید، یک URL فراخوانی ارائه می‌دهید که اعلان را پردازش می‌کند.

دریافت اعلان‌ها

یک اعلان از Mirror API به عنوان یک درخواست POST به نقطه پایانی مشترک ارسال می‌شود که حاوی یک بدنه درخواست JSON است.

HTTP خام

{
  "collection": "timeline",
  "itemId": "3hidvm0xez6r8_dacdb3103b8b604_h8rpllg",
  "operation": "UPDATE",
  "userToken": "harold_penguin",
  "verifyToken": "random_hash_to_verify_referer",
  "userActions": [
    {
      "type": "<TYPE>",
      "payload": "<PAYLOAD>"
    }
  ]
}

جاوا

import com.google.api.client.json.JsonFactory;
import com.google.api.client.json.jackson.JacksonFactory;
import com.google.api.services.mirror.model.Notification;

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

public class MyClass {
  // ...

  /**
    * Parse a request body into a Notification object.
    *
    * @param requestBody The notification payload sent by the Mirror API.
    * @return Parsed notification payload if successful, {@code null} otherwise.
    */
  static Notification parseNotification(InputStream requestBody) {
    try {
      JsonFactory jsonFactory = new JacksonFactory();

      return jsonFactory.fromInputStream(requetBody, Notification.class);
    } catch (IOException e) {
      System.out.println("An error occurred: " + e);
      return null;
    }
  }

  // ...
}

پایتون

import json

def parse_notification(request_body):
  """Parse a request body into a notification dict.

  Params:
    request_body: The notification payload sent by the Mirror API as a string.
  Returns:
    Dict representing the notification payload.
  """
  return json.load(request_body)

اگر خطایی رخ نداده باشد، سرویس شما باید با کد وضعیت HTTP 200 OK به API پاسخ دهد. اگر سرویس شما با کد خطا پاسخ دهد، ممکن است Mirror API سعی کند اعلان را دوباره به سرویس شما ارسال کند.

انواع اعلان

رابط برنامه‌نویسی کاربردی (API) آینه (Mirror) برای رویدادهای مختلف، بسته‌ی اعلان (notification payload) متفاوتی ارسال می‌کند.

پاسخ

کاربر با استفاده از آیتم منوی REPLY که در داخل برنامه تعبیه شده است، به آیتم جدول زمانی شما پاسخ داده است:

{
  "collection": "timeline",
  "itemId": "3hidvm0xez6r8_dacdb3103b8b604_h8rpllg",
  "operation": "INSERT",
  "userToken": "harold_penguin",
  "verifyToken": "random_hash_to_verify_referer",
  "userActions": [
    {
      "type": "REPLY"
    }
  ]
}

ویژگی itemId روی ID آیتمی تنظیم می‌شود که شامل موارد زیر است:

ویژگی inReplyTo روی ID آیتم جدول زمانی که به آن پاسخ داده می‌شود، تنظیم می‌شود.
ویژگی text که برای رونویسی متن تنظیم شده است.
ویژگی recipients به creator آیتم جدول زمانی که در صورت وجود، به آن پاسخ داده می‌شود، تنظیم می‌شود.

مثال:

{
  "kind": "glass#timelineItem",
  "id": "3hidvm0xez6r8_dacdb3103b8b604_h8rpllg",
  "inReplyTo": "3236e5b0-b282-4e00-9d7b-6b80e2f47f3d",
  "text": "This is a text reply",
  "recipients": [
    {
      "id": "CREATOR_ID",
      "displayName": "CREATOR_DISPLAY_NAME",
      "imageUrls": [
        "CREATOR_IMAGE_URL"
      ]
    }
  ]
}

حذف

کاربر یک مورد از جدول زمانی را حذف کرده است:

{
  "collection": "timeline",
  "itemId": "3hidvm0xez6r8_dacdb3103b8b604_h8rpllg",
  "operation": "DELETE",
  "userToken": "harold_penguin",
  "verifyToken": "random_hash_to_verify_referer",
  "userActions": [
    {
      "type": "DELETE"
    }
  ]
}

ویژگی itemId برابر با شناسه (ID) آیتم حذف شده تنظیم شده است. آیتم دیگر شامل فراداده‌ای غیر از شناسه (ID) و ویژگی isDeleted نیست.

مورد منوی سفارشی انتخاب شده است

کاربر یک آیتم منوی سفارشی تنظیم شده توسط سرویس شما را انتخاب کرده است:

{
  "collection": "timeline",
  "itemId": "3hidvm0xez6r8_dacdb3103b8b604_h8rpllg",
  "operation": "UPDATE",
  "userToken": "harold_penguin",
  "userActions": [
    {
      "type": "CUSTOM",
      "payload": "PING"
    }
  ]
}

ویژگی itemId برابر با شناسه (ID) آیتم منویی است که کاربر انتخاب کرده است.

آرایه userActions شامل لیستی از اقدامات سفارشی است که کاربر روی این مورد انجام داده است. سرویس شما باید بر اساس آن اقدامات را مدیریت کند.

به‌روزرسانی مکان

یک مکان جدید برای کاربر فعلی در دسترس است:

{
  "collection": "locations",
  "itemId": "latest",
  "operation": "UPDATE",
  "userToken": "harold_penguin",
  "verifyToken": "random_hash_to_verify_referer"
}

وقتی Glassware شما به‌روزرسانی موقعیت مکانی دریافت می‌کند، درخواستی را به نقطه پایانی glass.locations.get ارسال کنید تا آخرین موقعیت مکانی شناخته شده را بازیابی کنید. Glassware شما هر ده دقیقه به‌روزرسانی‌های موقعیت مکانی را دریافت می‌کند.

فرمان صوتی

کاربر شما یک فرمان صوتی را فعال کرده است، برای مثال: «باشه گلس، یادداشت بردار، کت استریم، تولد چیپوتله فرداست». اعلان زیر به گلس ور شما ارسال می‌شود:

{
  "collection": "timeline",
  "operation": "INSERT",
  "userToken": "chipotle's_owner",
  "verifyToken": "mew mew mew",
  "itemId": "<ITEM_ID>",
  "userActions": [
    {“type”: "LAUNCH"}
  ]
}

این اعلان با مقدار LAUNCH در ویژگی userActions از سایر اعلان‌ها متمایز می‌شود.

سپس می‌توانید از مقدار itemId برای دریافت آیتم جدول زمانی استفاده کنید:

{
  "id": "<ITEM_ID>",
  "text": "Chipotle's birthday is tomorrow",
  "recipients": [
    {"id": "CAT_STREAM"}
  ]
}

ویژگی recipients شامل id مخاطبی است که نشان دهنده‌ی فرمان صوتی مورد استفاده است.

کارت های استاتیک با مجموعه‌ها، منظم بمانید ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.

چگونه کار می‌کنند

چه زمانی از آنها استفاده کنیم

وارد کردن کارت‌های استاتیک

HTTP خام

جاوا

پایتون

HTTP خام

درج یک آیتم جدول زمانی با پیوست

HTTP خام

جاوا

پایتون

پیوست کردن ویدیو

صفحه بندی

بسته‌بندی

خواندن موارد جدول زمانی

HTTP خام

جاوا

پایتون

دسترسی به پیوست‌ها

HTTP خام

جاوا

ایجاد آیتم‌های منو

افزودن آیتم‌های منوی داخلی

HTTP خام

تعریف آیتم‌های منوی سفارشی

HTTP خام

به کاربران اجازه دهید کارت جدول زمانی شما را پین کنند

HTTP خام

اشتراک‌ها

دریافت اعلان‌ها

HTTP خام

جاوا

پایتون

انواع اعلان

پاسخ

حذف

مورد منوی سفارشی انتخاب شده است

به‌روزرسانی مکان

فرمان صوتی

کارت های استاتیک