Google Calendar の使用法Zend_Gdata_Calendar クラスを使うと、Google Calendar サービスで イベントの閲覧や作成、更新、削除ができるようになります。 Google Calendar API についての詳細な情報は » http://code.google.com/apis/calendar/overview.html を参照ください。 Calendar サービスへの接続Google Calendar API は、その他の GData API と同様に Atom Publishing Protocol (APP) を使用しています。これは、XML ベースのフォーマットでウェブのリソースを管理するための仕組みです。 クライアントと Google Calendar サーバとの間のやり取りは HTTP で行われ、認証済みの接続と未認証の接続の両方が利用できます。 何らかのトランザクションが発生する際には、 必ず接続を確立する必要があります。 カレンダーサーバとの接続は、まず HTTP クライアントを作成して Zend_Gdata_Calendar サービスのインスタンスをそこにバインドするという手順で行います。 認証Google Calendar API を使用すると、公開カレンダーだけでなく プライベートカレンダーのフィードにもアクセスできます。 公開フィードには認証は不要ですが、 認証しない場合は読み込み専用となり、機能が制限されます。 プライベートフィードでは完全な機能が使用できますが、 カレンダーサーバとの認証が必要になります。 Google Calendar がサポートしている認証方式は、次の 3 通りです。
Zend_Gdata ライブラリは、 これらのすべての方式に対応しています。 これ以降の説明は、認証方式については理解しており 適切な認証方式で接続できるようになっていることを前提として進めていきます。 詳細な情報は、このマニュアルの 認証に関するセクション か、あるいは » Google Data API Developer's Guide の Authentication Overview を参照ください。 サービスのインスタンスの作成Google Calendar を使用するためのクラスとして、このライブラリでは Zend_Gdata_Calendar を用意しています。 このクラスは Google Data や Atom Publishing Protocol モデルへの共通インターフェイスを提供し、 カレンダーサーバとのリクエストのやりとりを支援します。 使用する認証方式を決めたら、次に Zend_Gdata_Calendar のインスタンスを作成します。 このクラスのコンストラクタには、引数として Zend_Http_Client のインスタンスを渡します。 これは、AuthSub 認証および ClientAuth 認証へのインターフェイスを提供します。 これらの認証を使用する場合には、認証済みの HTTP クライアントが必要です。 引数を省略した場合は、未認証の Zend_Http_Client のインスタンスを自動的に作成して使用します。 以下の例は、ClientAuth 認証を使用して Calendar サービスを作成するものです。
AuthSub を使用する Calendar サービスを作成するのもほぼ同様ですが、 少々長めになります。
未認証のサーバを作成して、公開フィードへのアクセスや MagicCookie 認証で使用できます。
MagicCookie 認証は HTTP 接続で提供するものではなく、 クエリを送信する際の可視性を指定するものです。 以下にあるイベント取得の例を見てみましょう。 カレンダーリストの取得カレンダーサービスには、 認証済みのユーザのカレンダーの一覧を取得する機能があります。 これは Google Calendar の画面に表示される一覧と同じですが、 "hidden" とマークされているものも取得できるという点が異なります。 カレンダーリストは常に非公開なので、認証済み接続でアクセスする必要があります。 別のユーザのカレンダーリストを取得したり、MagicCookie 認証でアクセスしたりすることはできません。 適切な認証情報を持たずにカレンダーリストにアクセスしようとすると、 その処理は失敗し、ステータスコード 401 (Authentication Required) を返します。
getCalendarListFeed() をコールすると Zend_Gdata_Calendar_ListFeed の新しいインスタンスを作成します。この中には、使用できるカレンダーの一覧が Zend_Gdata_Calendar_ListEntry のインスタンスとして格納されています。 フィードを取得したら、それを使用して中身を取得できます。 イベントの取得カレンダーリストと同様、イベントも Zend_Gdata_Calendar クラスで取得できます。 返されるイベントリストの型は Zend_Gdata_Calendar_EventFeed で、各イベントは Zend_Gdata_Calendar_EventEntry のインスタンスとして格納されています。 先ほどの例と同様の方法で、個々のイベントの情報を取得できます。 クエリCalendar API でイベントを取得する際には、 クエリ URL を用いてほしいイベントを指定します。 Zend_Gdata_Calendar_EventQuery クラスは、 指定したパラメータに基づいたクエリ URL を自動的に作成することでこの作業の手間を軽減します。 使用できるパラメータの一覧は » Google Data APIs Protocol Reference の Queries セクション にあります。ここでは、そのうち特に重要な 3 つのパラメータについて説明します。
開始時刻順によるイベントの取得以下の例は、 Zend_Gdata_Query を使用して非公開フィードを指定しています。 つまり、認証済みの接続が必要となります。 認証に MagicCookie を使用している場合は、可視性は "private-magicCookieValue" としなければなりません。magicCookieValue のところは、Google Calendar で非公開 XML アドレスを閲覧した際に取得したランダムな文字列となります。 イベントは開始時刻の順に取得され、 過去のイベントは返されません。
ID や author、when、event status、visibility、web content、 そして content などのさまざまなプロパティが Zend_Gdata_Calendar_EventEntry で使用できます。プロパティの一覧は » Zend Framework API ドキュメント や » Calendar Protocol Reference を参照ください。 指定した日付の範囲からのイベントの取得指定した範囲、たとえば 2006 年 12 月 1 日から 2006 年 12 月 15 日までのすべてのイベントを表示するには、 先ほどのサンプルに次の 2 行を追加します。 "$query->setFutureevents('true')" を削除することを忘れないでください。 futureevents を指定すると startMin や startMax を上書きしてしまうからです。
startMin は範囲に含まれますが、 startMax は含まれないことに注意しましょう。上の例の場合、 2006-12-15 23:59:59 までのイベントが対象となります。 全文検索によるイベントの取得指定した単語、たとえば "dogfood" を含むすべてのイベントを表示するには、 setQuery() メソッドでクエリを作成します。
特定のイベントの取得特定のイベントを取得する場合は、そのイベントの ID をクエリで指定します。そして getCalendarEventFeed() ではなく getCalendarEventEntry() をコールします。
同様に、もしそのイベントの URL がわかっているのなら、 それを直接 getCalendarEntry() に渡して特定のイベントを取得することもできます。 この場合はクエリオブジェクトは不要です。 必要な情報は、イベントの URL にすべて含まれているからです。
イベントの作成一度だけのイベントの作成イベントをカレンダーに追加するには、 Zend_Gdata_EventEntry のインスタンスを作成して そこに適切なデータを代入します。カレンダーサービスのインスタンス (Zend_Gdata_Calendar) はそのデータを XML に変換し、カレンダーサーバに POST します。 イベントを作成するには、AuthSub 認証あるいは ClientAuth 認証でカレンダーサーバと接続する必要があります。 最低限設定しなければならない属性は、次のとおりです。
その他、オプションで設定できる属性は次のようになります。
イベントの属性の一覧は、 » Zend Framework API ドキュメント および » Calendar Protocol Reference を参照ください。 where のように複数の値を持つことのある属性は配列で実装しています。 それにあわせて適切な形式にする必要があります。これらの属性には、 パラメータとしてオブジェクトを渡さなければならないことに注意しましょう。 文字列などを渡そうとすると、XML への変換時にエラーとなります。 イベントの情報を設定したら、それをカレンダーサーバにアップロードします。 アップロードするには、カレンダーサーバの insertEvent() 関数の引数としてそのイベントを渡します。
イベントのスケジュールおよびリマインダーイベントの開始時刻と期間は when プロパティによって決まります。 この中には startTime、endTime および valueString というプロパティが含まれます。 StartTime および EndTime がイベントの期間を表します。一方 valueString は現在使われていません。 全日のイベントを作成するには、 startTime および endTime で日付のみを指定し、時刻は省略します。 同様に、期間がゼロのイベントを作成する場合は endTime を省略します。 すべての場合について、日時は » RFC3339 形式で指定しなければなりません。
when 属性では、 ユーザへのリマインダーをいつ送信するかを指定することもできます。 リマインダーは配列形式で保存し、各イベントには 5 つまでのリマインダーを関連づけることができます。 reminder を指定するには、少なくともふたつの属性 method と time を指定する必要があります。 method には "alert"、"email" あるいは "sms" を文字列で指定します。time は整数値で指定します。 minutes、hours、days を指定するか、あるいは absoluteTime を指定します。 しかし、指定するのはこれらの中のどれかひとつのみとしなければなりません。 複数の単位が必要な場合は、一番小さい単位に換算して指定します。 たとえば、1 時間 30 分の場合は 90 分と指定しなければなりません。
繰り返し発生するイベントの作成繰り返し発生するイベントの作成方法は、 一回しか発生しないイベントの場合と同じです。 ただ、when 属性の代わりに recurrence 属性を指定する必要があります。 recurrence 属性は、そのイベントの繰り返しパターンを文字列で指定します。 この文字列は、iCalendar の標準規格 ( » RFC 2445 ) で定義されているものを使用します。 繰り返しパターンの例外は、別途 recurrenceException 属性で指定します。 しかし、iCalendar の標準規格では第二の繰り返しパターンを定義できます。 どちらかを使用するといいでしょう。 繰り返しパターンの解析は複雑なので、詳細はこのドキュメントでは扱いません。 詳細な情報を知りたい場合は、 » Google Data APIs Developer Guide の Common Elements セクション あるいは RFC 2445 を参照ください。
QuickAdd の使用法QuickAdd とは、自由形式のテキストでイベントを作成する機能のことです。 たとえば、"Dinner at Joe's Diner on Thursday" という文字列を指定すると、 タイトルが "Dinner"、場所が "Joe's Diner"、日付が "Thursday" のイベントが作成されます。QuickAdd 機能を使用するには、 QuickAdd プロパティを TRUE に設定し、 任意のテキストを content プロパティに指定します。
イベントの変更イベントのインスタンスを取得したら、 新しいイベントを作成する場合と同じようにしてその属性を変更できます。 変更が完了したら、そのイベントの save() メソッドをコールすると、変更内容をカレンダーサーバにアップロードします。 そして、更新後のイベントのコピーを返します。 イベントを取得した後で別のユーザがそのイベントを変更していた場合、 save() は失敗し、ステータスコード 409 (Conflict) を返します。これを解決するには、 変更を加える直前に最新のコピーを取得する必要があります。
イベントの削除カレンダーのイベントを削除する方法には二通りあります。 ひとつはカレンダーサービスの delete() メソッドにそのイベントの編集用 URL を指定する方法、 もうひとつはそのイベント自身の delete() メソッドをコールすることです。 どちらの場合も、クエリのパラメータ updateMin を指定した場合は削除後もそのイベントが プライベートイベントフィードとして残ります。 削除されたイベントと通常のイベントを区別するには eventStatus プロパティを確認します。 削除されたイベントは、このプロパティが "http://schemas.google.com/g/2005#event.canceled" に設定されています。
イベントのコメントへのアクセスfull イベントビューでは、コメントはイベントのエントリに保存されません。 その代わりとして、各イベントにはコメントの URL が含まれており、 それを使用して手動でコメントを取得することになります。 コメントの操作方法は、イベントの場合とよく似ています。 ただ、使用するフィードクラスやエントリクラスは異なります。 またイベントのメタデータにある where や when といったプロパティはコメントにはありません。コメントの発言者は author プロパティに、そしてコメントの本文は content プロパティに格納されます。
|
|