google Glass API 开发指南(google翻译附英文).doc

开发指南时间轴（Timeline）你的用户的时间轴被分为时间表项目。您可以使用API接入和管理项目通过HTTP的REST操作时间表。（Your users timeline is divided up into timeline items. You can use the API to insert and manage timeline items with REST operations over HTTP.）注意：时间轴的产品最后七天在用户的玻璃和30天镜象API。（Note:Timeline items last for seven days on a users Glass and 30 days in the Mirror API.）1. 插入一个简单的时间轴项目1. 阅读时间表项目2. 插入一个时间表与媒体项目3. 访问附件4. 捆绑卡2. 用户交互菜单项1. 使用内置的菜单项2. 定义自定义菜单项3. 允许用户固定时间表卡插入一个简单的时间轴项目要插入一个时间表项，POST一个JSON表示的时间表项目的REST端点。大多数字段都是可选的。最简单的形式，一个时间表项目只包含一个简短的文字消息。这是一个简单的时间表项目如何被插入。（Toinserta timeline item, POST aJSON representation of a timeline itemto the REST endpoint.Most of the fields are optional. In simplest form, a timeline item contains only a short text message. This is how a simple timeline item is inserted.）原始HTTP的Java的POST /mirror/v1/timeline HTTP/1.1Host: Authorization: Bearer auth tokenContent-Type: application/jsonContent-Length: 26 text: Hello world Java的TimelineItem timelineItem = new TimelineItem();timelineItem.setText(Hello world);service.timeline().insert(timelineItem).execute();在成功时，服务器会返回一个201响应代码创建创建项目的完整副本。对于上面的例子，可能看起来像一个成功的响应：（On success, the server will return a 201 Created response code with a full copy of the created item. For the example above, a successful response might look like:）原始的HTTPHTTP/1.1 201 CreatedDate: Tue, 25 Sep 2012 23:30:11 GMTContent-Type: application/jsonContent-Length: 303kind: glass#timelineItem,id: 1234567890,selfLink: /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插入项目，将出现在用户的时间轴看起来像这样：（The inserted item that would appear in the users timeline looks like this:）阅读时间表项目（Reading timeline items）你的服务可以访问所有的时间表，它创建项目，以及所有共享项目时间表。以下是如何为您服务是可见的项目列出时间表。（Your service can access all timeline items that it created, and all timeline items that were shared with it. Heres how tolistthe timeline items that are visible to your service.）原始HTTP的GET /mirror/v1/timeline HTTP/1.1Host: Authorization: Bearer auth tokenJava的Timeline Item timelineItem = new TimelineItem();service.timeline().list().execute();您可以使用其他REST操作，更新和删除时间轴项目。（You can use other REST operations toget,updateanddeletetimeline items.）插入一个时间表与媒体项目（Inserting a timeline item with media）一张图片胜过千言万语，这是很多比你更可以融入一个时间表的项目。为此，您还可以包括图像和视频作为附件的时间表项目。（A picture is worth a thousand words, which is a lot more than you can fit into a timeline item. To this end, you can also include images and video as attachments to a timeline item.）在一个较低的水平，使用HTTP多附件上传。谷歌的API客户端库，使得这个易于使用的媒体上传。（At a low level, attachments are uploaded usingHTTP Multipart. Google APIs client libraries make this easy using media upload.）以下是如何插入一个时间表带有附件的项目。（Heres how to insert a timeline item with an attachment）原始HTTP的Java的PythonPOST /mirror/v1/timeline HTTP/1.1Host: Authorization: Bearer auth tokenContent-Type: multipart/related; boundary=mymultipartboundaryContent-Length: length-mymultipartboundaryContent-Type: application/json; charset=UTF-8 text: A solar eclipse of Saturn. Earth is also in this photo. Can you find it? -mymultipartboundaryContent-Type: image/jpegContent-Transfer-Encoding: binarybinary image data-mymultipartboundary-TimelineItem timelineItem = new TimelineItem();timelineItem.setText(Hello world);InputStreamContent mediaContent = new InputStreamContent(contentType, attachment);service.timeline().insert(timelineItem, mediaContent).execute();时间轴项附加图像的玻璃装置上，看起来像这样：（A timeline item with an attached image looks something like this on the glass device:）访问附件（Accessing attachments）时间轴带有附件的项目使他们在一个数组属性，恰当地命名为附件。附件的二进制数据，可以获取从URL中发现将contentUrl属性或通过附件的端点。（Timeline items with attachments expose them in an array property aptly namedattachments. The binary data for the attachment can be fetched from the URL found in thecontentUrlproperty or via theattachments endpoint.）注：内容保护的OAuth 2.0，就像其他调用的API端点。谷歌API客户端库提供访问附件使用媒体下载功能的二进制内容。（Note:The content is protected by OAuth 2.0, just like other calls to the API endpoints. Google API client libraries provide access to the binary content of attachments using the media download feature.）原料HTTP的GET /mirror/v1/timeline/itemId/attachments/attachmentId HTTP/1.1Host: Authorization: Bearer auth tokenJAVA的TimelineItem item = service.timeline().get(itemId).execute();String attachmentId = item.getAttachments().get(0).getId();service.attachments().get(itemId, attachmentId).executeAsInputStream();捆绑卡（Bundling cards）捆绑让您结合成捆的许多相关的卡。束杰出的页面卷曲正常时间轴卡的右上角。（Bundling allows you to combine many related cards into a bundle. Bundles are distinguished from normal timeline cards by the page curl in the upper right corner.）有两种方式捆绑内容：寻呼和线程。寻呼是通过指定值在timelineItem.htmlPages 属性。如果使用分页捆绑，元素都有着相同的timelineId，因此有相同的一组菜单项。这是非常有用的内容传送至玻璃不适合到一个单一的卡。（There are two ways to bundle content: paging and threading. Paging is done by specifying values in thetimelineItem.htmlPagesproperty. If you use paging bundles, elements all share the sametimelineIdand hence have the same set of menu items. This is useful for sending content to Glass that does not fit onto a single card.）线程是通过与一个共同的bundleId的许多时间表卡关联。要使用此技术，创造相同的值bundleId许多时间表项目。最近新增的项目将被盖卡。这种技术更可用于相关项目，如电子邮件线程。（Threading is done by associating many timeline cards with a commonbundleId. To use this technique, create many timeline items with the same value forbundleId. The most recently added item will be the cover card. This technique is more useful for related items like email threads.）用户交互菜单项（User interaction with menu items）提供的内容仅仅是故事的一半。最有趣的服务用户所采取的行动作出回应。用户可以通过选择菜单项时间表卡。（Delivering content is only half of the story. Most interesting services also respond to actions taken by the user. Users can act on timeline cards by selecting menu items.）菜单项有两种形式：内置菜单项和自定义菜单项。内置菜单项提供玻璃设备等硬件大声阅读的时间表卡所提供的特殊功能，导航到一个位置或者共享图像。（Menu items come in two flavors: built-in menu items and custom menu items. Built-in menu items provide access to special functionalities provided by the glass device hardware such as reading a timeline card aloud, navigating to a location or sharing an image.）自定义菜单项可以让您的应用程序为您服务是特定的行为暴露，并提供了一个菜单图标匹配。（Custom menu items allow your application to expose behavior that is specific to your service and provide a menu icon to match）使用内置的菜单项（Using built-in menu items）您可以添加内置菜单项，通过填充菜单项数组，当你插入你的时间表项目。要使用一个内置的菜单项，你只需要填入每个菜单项的动作。（You can add built-in menu items to your timeline items by populating themenuItems arraywhen you insert them. To use a built-in menu item, you only need to populate theactionof eachmenuItem.）原始的HTTPHTTP/1.1 201 CreatedDate: Tue, 25 Sep 2012 23:30:11 GMTContent-Type: application/jsonContent-Length: 303 text: Hello world, menuItems: action: REPLY 注：参考文档包含可用的内建动作的详细说明。（Note:Thereference documentationcontains a detailed description of the available built in actions.）定义自定义菜单项（Defining custom menu items）内置动作可能不会永远是不够的。许多服务都需要暴露自己的特定的菜单项。这是自定义操作来发挥作用。（Built-in actions may not always be enough. Many services need to expose their own specific menu items. This is where custom actions come into play.）创建一个自定义菜单项通过指定一个menuItem.action习惯和menuItem.id的。当用户触发一个自定义菜单项，通知发送给服务人口与menuItem.id。这可以让你确定源的通知。(Create a custom menu item by specifying amenuItem.actionofCUSTOMand amenuItem.id. When your user triggers one of your custom menu items, anotificationis sent to your service with themenuItem.idpopulated. This allows you to determine the source of the notification.)您还必须填充menuItem.menuValue的指定iconUrl和显示名称将出现在玻璃设备。(You must also populatemenuItem.menuValueto specify aniconUrlanddisplayNamethat will appear on the glass device.)原始的HTTPHTTP/1.1 201 CreatedDate: Tue, 25 Sep 2012 23:30:11 GMTContent-Type: application/jsonContent-Length: 303 text: Hello world, menuItems: action: CUSTOM, id: complete values: displayName: Complete, iconUrl: /icons/complete.png 注：为了获得最佳效果，请使用50像素的正方形透明背景的PNG图标图像。(Note:For best results, use a PNG icon image that is 50 pixels square with a transparent background.)允许用户固定时间表卡(Allowing users to pin your timeline card)您可以创建一个菜单项，可以让您的用户针时间表卡，它将永久显示在时间轴的卡主时钟卡的左侧。用户可以取消固定卡，通过使用相同的菜单项。(You can create a menu item that lets your users pin the timeline card, which permanently displays the timeline card to the left of the main clock card. Users can unpin the card as well, by using the same menu item)钢钉菜单项是一个内置在菜单项，因此，所有你需要做的是提供一个菜单项TOGGLE_PINNED行动。(The pinning menu item is a built-in menu item, so all you need to do is provide theTOGGLE_PINNEDactionfor amenuItem.)原始的HTTPHTTP/1.1 201 CreatedDate: Tue, 25 Sep 2012 23:30:11 GMTContent-Type: application/jsonContent-Length: 303 text: You can pin or unpin this card.,menuItems: action: TOGGLE_PINNED .订阅(Subscriptions)镜API允许你订阅，当用户需要发送一个时间轴项目的具体行动，或用户位置时，已经更新的通知。(The Mirror API allows you tosubscribe to notificationsthat are sent when the user takes specific actions on aTimeline Itemor when the user location has been updated.)1. 接收通知2. 通知类型1. 共享图片2. 回复3. 删除4. 选择自定义菜单项5. 位置更新接收通知(Receiving notifications)从镜像API发送一个POST请求包含一个JSON请求主体的认购端点的通知。(A notification from the Mirror API is sent as aPOSTrequest to the subscribed endpoint containing aJSONrequest body.)原始HTTP的 collection: timeline, itemId: 3hidvm0xez6r8_dacdb3103b8b604_h8rpllg, operation: UPDATE, userToken: harold_penguin, verifyToken: random_hash_to_verify_referer, userActions: type: , payload: Java的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; / .你的服务必须回应一个200 OKHTTP状态代码，如果没有发生错误的API。如果您的服务响应错误代码，镜像API可能会尝试重新发送该通知为您服务。(Your service must respond to the API with a200 OKHTTP status code if no error occurred. If your service responds with an error code, the Mirror API might try to resend the notification to your service.)注：连接超时10秒后。如果需要一个漫长的过程，马上做出反应，并在另一个线程中做的过程。(Note:The connection will time out after 10 seconds. If a long process is required, respond right away and do the process in another thread.)通知类型(Notification types)镜API发送一个不同的有效载荷为不同的事件通知。(The Mirror API sends a different notification payload for different events.)共享图片(Shared picture)用户已经分享了一张图片与您的服务。(The user has shared a picture with your service.) collection: timeline, itemId: 3hidvm0xez6r8_dacdb3103b8b604_h8rpllg, operation: UPDATE, userToken: harold_penguin, verifyToken: random_hash_to_verify_referer, userActions: type: SHARE ITEMID属性设置该项目包含的照片作为附件的ID：(TheitemIdattribute is set to theIDof the item containing the photo as an attachment:) id: 3hidvm0xez6r8_dacdb3103b8b604_h8rpllg, attachments: contentType: image/jpeg, id: , contentUrl: /mirror/v1/attachments/3hidvm0xez6r8_dacdb3103b8b604_h8rpllg/ , recipients: kind: glass#contact, source: api:, id: , displayName: , imageUrls: 注：与联系人共享内容的更多信息，请参阅联系。(Note:SeeContactsfor more information about sharing content with contacts.)回复(Reply)用户已经回答了你的时间表项目使用内置的回复菜单项：(The user has replied to your timeline item using the built-inREPLYmenu item:) collection: timeline, itemId: 3hidvm0xez6r8_dacdb3103b8b604_h8rpllg, operation: INSERT, userToken: harold_penguin, verifyToken: random_hash_to_verify_referer, userActions: type: REPLY ITEMID属性设置该项目包含的ID： inReplyTo属性设置为ID的时间轴项目，它是一个答复。 文本属性设置文本transcribtion的。 附件的属性设置到Web的音频播放器和语音记录的音频文件。(TheitemIdattribute is set to theIDof the item containing: inReplyToattribute set to theIDof the timeline item it is a reply to. textattribute set to the text transcribtion. attachmentsattribute set to the web audio player and the audio file of the voice recording.)例如： kind: glass#timelineItem, id: 3hidvm0xez6r8_dacdb3103b8b604_h8rpllg, inReplyTo: 3236e5b0-b282-4e00-9d7b-6b80e2f47f3d, text: This is a text reply, attachments: contentType: text/vnd.google.audio-player-url, contentUrl: , contentType: text/vnd.google.audio-download-url, contentUrl: 删除该用户已删除项目的时间表：(The user has deleted a timeline item:) collection: timeline, itemId: 3hidvm0xez6r8_dacdb3103b8b604_h8rpllg, operation: DELETE, userToken: harold_penguin, verifyToken: random_hash_to_verify_referer, userActions: type: DELETE ITEMID属性设置的ID删除项。资料不再包含元数据以外的ID和isDeleted财产的。(TheitemIdattribute is set to the ID of the deleted item. The item no longer contains metadata other than its ID and theisDeletedproperty.)注意：如果用户删除一个项目从他们的时间表，建议您删除这些内容从你的系统太。(Note:If the user deletes an item from their timeline, its recommended that you delete this content from your systems too.)选择自定义菜单项(Custom menu item selected)用户选择了一个自定义菜单项设置由您的服务：(The user has selected acustom menu itemset by your service:) collection: timeline, itemId: 3hidvm0xez6r8_dacdb3103b8b604_h8rpllg, operation: UPDATE, userToken: harold_penguin, userActions: type: CUSTOM, payload: PING 的ITEMID属性被设置为用户选择的菜单项的ID。(TheitemIdattribute is set to the ID of the menu item that the user selected.)的userActions数组包含了这个项目的用户自定义操作的列表。您的服务应如何处理这些相应的行动。(TheuserActionsarray contains the list of custom actions that the user took on this item. Your service should handle those actions accordingly.)位置更新(Location update)为当前用户提供一个新的位置是：(A new location is available for the current user:) collection: locations, itemId: latest, operation: UPDATE, userToken: harold_penguin, verifyToken: random_hash_to_verify_referer当你的玻璃器皿接收位置更新，发送一个请求到的glass.locations.get端点检索最新的已知位置。你的玻璃器皿接收位置，每10分钟更新。(When your Glassware receives a location update, send a request to theglass.locations.getendpoint to retrieve the latest known location. Your Glassware receives location updates every ten minutes.)注：正在位置信息需要/auth/glass.location的范围。(Note:Retrievinglocationinformationrequiresthe/auth/glass.locationscope.)位置(Location)您可以使用镜像API观察用户的位置在时间轴项目，直接要求他们最后已知位置，并订阅周期性位置更新。您也可以提供预渲染的时间表卡给镜像API坐标绘制的地图图像。(You can use the Mirror API to observe the users location in timeline items, request theirlast known locationdirectly, and subscribe to periodic location updates. You can also deliver pre-rendered map images in timeline cards by giving the Mirror API the coordinates to draw.)注：检索用户的位置，需要额外/auth/glass.location范围。(Note:Retrieving users location requires the additional/auth/glass.locationscope.)检索最新的已知位置(Retrieving the latest known location)要检索最新的已知位置为当前用户，发送一个GET请求发送到REST端点：(Toretrievethe latest known location for the current user, send aGETrequest to the REST endpoint:)原始的HTTPGET /mirror/v1/locations/ HTTP/1.1Authorization: Bearer auth token订阅的位置更新(Subscribing to location updates)订阅时间表更新，您可以订阅订阅地点集合地点的更新。(Similar tosubscribing to timeline updates, you can subscribe to location updates by subscribing to thelocationscollection.)原始的HTTPPOST /mirror/v1/subscriptions HTTP/1.1Authorization: Bearer auth tokenContent-Type: application/jsonContent-Length: length collection: locations, userToken: harold_penguin, verifyToken: random_hash_to_verify_referer, callbackUrl: /notify/callback注：在这个时候，地点通知每隔10分钟发送。(Note:At this time, location notifications are sent every 10 minutes.)在时间轴卡的渲染图(Rendering maps on timeline cards)谷歌镜API可以使你和覆盖标记和线条图，以示重要场所和路径。使用玻璃:/ /地图URI请求地图。下面是一个例子：(The Google Mirror API can render maps for you and overlay markers and lines to signify important places and paths. Use theglass:/mapURI to request a map. Heres an example:)注：请务必指定的宽度和高度的图像以及的标签。这可以防止回流被渲染的地图图像。这里是一个所需的参数的描述：(Note:Always specify the width and height of the image in thetag as w