documentation/manual/ja/module_specs/Zend_Gdata_Calendar.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <!-- EN-Revision: 20779 -->
   4 <sect1 id="zend.gdata.calendar">
   5     <title>Google Calendar の使用法</title>
   6     <para>
   7         <classname>Zend_Gdata_Calendar</classname>
   8         クラスを使うと、Google Calendar サービスで
   9         イベントの閲覧や作成、更新、削除ができるようになります。
  10     </para>
  11     <para>
  12         Google Calendar <acronym>API</acronym> についての詳細な情報は
  13         <ulink url="http://code.google.com/apis/calendar/overview.html">http://code.google.com/apis/calendar/overview.html</ulink>
  14         を参照ください。
  15     </para>
  16     <sect2 id="zend.gdata.calendar.connecting">
  17         <title>Calendar サービスへの接続</title>
  18         <para>
  19             Google Calendar <acronym>API</acronym> は、その他の GData <acronym>API</acronym> と同様に
  20             Atom Publishing Protocol (APP) を使用しています。これは、<acronym>XML</acronym>
  21             ベースのフォーマットでウェブのリソースを管理するための仕組みです。
  22             クライアントと Google Calendar サーバとの間のやり取りは
  23             <acronym>HTTP</acronym> で行われ、認証済みの接続と未認証の接続の両方が利用できます。
  24         </para>
  25         <para>
  26             何らかのトランザクションが発生する際には、
  27             必ず接続を確立する必要があります。
  28             カレンダーサーバとの接続は、まず <acronym>HTTP</acronym> クライアントを作成して
  29             <classname>Zend_Gdata_Calendar</classname>
  30             サービスのインスタンスをそこにバインドするという手順で行います。
  31         </para>
  32         <sect3 id="zend.gdata.calendar.connecting.authentication">
  33             <title>認証</title>
  34             <para>
  35                 Google Calendar <acronym>API</acronym> を使用すると、公開カレンダーだけでなく
  36                 プライベートカレンダーのフィードにもアクセスできます。
  37                 公開フィードには認証は不要ですが、
  38                 認証しない場合は読み込み専用となり、機能が制限されます。
  39                 プライベートフィードでは完全な機能が使用できますが、
  40                 カレンダーサーバとの認証が必要になります。
  41                 Google Calendar がサポートしている認証方式は、次の 3 通りです。
  42             </para>
  43             <itemizedlist>
  44                 <listitem>
  45                     <para>
  46                         <firstterm>ClientAuth</firstterm>
  47                         は、カレンダーサーバとの間で直接
  48                         ユーザ名/パスワード
  49                         による認証を行います。この方式では
  50                         ユーザ自身がアプリケーションにパスワードを教える必要があるので、
  51                         これは他の方式が使えない場合にのみ使用するようにしましょう。
  52                     </para>
  53                 </listitem>
  54                 <listitem>
  55                     <para>
  56                         <firstterm>AuthSub</firstterm>
  57                         は、Gooble のプロキシサーバを経由してカレンダーサーバとの認証を行ないます。
  58                         これは ClientAuth と同じくらい便利に使用でき、
  59                         セキュリティリスクもありません。
  60                         ウェブベースのアプリケーションでは、
  61                         これは最適な選択肢となります。
  62                     </para>
  63                 </listitem>
  64                 <listitem>
  65                     <para>
  66                         <firstterm>MagicCookie</firstterm>
  67                         は、Google Calendar インターフェイス内の
  68                         半ランダムな <acronym>URL</acronym> にもとづいた認証を行なう方法です。
  69                         この方法は、実装するのが一番簡単です。しかし、
  70                         ユーザ自身が安全な <acronym>URL</acronym> を事前に取得しないと認証できません
  71                         またカレンダーリストにはアクセスできず、
  72                         アクセスは読み込み専用に制限されます。
  73                     </para>
  74                 </listitem>
  75             </itemizedlist>
  76             <para>
  77                 <classname>Zend_Gdata</classname> ライブラリは、
  78                 これらのすべての方式に対応しています。
  79                 これ以降の説明は、認証方式については理解しており
  80                 適切な認証方式で接続できるようになっていることを前提として進めていきます。
  81                 詳細な情報は、このマニュアルの
  82                 <link linkend="zend.gdata.introduction.authentication">認証に関するセクション</link>
  83                 か、あるいは
  84                 <ulink url="http://code.google.com/apis/gdata/auth.html">Google Data <acronym>API</acronym> Developer's Guide
  85                 の Authentication Overview</ulink>
  86                 を参照ください。
  87             </para>
  88         </sect3>
  89         <sect3 id="zend.gdata.calendar.connecting.service">
  90             <title>サービスのインスタンスの作成</title>
  91             <para>
  92                 Google Calendar を使用するためのクラスとして、このライブラリでは
  93                 <classname>Zend_Gdata_Calendar</classname> を用意しています。
  94                 このクラスは Google Data や Atom Publishing Protocol
  95                 モデルへの共通インターフェイスを提供し、
  96                 カレンダーサーバとのリクエストのやりとりを支援します。
  97             </para>
  98             <para>
  99                 使用する認証方式を決めたら、次に
 100                 <classname>Zend_Gdata_Calendar</classname> のインスタンスを作成します。
 101                 このクラスのコンストラクタには、引数として
 102                 <classname>Zend_Http_Client</classname> のインスタンスを渡します。
 103                 これは、AuthSub 認証および ClientAuth 認証へのインターフェイスを提供します。
 104                 これらの認証を使用する場合には、認証済みの <acronym>HTTP</acronym> クライアントが必要です。
 105                 引数を省略した場合は、未認証の
 106                 <classname>Zend_Http_Client</classname>
 107                 のインスタンスを自動的に作成して使用します。
 108             </para>
 109             <para>
 110                 以下の例は、ClientAuth 認証を使用して Calendar サービスを作成するものです。
 111             </para>
 112             <programlisting language="php"><![CDATA[
 113 // ClientAuth 認証用のパラメータ
 114 $service = Zend_Gdata_Calendar::AUTH_SERVICE_NAME;
 115 $user = "sample.user@gmail.com";
 116 $pass = "pa$$w0rd";
 117
 118 // 認証済みの HTTP クライアントを作成します
 119 $client = Zend_Gdata_ClientLogin::getHttpClient($user, $pass, $service);
 120
 121 // Calendar サービスのインスタンスを作成します
 122 $service = new Zend_Gdata_Calendar($client);
 123 ]]></programlisting>
 124             <para>
 125                 AuthSub を使用する Calendar サービスを作成するのもほぼ同様ですが、
 126                 少々長めになります。
 127             </para>
 128             <programlisting language="php"><![CDATA[
 129 /*
 130  * 現在の URL を取得し、AuthSub サーバに
 131  * 認証後のリダイレクト先を伝えられるようにします
 132  */
 133 function getCurrentUrl()
 134 {
 135     global $_SERVER;
 136
 137     // php_self をフィルタリングし、セキュリティを確保します
 138     $php_request_uri =
 139         htmlentities(substr($_SERVER['REQUEST_URI'],
 140                             0,
 141                             strcspn($_SERVER['REQUEST_URI'], "\n\r")),
 142                             ENT_QUOTES);
 143
 144     if (isset($_SERVER['HTTPS']) &&
 145         strtolower($_SERVER['HTTPS']) == 'on') {
 146         $protocol = 'https://';
 147     } else {
 148         $protocol = 'http://';
 149     }
 150     $host = $_SERVER['HTTP_HOST'];
 151     if ($_SERVER['HTTP_PORT'] != '' &&
 152         (($protocol == 'http://' && $_SERVER['HTTP_PORT'] != '80') ||
 153         ($protocol == 'https://' && $_SERVER['HTTP_PORT'] != '443'))) {
 154         $port = ':' . $_SERVER['HTTP_PORT'];
 155     } else {
 156         $port = '';
 157     }
 158     return $protocol . $host . $port . $php_request_uri;
 159 }
 160
 161 /**
 162  * AuthSub 認証済みの HTTP クライアントを作成し、ログインが必要なら
 163  * ユーザを AuthSub サーバにリダイレクトします
 164  */
 165 function getAuthSubHttpClient()
 166 {
 167     global $_SESSION, $_GET;
 168
 169     // AuthSub セッションあるいはワンタイムトークンがなければ、
 170     // AuthSub サーバにリダイレクトします
 171     if (!isset($_SESSION['sessionToken']) && !isset($_GET['token'])) {
 172         // AuthSub サーバへのパラメータ
 173         $next = getCurrentUrl();
 174         $scope = "http://www.google.com/calendar/feeds/";
 175         $secure = false;
 176         $session = true;
 177
 178         // ユーザを AuthSub サーバにリダイレクトします
 179
 180         $authSubUrl = Zend_Gdata_AuthSub::getAuthSubTokenUri($next,
 181                                                              $scope,
 182                                                              $secure,
 183                                                              $session);
 184          header("HTTP/1.0 307 Temporary redirect");
 185
 186          header("Location: " . $authSubUrl);
 187
 188          exit();
 189     }
 190
 191     // AuthSub のワンタイムトークンを、必要に応じてセッショントークンに変換します
 192     if (!isset($_SESSION['sessionToken']) && isset($_GET['token'])) {
 193         $_SESSION['sessionToken'] =
 194             Zend_Gdata_AuthSub::getAuthSubSessionToken($_GET['token']);
 195     }
 196
 197     // この時点で AuthSub による認証がすんでいるので、
 198     // 認証済みの HTTP クライアントのインスタンスを作成できます
 199
 200     // 認証済みの HTTP クライアントを作成します
 201     $client = Zend_Gdata_AuthSub::getHttpClient($_SESSION['sessionToken']);
 202     return $client;
 203 }
 204
 205 // -> スクリプトの実行はここから始まります <-
 206
 207 // ユーザが有効なセッションを保持していることを確認し、
 208 // AuthSub セッショントークンを記録します
 209 session_start();
 210
 211 // Calendar サービスのインスタンスを作成し、
 212 // 必要に応じてユーザを AuthSub サーバにリダイレクトします
 213 $service = new Zend_Gdata_Calendar(getAuthSubHttpClient());
 214 ]]></programlisting>
 215             <para>未認証のサーバを作成して、公開フィードへのアクセスや MagicCookie 認証で使用できます。</para>
 216             <programlisting language="php"><![CDATA[
 217 // Calendar サービスのインスタンスを、
 218 // 未認証の HTTP クライアントで作成します
 219
 220 $service = new Zend_Gdata_Calendar();
 221 ]]></programlisting>
 222             <para>
 223                 MagicCookie 認証は <acronym>HTTP</acronym> 接続で提供するものではなく、
 224                 クエリを送信する際の可視性を指定するものです。
 225                 以下にあるイベント取得の例を見てみましょう。
 226             </para>
 227         </sect3>
 228     </sect2>
 229     <sect2 id="zend.gdata.calendar_retrieval">
 230         <title>カレンダーリストの取得</title>
 231         <para>
 232             カレンダーサービスには、
 233             認証済みのユーザのカレンダーの一覧を取得する機能があります。
 234             これは Google Calendar の画面に表示される一覧と同じですが、
 235             "<code>hidden</code>" とマークされているものも取得できるという点が異なります。
 236         </para>
 237         <para>
 238             カレンダーリストは常に非公開なので、認証済み接続でアクセスする必要があります。
 239             別のユーザのカレンダーリストを取得したり、MagicCookie
 240             認証でアクセスしたりすることはできません。
 241             適切な認証情報を持たずにカレンダーリストにアクセスしようとすると、
 242             その処理は失敗し、ステータスコード 401 (Authentication Required) を返します。
 243         </para>
 244         <programlisting language="php"><![CDATA[
 245 $service = Zend_Gdata_Calendar::AUTH_SERVICE_NAME;
 246 $client = Zend_Gdata_ClientLogin::getHttpClient($user, $pass, $service);
 247 $service = new Zend_Gdata_Calendar($client);
 248
 249 try {
 250     $listFeed= $service->getCalendarListFeed();
 251 } catch (Zend_Gdata_App_Exception $e) {
 252     echo "エラー: " . $e->getMessage();
 253 }
 254 ]]></programlisting>
 255         <para>
 256             <methodname>getCalendarListFeed()</methodname> をコールすると
 257             <classname>Zend_Gdata_Calendar_ListFeed</classname>
 258             の新しいインスタンスを作成します。この中には、使用できるカレンダーの一覧が
 259             <classname>Zend_Gdata_Calendar_ListEntry</classname>
 260             のインスタンスとして格納されています。
 261             フィードを取得したら、それを使用して中身を取得できます。
 262         </para>
 263         <programlisting language="php"><![CDATA[
 264 echo "<h1>カレンダーリストのフィード</h1>";
 265 echo "<ul>";
 266 foreach ($listFeed as $calendar) {
 267     echo "<li>" . $calendar->title .
 268          " (Event Feed: " . $calendar->id . ")</li>";
 269 }
 270 echo "</ul>";
 271 ]]></programlisting>
 272     </sect2>
 273     <sect2 id="zend.gdata.event_retrieval">
 274         <title>イベントの取得</title>
 275         <para>
 276             カレンダーリストと同様、イベントも
 277             <classname>Zend_Gdata_Calendar</classname>
 278             クラスで取得できます。
 279             返されるイベントリストの型は
 280             <classname>Zend_Gdata_Calendar_EventFeed</classname>
 281             で、各イベントは
 282             <classname>Zend_Gdata_Calendar_EventEntry</classname>
 283             のインスタンスとして格納されています。
 284             先ほどの例と同様の方法で、個々のイベントの情報を取得できます。
 285         </para>
 286         <sect3 id="zend.gdata.event_retrieval.queries">
 287             <title>クエリ</title>
 288             <para>
 289                 Calendar <acronym>API</acronym> でイベントを取得する際には、
 290                 クエリ <acronym>URL</acronym> を用いてほしいイベントを指定します。
 291                 <classname>Zend_Gdata_Calendar_EventQuery</classname> クラスは、
 292                 指定したパラメータに基づいたクエリ <acronym>URL</acronym>
 293                 を自動的に作成することでこの作業の手間を軽減します。
 294                 使用できるパラメータの一覧は
 295                 <ulink url="http://code.google.com/apis/gdata/reference.html#Queries">
 296                 Google Data <acronym>API</acronym>s Protocol Reference の Queries セクション</ulink>
 297                 にあります。ここでは、そのうち特に重要な
 298                 3 つのパラメータについて説明します。
 299             </para>
 300             <itemizedlist>
 301                 <listitem>
 302                     <para>
 303                         <firstterm>User</firstterm>
 304                         は、誰のカレンダーを検索するのかをメールアドレスで指定します。
 305                         省略した場合は "default" を使用します。
 306                         これは、現在認証されているユーザ (認証済みの場合)
 307                         を表します。
 308                     </para>
 309                 </listitem>
 310                 <listitem>
 311                     <para>
 312                         <firstterm>Visibility</firstterm>
 313                         は、公開カレンダーと非公開カレンダーの
 314                         どちらを検索するのかを指定します。
 315                         未認証のセッションを使用していて
 316                         MagicCookie もない場合は、
 317                         公開フィードのみしか使用できません。
 318                     </para>
 319                 </listitem>
 320                 <listitem>
 321                     <para>
 322                         <firstterm>Projection</firstterm>
 323                         は、サーバから返されるデータの件数とフォーマットを指定します。
 324                         たいていの場合は "full" を指定することになるでしょう。
 325                         "basic" を指定すると、ほとんどのメタデータ情報を
 326                         各イベントの content フィールドの可読形式で格納します。
 327                         "composite" を指定すると、各イベントについてのコメントも情報に付加します。
 328                         "composite" は、"full"
 329                         よりも巨大になることもあります。
 330                     </para>
 331                 </listitem>
 332             </itemizedlist>
 333         </sect3>
 334         <sect3 id="zend.gdata.event_retrieval.start_time">
 335             <title>開始時刻順によるイベントの取得</title>
 336             <para>
 337                 以下の例は、
 338                 <classname>Zend_Gdata_Query</classname> を使用して非公開フィードを指定しています。
 339                 つまり、認証済みの接続が必要となります。
 340                 認証に MagicCookie を使用している場合は、可視性は
 341                 "<code>private-magicCookieValue</code>"
 342                 としなければなりません。magicCookieValue
 343                 のところは、Google Calendar で非公開
 344                 <acronym>XML</acronym> アドレスを閲覧した際に取得したランダムな文字列となります。
 345                 イベントは開始時刻の順に取得され、
 346                 過去のイベントは返されません。
 347             </para>
 348             <programlisting language="php"><![CDATA[
 349 $query = $service->newEventQuery();
 350 $query->setUser('default');
 351 // MagicCookie 認証の場合は
 352 // $query->setVisibility('private-magicCookieValue') とします
 353 $query->setVisibility('private');
 354 $query->setProjection('full');
 355 $query->setOrderby('starttime');
 356 $query->setFutureevents('true');
 357
 358 // カレンダーサーバからイベントの一覧を取得します
 359 try {
 360     $eventFeed = $service->getCalendarEventFeed($query);
 361 } catch (Zend_Gdata_App_Exception $e) {
 362     echo "エラー: " . $e->getMessage();
 363 }
 364
 365 // リストの内容を順に取得し、HTML のリストとして出力します
 366 echo "<ul>";
 367 foreach ($eventFeed as $event) {
 368     echo "<li>" . $event->title . " (Event ID: " . $event->id . ")</li>";
 369 }
 370 echo "</ul>";
 371 ]]></programlisting>
 372             <para>
 373                 ID や author、when、event status、visibility、web content、
 374                 そして content などのさまざまなプロパティが
 375                 <classname>Zend_Gdata_Calendar_EventEntry</classname>
 376                 で使用できます。プロパティの一覧は
 377                 <ulink url="http://framework.zend.com/apidoc/core/">Zend Framework
 378                 <acronym>API</acronym> ドキュメント</ulink>
 379                 や
 380                 <ulink url="http://code.google.com/apis/gdata/reference.html">Calendar Protocol Reference</ulink>
 381                 を参照ください。
 382             </para>
 383         </sect3>
 384         <sect3 id="zend.gdata.event_retrieval.date_range">
 385             <title>指定した日付の範囲からのイベントの取得</title>
 386             <para>
 387                 指定した範囲、たとえば 2006 年 12 月 1 日から
 388                 2006 年 12 月 15 日までのすべてのイベントを表示するには、
 389                 先ほどのサンプルに次の 2 行を追加します。
 390                 "<code>$query->setFutureevents('true')</code>"
 391                 を削除することを忘れないでください。
 392                 <code>futureevents</code>
 393                 を指定すると
 394                 <code>startMin</code>
 395                 や
 396                 <code>startMax</code>
 397                 を上書きしてしまうからです。
 398             </para>
 399             <programlisting language="php"><![CDATA[
 400 $query->setStartMin('2006-12-01');
 401 $query->setStartMax('2006-12-16');
 402 ]]></programlisting>
 403             <para>
 404                 <code>startMin</code>
 405                 は範囲に含まれますが、
 406                 <code>startMax</code>
 407                 は含まれないことに注意しましょう。上の例の場合、
 408                 2006-12-15 23:59:59 までのイベントが対象となります。
 409             </para>
 410         </sect3>
 411         <sect3 id="zend.gdata.event_retrieval.fulltext">
 412             <title>全文検索によるイベントの取得</title>
 413             <para>
 414                 指定した単語、たとえば "dogfood"
 415                 を含むすべてのイベントを表示するには、
 416                 <methodname>setQuery()</methodname>
 417                 メソッドでクエリを作成します。
 418             </para>
 419             <programlisting language="php"><![CDATA[
 420 $query->setQuery("dogfood");
 421 ]]></programlisting>
 422         </sect3>
 423         <sect3 id="zend.gdata.event_retrieval.individual">
 424             <title>特定のイベントの取得</title>
 425             <para>
 426                 特定のイベントを取得する場合は、そのイベントの ID
 427                 をクエリで指定します。そして
 428                 <methodname>getCalendarEventFeed()</methodname>
 429                 ではなく
 430                 <methodname>getCalendarEventEntry()</methodname>
 431                 をコールします。
 432             </para>
 433             <programlisting language="php"><![CDATA[
 434 $query = $service->newEventQuery();
 435 $query->setUser('default');
 436 $query->setVisibility('private');
 437 $query->setProjection('full');
 438 $query->setEvent($eventId);
 439
 440 try {
 441     $event = $service->getCalendarEventEntry($query);
 442 } catch (Zend_Gdata_App_Exception $e) {
 443     echo "エラー: " . $e->getMessage();
 444 }
 445 ]]></programlisting>
 446             <para>
 447                 同様に、もしそのイベントの <acronym>URL</acronym> がわかっているのなら、
 448                 それを直接 <methodname>getCalendarEntry()</methodname>
 449                 に渡して特定のイベントを取得することもできます。
 450                 この場合はクエリオブジェクトは不要です。
 451                 必要な情報は、イベントの <acronym>URL</acronym> にすべて含まれているからです。
 452             </para>
 453             <programlisting language="php"><![CDATA[
 454 $eventURL = "http://www.google.com/calendar/feeds/default/private"
 455           . "/full/g829on5sq4ag12se91d10uumko";
 456
 457 try {
 458     $event = $service->getCalendarEventEntry($eventURL);
 459 } catch (Zend_Gdata_App_Exception $e) {
 460     echo "エラー: " . $e->getMessage();
 461 }
 462 ]]></programlisting>
 463         </sect3>
 464     </sect2>
 465     <sect2 id="zend.gdata.calendar.creating_events">
 466         <title>イベントの作成</title>
 467         <sect3 id="zend.gdata.calendar.creating_events.single">
 468             <title>一度だけのイベントの作成</title>
 469             <para>
 470                 イベントをカレンダーに追加するには、
 471                 <classname>Zend_Gdata_EventEntry</classname> のインスタンスを作成して
 472                 そこに適切なデータを代入します。カレンダーサービスのインスタンス
 473                 (<classname>Zend_Gdata_Calendar</classname>) はそのデータを <acronym>XML</acronym>
 474                 に変換し、カレンダーサーバに POST します。
 475                 イベントを作成するには、AuthSub 認証あるいは
 476                 ClientAuth 認証でカレンダーサーバと接続する必要があります。
 477             </para>
 478             <para>最低限設定しなければならない属性は、次のとおりです。</para>
 479             <itemizedlist>
 480                 <listitem>
 481                     <para>
 482                         <firstterm>Title</firstterm>
 483                         は、Google Calendar でイベントの見出しとして表示される内容です。
 484                     </para>
 485                 </listitem>
 486                 <listitem>
 487                     <para>
 488                         <firstterm>When</firstterm>
 489                         は、そのイベントの期間を表します。
 490                         オプションで、リマインダーを関連付けることができます。
 491                         この属性については、次のセクションで詳しく説明します。
 492                     </para>
 493                 </listitem>
 494             </itemizedlist>
 495             <para>その他、オプションで設定できる属性は次のようになります。</para>
 496             <itemizedlist>
 497                 <listitem>
 498                     <para>
 499                         <firstterm>Author</firstterm>
 500                         は、そのイベントを作成したユーザについての情報です。
 501                     </para>
 502                 </listitem>
 503                 <listitem>
 504                     <para>
 505                         <firstterm>Content</firstterm>
 506                         は、イベントの詳細情報です。
 507                         Google Calendar でそのイベントの詳細情報を開いたときに表示されます。
 508                     </para>
 509                 </listitem>
 510                 <listitem>
 511                     <para>
 512                         <firstterm>EventStatus</firstterm>
 513                         はそのイベントが確認済み (confirmed)
 514                         なのか仮の予定 (tentative) なのか、
 515                         あるいは取り消された (canceled) を表します。
 516                     </para>
 517                 </listitem>
 518                 <listitem>
 519                     <para>
 520                         <firstterm>Hidden</firstterm>
 521                         は、そのイベントを Google Calendar 上で非表示にします。
 522                     </para>
 523                 </listitem>
 524                 <listitem>
 525                     <para>
 526                         <firstterm>Transparency</firstterm>
 527                         は、そのイベントをユーザの予定表に反映させるかどうかを指定します。
 528                     </para>
 529                 </listitem>
 530                 <listitem>
 531                     <para>
 532                         <firstterm>WebContent</firstterm>
 533                         は、そのイベント内で外部のコンテンツへのリンクを指定します。
 534                     </para>
 535                 </listitem>
 536                 <listitem>
 537                     <para>
 538                         <firstterm>Where</firstterm>
 539                         は、そのイベントの場所を指定します。
 540                     </para>
 541                 </listitem>
 542                 <listitem>
 543                     <para>
 544                         <firstterm>Visibility</firstterm>
 545                         は、そのイベントを公開リスト上では非表示にします。
 546                     </para>
 547                 </listitem>
 548             </itemizedlist>
 549             <para>
 550                 イベントの属性の一覧は、
 551                 <ulink url="http://framework.zend.com/apidoc/core/">Zend Framework <acronym>API</acronym>
 552                 ドキュメント</ulink>
 553                 および
 554                 <ulink url="http://code.google.com/apis/gdata/reference.html">Calendar
 555                 Protocol Reference</ulink>
 556                 を参照ください。
 557                 where のように複数の値を持つことのある属性は配列で実装しています。
 558                 それにあわせて適切な形式にする必要があります。これらの属性には、
 559                 パラメータとしてオブジェクトを渡さなければならないことに注意しましょう。
 560                 文字列などを渡そうとすると、<acronym>XML</acronym> への変換時にエラーとなります。
 561             </para>
 562             <para>
 563                 イベントの情報を設定したら、それをカレンダーサーバにアップロードします。
 564                 アップロードするには、カレンダーサーバの
 565                 <methodname>insertEvent()</methodname> 関数の引数としてそのイベントを渡します。
 566             </para>
 567             <programlisting language="php"><![CDATA[
 568 // カレンダーサービスのマジックメソッドで、新規エントリを作成します
 569 $event= $service->newEventEntry();
 570
 571 // イベントの情報を設定します
 572 // 各属性は、対応するクラスのインスタンスとして作成されることに注意しましょう
 573 $event->title = $service->newTitle("My Event");
 574 $event->where = array($service->newWhere("Mountain View, California"));
 575 $event->content =
 576     $service->newContent(" This is my awesome event. RSVP required.");
 577
 578 // RFC 3339 形式で日付を指定します
 579 $startDate = "2008-01-20";
 580 $startTime = "14:00";
 581 $endDate = "2008-01-20";
 582 $endTime = "16:00";
 583 $tzOffset = "-08";
 584
 585 $when = $service->newWhen();
 586 $when->startTime = "{$startDate}T{$startTime}:00.000{$tzOffset}:00";
 587 $when->endTime = "{$endDate}T{$endTime}:00.000{$tzOffset}:00";
 588 $event->when = array($when);
 589
 590 // イベントをカレンダーサーバにアップロードします
 591 // サーバに記録したイベントのコピーが返されます
 592 $newEvent = $service->insertEvent($event);
 593 ]]></programlisting>
 594         </sect3>
 595         <sect3 id="zend.gdata.calendar.creating_events.schedulers_reminders">
 596             <title>イベントのスケジュールおよびリマインダー</title>
 597             <para>
 598                 イベントの開始時刻と期間は <code>when</code> プロパティによって決まります。
 599                 この中には
 600                 <code>startTime</code>、<code>endTime</code>
 601                 および <code>valueString</code>
 602                 というプロパティが含まれます。
 603                 <code>StartTime</code> および <code>EndTime</code>
 604                 がイベントの期間を表します。一方 <code>valueString</code>
 605                 は現在使われていません。
 606             </para>
 607             <para>
 608                 全日のイベントを作成するには、
 609                 <code>startTime</code>
 610                 および
 611                 <code>endTime</code>
 612                 で日付のみを指定し、時刻は省略します。
 613                 同様に、期間がゼロのイベントを作成する場合は
 614                 <code>endTime</code> を省略します。
 615                 すべての場合について、日付や時刻は
 616                 <ulink url="http://www.ietf.org/rfc/rfc3339.txt">RFC3339</ulink>
 617                 形式で指定しなければなりません。
 618             </para>
 619             <programlisting language="php"><![CDATA[
 620 // 2007 年 12 月 5 日の午後 2 時 (UTC-8) から
 621 // 1 時間のイベントを設定します
 622 $when = $service->newWhen();
 623 $when->startTime = "2007-12-05T14:00:00-08:00";
 624 $when->endTime="2007-12-05T15:00:00:00-08:00";
 625
 626 // when プロパティをイベントに追加します
 627 $event->when = array($when);
 628 ]]></programlisting>
 629             <para>
 630                 <code>when</code> 属性では、
 631                 ユーザへのリマインダーをいつ送信するかを指定することもできます。
 632                 リマインダーは配列形式で保存し、各イベントには
 633                 5 つまでのリマインダーを関連づけることができます。
 634             </para>
 635             <para>
 636                 <code>reminder</code> を指定するには、少なくともふたつの属性
 637                 <code>method</code> と time を指定する必要があります。
 638                 <code>method</code> には "alert"、"email"
 639                 あるいは "sms" を文字列で指定します。time
 640                 は整数値で指定します。
 641                 <code>minutes</code>、<code>hours</code>、<code>days</code>
 642                 を指定するか、あるいは
 643                 <code>absoluteTime</code> を指定します。
 644                 しかし、指定するのはこれらの中のどれかひとつのみとしなければなりません。
 645                 複数の単位が必要な場合は、一番小さい単位に換算して指定します。
 646                 たとえば、1 時間 30 分の場合は 90 分と指定しなければなりません。
 647             </para>
 648             <programlisting language="php"><![CDATA[
 649 // 新しいリマインダーオブジェクトを作成します。
 650 // 予定の 10 分前に、メールでメッセージを送るようにします
 651 $reminder = $service->newReminder();
 652 $reminder->method = "email";
 653 $reminder->minutes = "10";
 654
 655 // 既存のイベントの when プロパティにリマインダーを適用します
 656 $when = $event->when[0];
 657 $when->reminders = array($reminder);
 658 ]]></programlisting>
 659         </sect3>
 660         <sect3 id="zend.gdata.calendar.creating_events.recurring">
 661             <title>繰り返し発生するイベントの作成</title>
 662             <para>
 663                 繰り返し発生するイベントの作成方法は、
 664                 一回しか発生しないイベントの場合と同じです。
 665                 ただ、when 属性の代わりに recurrence 属性を指定する必要があります。
 666                 recurrence 属性は、そのイベントの繰り返しパターンを文字列で指定します。
 667                 この文字列は、iCalendar の標準規格 (
 668                 <ulink url="http://www.ietf.org/rfc/rfc2445.txt">RFC 2445</ulink>
 669                 ) で定義されているものを使用します。
 670             </para>
 671             <para>
 672                 繰り返しパターンの例外は、別途
 673                 <code>recurrenceException</code> 属性で指定します。
 674                 しかし、iCalendar の標準規格では第二の繰り返しパターンを定義できます。
 675                 どちらかを使用するといいでしょう。
 676             </para>
 677             <para>
 678                 繰り返しパターンの解析は複雑なので、詳細はこのドキュメントでは扱いません。
 679                 詳細な情報を知りたい場合は、
 680                 <ulink url="http://code.google.com/apis/gdata/elements.html#gdRecurrence">Google
 681                 Data <acronym>API</acronym>s Developer Guide の Common Elements セクション</ulink>
 682                 あるいは <acronym>RFC</acronym> 2445 を参照ください。
 683             </para>
 684             <programlisting language="php"><![CDATA[
 685  // カレンダーサービスのマジックメソッドで、新規エントリを作成します
 686 $event= $service->newEventEntry();
 687
 688 // イベントの情報を設定します
 689 // 各属性は、対応するクラスのインスタンスとして作成されることに注意しましょう
 690 $event->title = $service->newTitle("My Recurring Event");
 691 $event->where = array($service->newWhere("Palo Alto, California"));
 692 $event->content =
 693     $service->newContent(' This is my other awesome event, ' .
 694                          ' occurring all-day every Tuesday from .
 695                          '2007-05-01 until 207-09-04. No RSVP required.');
 696
 697 // 繰り返しパターンの期間と頻度を指定します
 698
 699 $recurrence = "DTSTART;VALUE=DATE:20070501\r\n" .
 700         "DTEND;VALUE=DATE:20070502\r\n" .
 701         "RRULE:FREQ=WEEKLY;BYDAY=Tu;UNTIL=20070904\r\n";
 702
 703 $event->recurrence = $service->newRecurrence($recurrence);
 704
 705 // イベントをカレンダーサーバにアップロードします
 706 // サーバに記録したイベントのコピーが返されます
 707 $newEvent = $service->insertEvent($event);
 708 ]]></programlisting>
 709         </sect3>
 710         <sect3 id="zend.gdata.calendar.creating_events.quickadd">
 711             <title>QuickAdd の使用法</title>
 712             <para>
 713                 QuickAdd とは、自由形式のテキストでイベントを作成する機能のことです。
 714                 たとえば、"Dinner at Joe's Diner on Thursday" という文字列を指定すると、
 715                 タイトルが "Dinner"、場所が "Joe's Diner"、日付が "Thursday"
 716                 のイベントが作成されます。QuickAdd 機能を使用するには、
 717                 <code>QuickAdd</code> プロパティを <constant>TRUE</constant> に設定し、
 718                 任意のテキストを <code>content</code> プロパティに指定します。
 719             </para>
 720             <programlisting language="php"><![CDATA[
 721 // カレンダーサービスのマジックメソッドで、新規エントリを作成します
 722 $event= $service->newEventEntry();
 723
 724 // イベントの情報を設定します
 725 $event->content= $service->newContent("Dinner at Joe's Diner on Thursday");
 726 $event->quickAdd = $service->newQuickAdd("true");
 727
 728 // イベントをカレンダーサーバにアップロードします
 729 // サーバに記録したイベントのコピーが返されます
 730 $newEvent = $service->insertEvent($event);
 731 ]]></programlisting>
 732         </sect3>
 733     </sect2>
 734     <sect2 id="zend.gdata.calendar.modifying_events">
 735         <title>イベントの変更</title>
 736         <para>
 737             イベントのインスタンスを取得したら、
 738             新しいイベントを作成する場合と同じようにしてその属性を変更できます。
 739             変更が完了したら、そのイベントの <methodname>save()</methodname>
 740             メソッドをコールすると、変更内容をカレンダーサーバにアップロードします。
 741             そして、更新後のイベントのコピーを返します。
 742         </para>
 743         <para>
 744             イベントを取得した後で別のユーザがそのイベントを変更していた場合、
 745             <methodname>save()</methodname> は失敗し、ステータスコード 409 (Conflict)
 746             を返します。これを解決するには、
 747             変更を加える直前に最新のコピーを取得する必要があります。
 748         </para>
 749         <programlisting language="php"><![CDATA[
 750 // ユーザのイベントリストから最初のイベントを取得します
 751 $event = $eventFeed[0];
 752
 753 // タイトルを変更します
 754 $event->title = $service->newTitle("Woof!");
 755
 756 // 変更をサーバにアップロードします
 757 try {
 758     $event->save();
 759 } catch (Zend_Gdata_App_Exception $e) {
 760     echo "エラー: " . $e->getMessage();
 761 }
 762 ]]></programlisting>
 763     </sect2>
 764     <sect2 id="zend.gdata.calendar.deleting_events">
 765         <title>イベントの削除</title>
 766         <para>
 767             カレンダーのイベントを削除する方法には二通りあります。
 768             ひとつはカレンダーサービスの <methodname>delete()</methodname>
 769             メソッドにそのイベントの編集用 <acronym>URL</acronym> を指定する方法、
 770             もうひとつはそのイベント自身の <methodname>delete()</methodname>
 771             メソッドをコールすることです。
 772         </para>
 773         <para>
 774             どちらの場合も、クエリのパラメータ <code>updateMin</code>
 775             を指定した場合は削除後もそのイベントが
 776             プライベートイベントフィードとして残ります。
 777             削除されたイベントと通常のイベントを区別するには
 778             <code>eventStatus</code> プロパティを確認します。
 779             削除されたイベントは、このプロパティが
 780             "http://schemas.google.com/g/2005#event.canceled"
 781             に設定されています。
 782         </para>
 783         <programlisting language="php"><![CDATA[
 784 // 方法 1: イベントを直接削除します
 785 $event->delete();
 786 ]]></programlisting>
 787         <programlisting language="php"><![CDATA[
 788 // 方法 2: カレンダーサービスに、
 789 // 削除したいイベントの編集 URL を渡します
 790 $service->delete($event->getEditLink()->href);
 791 ]]></programlisting>
 792     </sect2>
 793     <sect2 id="zend.gdata.calendar.comments">
 794         <title>イベントのコメントへのアクセス</title>
 795         <para>
 796             full イベントビューでは、コメントはイベントのエントリに保存されません。
 797             その代わりとして、各イベントにはコメントの <acronym>URL</acronym> が含まれており、
 798             それを使用して手動でコメントを取得することになります。
 799         </para>
 800         <para>
 801             コメントの操作方法は、イベントの場合とよく似ています。
 802             ただ、使用するフィードクラスやエントリクラスは異なります。
 803             またイベントのメタデータにある where や when
 804             といったプロパティはコメントにはありません。コメントの発言者は
 805             <code>author</code> プロパティに、そしてコメントの本文は
 806             <code>content</code> プロパティに格納されます。
 807         </para>
 808         <programlisting language="php"><![CDATA[
 809 // コメントの URL を、フィードリストの最初のイベントから取得します
 810 $event = $eventFeed[0];
 811 $commentUrl = $event->comments->feedLink->url;
 812
 813 // そのイベントのコメント一覧を取得します
 814 try {
 815 $commentFeed = $service->getFeed($commentUrl);
 816 } catch (Zend_Gdata_App_Exception $e) {
 817     echo "エラー: " . $e->getMessage();
 818 }
 819
 820 // 各コメントを HTML のリストで出力します
 821 echo "<ul>";
 822 foreach ($commentFeed as $comment) {
 823     echo "<li><em>Comment By: " . $comment->author->name "</em><br/>" .
 824          $comment->content . "</li>";
 825 }
 826 echo "</ul>";
 827 ]]></programlisting>
 828     </sect2>
 829 </sect1>