Google Calendar API使用心得分享|IT168 技术开发

quasiceo 2013-10-26

展开全文

Google Calendar API使用心得分享

责任编辑：cynthia作者：ITPUB论坛 2008-07-14

文本Tag： Google

【IT168 技术文档】本院联合行事历系利用Google Calendar（GC）所建置的，40多个所（处）中心先分别使用GC建立各单位的行事历，再由计算中心所撰写的PHP程序，逐日从各单位的行事历中撷取新增及异动事件，汇入联合行事历。这是我们接触GC API（应用程序接口）的缘由。

Google API说明网页概述

使用GC API之前，要先阅读说明文件。Google的API说明文件的风格与众不同，不全然以阶层式结构呈现，有时候倒像是蜘蛛网般交错相连。对熟悉这种风格的人而言，或许很容易快速进入想读取的网页，但是对初学者而言，却往往苦于不能对同一主题下的全部内容一览无遗。因此有必要先介绍如何阅读GC API的说明文件。

首先进到网站 http://code.google.com/，点选画面左方的「APIs & Developer Tools」进入浏览页面。点选「Products（Featured）」视框里的「Google Calendar APIs and Tools」选项，右边「Details」视框里的各个链接都可以参考。自其中的「Home」选项连入后，右侧有3个链接，概述如下：

1. 先循着「Gdata protocol」大略看看，以便对Gdata有个大概了解。

2. 循着「Developer’s Guide」进入，读过该页之后，再点选左边字段里的「PHP」，并从此页开头的段落找到「Zend Framework」链接，下载新版的范例程序。

3. 「Reference Guide」这一页说明API的设定及常用参数，对使用者相当重要。左边的「Authentication」提及两种登入方式：

　　(1)「Authentication for Installed Applications」说明安装在PC或手机里的应用程序，如何使用特定calendar的calendar ID读取其公开的事件。请参阅http://code.google.com/apis/accounts/AuthForInstalledApps.html（范例详见下文）。

　　(2)「Authentication for Web Applications」解说如何利用Google的验证代理服务器，以URL与使用者互动，完成身份验证，简称为AuthSub。可回到「Google Calendar APIs and Tools」页面，从右侧「Articles & Tutorials」连入后，参考第3篇「Using cURL to interact with Google data services」，了解如何藉由cURL来使用AuthSub服务。也可参阅http://code.google.com/apis/accounts/AuthForWebApps.html。

范例程序

　对登入机制与Gdata有基本概念之后，即可进一步参考Zend公司所撰写的范例程序。Zend是一家专门发展PHP软件的公司，Zend Framework则是该公司制作的软件开发框架。

　下列范例即是出自该框架的参考文件。范例程序必须配合php5.0以上版本。

　自前述「Developer’s Guide」网页找到php页面的链接http://code.google.com/apis/calendar/developers_guide_php.html，点选后进入该页面。点选网页中间的“Zend Google Data Client Library”找到下载页面http://framework./download/gdata。点选Docs→APIs可以查询函式http://framework./apidoc/core/。下载新版档案后主要参考的档案为ZendGdata-1.0.3\demos\Zend\Gdata\Calendar.php。

　使用GC API，首先是要注意Google对某些动作有所限制，例如开启新日历，一开始被限制只能开启十几个日历，必须间隔一段时间之后才会逐渐放宽日历数的上限。此外，读取某一本日历的事件时，不管是设定时间范围或是想要抓取整本日历的事件，都有一次只能抓取25笔的限制，因此若有特殊应用需要较大量存取，动作之前可能得先行测试。

　分享一些GC API使用上的小心得，在outputCalendarByDate这个function及其它需要输入日期的地方，可以使用2000-01-01或是2000-01-01T00:00:00。如果需要调整时差的话，可在后方加上“+08:00”（此为台北时差）。若是只写日期而不写详细时间，在需要进行时间点的判断时会以当日早上八点为判断点。

　另一个跟outputCalendarByDate有关且比较特殊的地方是，在判断要不要输出该笔事件时是以下列参数为准：

$query->setStartMin($startDate);
$query->setStartMax($endDate);

　若某个事件与这两个时间区间有交集就判定为输出。当这两个参数只写日期时，将如上述以该日早上八点为准，因此要想输出某一天的事件，保险一点还是把时分秒也写进去，否则会发生许多输出不如预期的情况。

　有关event obj的分析，利用print_r()将一个event展开，可看见全部变量，下列为常见的日历中文字段名称与对应的变量位置：

事项：$event->title->text
时间(array)：$event->when
　起始时间：$event->when->startTime
　结束时间：$event->when->endTime
地点(array)：$event->where->valueString
详情：$event->content->text

　若是循环事件则使用$event->recurrence->text记录讯息，这是一串较长较复杂的string，跟上述的时间格式不同。

　每个事件都赋予event ID，对应的变量为$event->id->text，不过显示出来的是一串网址，其中含有此事件所属的日历ID，最后一个“/”之后才是此事件的ID。如果要在qurey中设定单一事件则可用“$query->setEvent($eventId);”，需注意不可与setStartMin/setStartMax共享。

　Zend所提供的code必须使用账号密码登入后才能使用，若是只要读取该日历，可删掉“$gdataCal = new Zend_Gdata_Calendar($client);”里的$client，然后把想开启的calendar ID填入“$query->setUser($calID);”，注意此calendar必须是已经设定成公开日历。

　写入事件时也得注意一些事情，某些字段的内容是由GC自动产生的，即使local端修改了下载的事件，但存回Google database时依然会被改写回去。能被修改的字段主要是那些可见的字段，而诸如建立者或拥有者这类字段则是无法任意更动的。

　复制事件时，可以视需求先开一笔全新事件只复制必要的几个字段，或是利用“$targetEvent = $targetGdataCal->insertEvent($sourceEvent);”直接复制整笔事件到目标日历中。但使用上述指令时要注意这么做会连同送出邀请的字段都复制下来，当初我们就犯了这项错误，结果受邀者（也就是这事件的建立者）也将日历的受邀请时自动加入此事件做了勾选（这是默认值），然后就这样凑巧来往，将一笔事件复制了上百份，对双方都造成不小的困扰。

范例程序说明

　下文的小程序修改自上述的Calendar.php档，原本是利用Client Login的登入方法，需要使用者账号密码，可以对该日历进行各种增、删、修、查的动作。下列主要示范如何修改为只需要Calendar ID即可以只读方式开启日历。

　程序功能：开启一本公开日历，以只读方式开启并列出指定范围内的25笔事件，每笔事件皆列出起始结束时间、地点、详情、最后修改时间及事件ID。

<?php
//在此设定想看的日历ID，下列范例是英文版的台湾节日行事历 
$calID = 'taiwan__en@holiday.calendar.google.com';
//设定library路径，请记得根据自己计算机状况做修改 
ini_set('include_path', ini_get('include_path') . ':/home/user/public_html/ZendGdata-1.0.2/library');
require_once 'Zend/Loader.php';
Zend_Loader::loadClass('Zend_Gdata');
Zend_Loader::loadClass('Zend_Gdata_AuthSub');
Zend_Loader::loadClass('Zend_Gdata_ClientLogin');
Zend_Loader::loadClass('Zend_Gdata_Calendar');
$gdataCal = new Zend_Gdata_Calendar();
$query = $gdataCal->newEventQuery();
//原始范例中setUser给的参数是default 这样的话是开启范例中$client的主日历
//但由网页说明中我们可知用$cal可以开启我们指定的任何一本日历
$query->setUser($calID);
$query->setVisibility('public');
$query->setProjection('full');
$query->setOrderby('starttime');
$query->setStartMin('2008-02-01');
$query->setStartMax('2008-02-29');
$eventFeed = $gdataCal->getCalendarEventFeed($query);
foreach($eventFeed as $event){//在同一个query中能显示的事件数量上限为25笔
      foreach ($event->when as $when) {
echo "startTime:" . $when->startTime . "\n";//事件起始时间
              echo "endTime:" . $when->endTime . "\n";//事件结束时间
      }
echo "recurrence:" . $event->recurrence->text . "\n";//循环事件才有内容
      foreach ($event->where as $where) {
echo "where:" . $where->valueString . "\n";//地点
      }
echo "content:" . $event->content->text . "\n";//详情
      echo "updated:" . $event->updated->text . "\n";//最后修改时间
      echo "title:" . $event->title->text . "\n";//事项
      echo "id:" . $event->id->text . "\n\n";//事件id(平时看不到)
}
?>