documentation/manual/ja/module_specs/Zend_Gdata_Photos.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <!-- EN-Revision: 21815 -->
   4 <sect1 id="zend.gdata.photos">
   5     <title>Picasa Web Albums の使用法</title>
   6
   7     <para>
   8         Picasa Web Albums は、自分の写真のアルバムを管理したり
   9         他人のアルバムや写真を閲覧したりするサービスです。
  10         <acronym>API</acronym> を使用すると、このサービスをプログラムから操作できるようになります。
  11         たとえばアルバムへの追加や更新、削除、
  12         そして写真へのタグ付けやコメントを行うことができます。
  13     </para>
  14
  15     <para>
  16         公開されているアルバムや写真へのアクセスについては、
  17         アカウントによる制限はありません。
  18         しかし、読み込み専用以外のアクセスを行うにはログインする必要があります。
  19     </para>
  20
  21     <para>
  22         <acronym>API</acronym> についての詳細な情報、
  23         たとえば <acronym>API</acronym> へのアクセスを有効にする方法などは <ulink
  24         url="http://code.google.com/apis/picasaweb/overview.html">Picasa
  25         Web Albums Data <acronym>API</acronym> の概要</ulink>
  26         を参照ください。
  27     </para>
  28
  29     <note>
  30         <title>認証</title>
  31         <para>
  32             この <acronym>API</acronym> は、AuthSub (推奨)
  33             および ClientAuth による認証に対応しています。
  34             書き込みを行うには認証済みの <acronym>HTTP</acronym> 接続が必須ですが、
  35             認証していない接続でも読み込み専用のアクセスは可能です。
  36         </para>
  37     </note>
  38
  39     <sect2 id="zend.gdata.photos.connecting">
  40         <title>サービスへの接続</title>
  41         <para>
  42             Picasa Web Albums <acronym>API</acronym> は、その他の GData <acronym>API</acronym> と同様に
  43             Atom Publishing Protocol (APP) を使用しています。これは、<acronym>XML</acronym>
  44             ベースのフォーマットでウェブのリソースを管理するための仕組みです。
  45             クライアントと Google Calendar サーバとの間のやり取りは
  46             <acronym>HTTP</acronym> で行われ、認証済みの接続と未認証の接続の両方が利用できます。
  47         </para>
  48
  49         <para>
  50             何らかのトランザクションが発生する際には、
  51             必ず接続を確立する必要があります。
  52             Picasa サーバとの接続は、まず <acronym>HTTP</acronym> クライアントを作成して
  53             <classname>Zend_Gdata_Photos</classname>
  54             サービスのインスタンスをそこにバインドするという手順で行います。
  55         </para>
  56
  57         <sect3 id="zend.gdata.photos.connecting.authentication">
  58             <title>認証</title>
  59             <para>
  60                 Google Picasa <acronym>API</acronym> を使用すると、公開カレンダーだけでなく
  61                 プライベートカレンダーのフィードにもアクセスできます。
  62                 公開フィードには認証は不要ですが、
  63                 認証しない場合は読み込み専用となり、機能が制限されます。
  64                 プライベートフィードでは完全な機能が使用できますが、
  65                 Picasa サーバとの認証が必要になります。
  66                 Google Picasa がサポートしている認証方式は、次の 3 通りです。
  67             </para>
  68
  69             <itemizedlist>
  70                 <listitem>
  71                     <para>
  72                         <firstterm>ClientAuth</firstterm>
  73                         は、Picasa サーバとの間で直接
  74                         ユーザ名/パスワード
  75                         による認証を行います。この方式では
  76                         ユーザ自身がアプリケーションにパスワードを教える必要があるので、
  77                         これは他の方式が使えない場合にのみ使用するようにしましょう。
  78                     </para>
  79                 </listitem>
  80                 <listitem>
  81                     <para>
  82                         <firstterm>AuthSub</firstterm>
  83                         は、Gooble のプロキシサーバを経由して Picasa サーバとの認証を行ないます。
  84                         これは ClientAuth と同じくらい便利に使用でき、
  85                         セキュリティリスクもありません。
  86                         ウェブベースのアプリケーションでは、
  87                         これは最適な選択肢となります。
  88                     </para>
  89                 </listitem>
  90             </itemizedlist>
  91
  92             <para>
  93                 <classname>Zend_Gdata</classname> ライブラリは、
  94                 これらのすべての方式に対応しています。
  95                 これ以降の説明は、認証方式については理解しており
  96                 適切な認証方式で接続できるようになっていることを前提として進めていきます。
  97                 詳細な情報は、このマニュアルの
  98                 <link linkend="zend.gdata.introduction.authentication">認証に関するセクション</link>
  99                 か、あるいは
 100                 <ulink url="http://code.google.com/apis/gdata/auth.html">Google Data <acronym>API</acronym> Developer's Guide
 101                 の Authentication Overview</ulink>
 102                 を参照ください。
 103             </para>
 104         </sect3>
 105
 106         <sect3 id="zend.gdata.photos.connecting.service">
 107             <title>サービスのインスタンスの作成</title>
 108             <para>
 109                 サーバとのやりとりを行うためのクラスとして、このライブラリでは
 110                 <classname>Zend_Gdata_Photos</classname> サービスクラスを用意しています。
 111                 このクラスは Google Data や Atom Publishing Protocol
 112                 モデルへの共通インターフェイスを提供し、
 113                 サーバとのリクエストのやりとりを支援します。
 114             </para>
 115
 116             <para>
 117                 使用する認証方式を決めたら、次に
 118                 <classname>Zend_Gdata_Photos</classname> のインスタンスを作成します。
 119                 このクラスのコンストラクタには、引数として
 120                 <classname>Zend_Http_Client</classname> のインスタンスを渡します。
 121                 これは、AuthSub 認証および ClientAuth 認証へのインターフェイスを提供します。
 122                 これらの認証を使用する場合には、認証済みの <acronym>HTTP</acronym> クライアントが必要です。
 123                 引数を省略した場合は、未認証の
 124                 <classname>Zend_Http_Client</classname>
 125                 のインスタンスを自動的に作成して使用します。
 126             </para>
 127
 128             <para>
 129                 以下の例は、ClientAuth 認証を使用してサービスクラスを作成するものです。
 130             </para>
 131             <programlisting language="php"><![CDATA[
 132 // ClientAuth 認証用のパラメータ
 133 $service = Zend_Gdata_Photos::AUTH_SERVICE_NAME;
 134 $user = "sample.user@gmail.com";
 135 $pass = "pa$$w0rd";
 136
 137 // 認証済みの HTTP クライアントを作成します
 138 $client = Zend_Gdata_ClientLogin::getHttpClient($user, $pass, $service);
 139
 140 // サービスのインスタンスを作成します
 141 $service = new Zend_Gdata_Photos($client);
 142 ]]></programlisting>
 143
 144             <para>
 145                 AuthSub を使用するサービスを作成するのもほぼ同様ですが、
 146                 少々長めになります。
 147             </para>
 148             <programlisting language="php"><![CDATA[
 149 session_start();
 150
 151 /**
 152  * 現在のページの完全な URL を、環境変数をもとにして返します
 153  *
 154  * 次の環境変数を使用します
 155  * $_SERVER['HTTPS'] = (on|off|)
 156  * $_SERVER['HTTP_HOST'] = Host: ヘッダの値
 157  * $_SERVER['SERVER_PORT'] = ポート番号 (http/80,https/443 以外の場合に使用します)
 158  * $_SERVER['REQUEST_URI'] = HTTP リクエストのメソッドのあとに続く URI
 159  *
 160  * @return string 現在の URL
 161  */
 162 function getCurrentUrl()
 163 {
 164     global $_SERVER;
 165
 166     /**
 167      * php_self をフィルタリングしてセキュリティ脆弱性を防ぎます
 168      */
 169     $php_request_uri = htmlentities(substr($_SERVER['REQUEST_URI'], 0,
 170     strcspn($_SERVER['REQUEST_URI'], "\n\r")), ENT_QUOTES);
 171
 172     if (isset($_SERVER['HTTPS']) && strtolower($_SERVER['HTTPS']) == 'on') {
 173         $protocol = 'https://';
 174     } else {
 175         $protocol = 'http://';
 176     }
 177     $host = $_SERVER['HTTP_HOST'];
 178     if ($_SERVER['SERVER_PORT'] != '' &&
 179         (($protocol == 'http://' && $_SERVER['SERVER_PORT'] != '80') ||
 180         ($protocol == 'https://' && $_SERVER['SERVER_PORT'] != '443'))) {
 181             $port = ':' . $_SERVER['SERVER_PORT'];
 182     } else {
 183         $port = '';
 184     }
 185     return $protocol . $host . $port . $php_request_uri;
 186 }
 187
 188 /**
 189  * 認証後のリダイレクト先を伝えられるようにします
 190  * AuthSub URL を返します
 191  *
 192  * getCurrentUrl() を使用して次の URL を取得し、
 193  * Google サービスでの認証に成功したらそこにリダイレクトします
 194  *
 195  * @return string AuthSub URL
 196  */
 197 function getAuthSubUrl()
 198 {
 199     $next = getCurrentUrl();
 200     $scope = 'http://picasaweb.google.com/data';
 201     $secure = false;
 202     $session = true;
 203     return Zend_Gdata_AuthSub::getAuthSubTokenUri($next, $scope, $secure,
 204         $session);
 205 }
 206
 207 /**
 208  * AuthSub 認証を使用して Google と通信するための適切なヘッダを設定した
 209  * HTTP クライアントオブジェクトを返します
 210  *
 211  * $_SESSION['sessionToken'] を使用して、取得した AuthSub セッショントークンを
 212  * 保存します。Google での認証に成功したユーザのリダイレクト先 URL
 213  * に含まれる一回限りのトークンは、$_GET['token'] から取得します
 214  *
 215  * @return Zend_Http_Client
 216  */
 217 function getAuthSubHttpClient()
 218 {
 219     global $_SESSION, $_GET;
 220     if (!isset($_SESSION['sessionToken']) && isset($_GET['token'])) {
 221         $_SESSION['sessionToken'] =
 222             Zend_Gdata_AuthSub::getAuthSubSessionToken($_GET['token']);
 223     }
 224     $client = Zend_Gdata_AuthSub::getHttpClient($_SESSION['sessionToken']);
 225     return $client;
 226 }
 227
 228 /**
 229  * サービスのインスタンスを作成し、
 230  * 必要に応じてユーザを AuthSub サーバにリダイレクトします
 231  */
 232 $service = new Zend_Gdata_Photos(getAuthSubHttpClient());
 233 ]]></programlisting>
 234
 235             <para>未認証のサーバを作成して、公開フィードへのアクセスに使用できます。</para>
 236             <programlisting language="php"><![CDATA[
 237 // サービスのインスタンスを、未認証の HTTP クライアントで作成します
 238 $service = new Zend_Gdata_Photos();
 239 ]]></programlisting>
 240         </sect3>
 241     </sect2>
 242
 243     <sect2 id="zend.gdata.photos.queries">
 244         <title>クエリの仕組みと作成方法</title>
 245         <para>
 246             サービスに対してデータを要求するために最初にやることは、
 247             クエリを作成することです。以下の形式用のクエリクラスが用意されています。
 248         </para>
 249
 250         <itemizedlist>
 251             <listitem>
 252                 <para>
 253                     <firstterm>User</firstterm>
 254                     は、誰のデータを探すのかをユーザ名で指定します。
 255                     省略した場合は "default" を使用します。
 256                     これは、現在認証されているユーザ (認証済みの場合)
 257                     を表します。
 258                 </para>
 259             </listitem>
 260             <listitem>
 261                 <para>
 262                     <firstterm>Album</firstterm>
 263                     は、検索対象のアルバムを
 264                     ID あるいはアルバム名で指定します。
 265                 </para>
 266             </listitem>
 267             <listitem>
 268                 <para>
 269                     <firstterm>Photo</firstterm>
 270                     は、検索対象の写真を ID で指定します。
 271                 </para>
 272             </listitem>
 273         </itemizedlist>
 274
 275         <para>新しい <code>UserQuery</code> を作成するには次のようにします。</para>
 276         <programlisting language="php"><![CDATA[
 277 $service = Zend_Gdata_Photos::AUTH_SERVICE_NAME;
 278 $client = Zend_Gdata_ClientLogin::getHttpClient($user, $pass, $service);
 279 $service = new Zend_Gdata_Photos($client);
 280
 281 $query = new Zend_Gdata_Photos_UserQuery();
 282 $query->setUser("sample.user");
 283 ]]></programlisting>
 284
 285         <para>
 286             各クエリで検索結果を絞り込むために使用するパラメータを取得したり設定したりするには、
 287             それぞれ get(Parameter) および set(Parameter)
 288             を使用して次のようにします。
 289         </para>
 290
 291         <itemizedlist>
 292             <listitem>
 293                 <para>
 294                     <firstterm>Projection</firstterm>
 295                     は、フィードで返されるデータのフォーマットを指定します。
 296                     "api" あるいは "base" のいずれかです。通常は
 297                     "api" を指定することになるでしょう。デフォルトは "api"
 298                     です。
 299                 </para>
 300             </listitem>
 301             <listitem>
 302                 <para>
 303                     <firstterm>Type</firstterm>
 304                     は返される要素の型を指定します。"feed" あるいは "entry"
 305                     のいずれかで、デフォルトは "feed" です。
 306                 </para>
 307             </listitem>
 308             <listitem>
 309                 <para>
 310                     <firstterm>Access</firstterm>
 311                     は、返されるアイテムの可視性を指定します。
 312                     "all"、"public" あるいは "private" のいずれかで、
 313                     デフォルトは "all" です。
 314                     public 以外の要素が返されるのは、
 315                     認証済みのユーザに対するクエリの場合のみです。
 316                 </para>
 317             </listitem>
 318             <listitem>
 319                 <para>
 320                     <firstterm>Tag</firstterm>
 321                     は、返されるアイテムのタグを指定します。
 322                     タグを指定した場合は、その内容のタグがつけられている項目のみを返します。
 323                 </para>
 324             </listitem>
 325             <listitem>
 326                 <para>
 327                     <firstterm>Kind</firstterm>
 328                     は、返される要素の種類を指定します。
 329                     指定した場合は、この値にマッチするエントリのみを返します。
 330                 </para>
 331             </listitem>
 332             <listitem>
 333                 <para>
 334                     <firstterm>ImgMax</firstterm>
 335                     は、返されるエントリの最大画像サイズを指定します。
 336                     この値より小さい画像エントリのみを返します。
 337                 </para>
 338             </listitem>
 339             <listitem>
 340                 <para>
 341                     <firstterm>Thumbsize</firstterm>
 342                     は、返されるエントリのサムサイズを指定します。
 343                     返されたエントリのサムサイズはこの値に等しくなります。
 344                 </para>
 345             </listitem>
 346             <listitem>
 347                 <para>
 348                     <firstterm>User</firstterm>
 349                     は、検索対象のユーザを指定します。
 350                     デフォルトは "default" です。
 351                 </para>
 352             </listitem>
 353             <listitem>
 354                 <para>
 355                     <firstterm>AlbumId</firstterm>
 356                     は、検索対象のアルバムの ID を指定します。
 357                     この要素は、アルバムや写真の問い合わせに対してのみ適用されます。
 358                     写真に対するクエリの場合、
 359                     ここで指定したアルバムに含まれる写真が対象となります。
 360                     アルバム ID は アルバム名とは互いに排他的です。
 361                     一方を指定すると、もう一方は取り消されます。
 362                 </para>
 363             </listitem>
 364             <listitem>
 365                 <para>
 366                     <firstterm>AlbumName</firstterm>
 367                     は、検索対象のアルバムの名前を指定します。
 368                     この要素は、アルバムや写真の問い合わせに対してのみ適用されます。
 369                     写真に対するクエリの場合、
 370                     ここで指定したアルバムに含まれる写真が対象となります。
 371                     アルバム名は アルバム ID とは互いに排他的です。
 372                     一方を指定すると、もう一方は取り消されます。
 373                 </para>
 374             </listitem>
 375             <listitem>
 376                 <para>
 377                     <firstterm>PhotoId</firstterm>
 378                     は、検索対象の写真の ID を指定します。
 379                     この要素は、写真の問い合わせに対してのみ適用されます。
 380                 </para>
 381             </listitem>
 382         </itemizedlist>
 383     </sect2>
 384
 385     <sect2 id="zend.gdata.photos.retrieval">
 386         <title>フィードやエントリの取得</title>
 387         <para>
 388             このサービスには、ユーザやアルバムそして写真に関する
 389             フィードや個々のエントリを取得する機能があります。
 390         </para>
 391
 392         <sect3 id="zend.gdata.photos.user_retrieval">
 393             <title>ユーザの取得</title>
 394             <para>
 395                 このサービスは、ユーザのフィードおよびユーザのコンテンツ一覧の取得をサポートしています。
 396                 指定したユーザが認証済みユーザである場合は、
 397                 "<code>hidden</code>" とマークされているエントリも返されます。
 398             </para>
 399
 400             <para>ユーザのフィードにアクセスするには、ユーザ名を <code>getUserFeed</code> メソッドに渡します。</para>
 401             <programlisting language="php"><![CDATA[
 402 $service = Zend_Gdata_Photos::AUTH_SERVICE_NAME;
 403 $client = Zend_Gdata_ClientLogin::getHttpClient($user, $pass, $service);
 404 $service = new Zend_Gdata_Photos($client);
 405
 406 try {
 407     $userFeed = $service->getUserFeed("sample.user");
 408 } catch (Zend_Gdata_App_Exception $e) {
 409     echo "エラー: " . $e->getMessage();
 410 }
 411 ]]></programlisting>
 412
 413             <para>あるいは、クエリを作成してフィードにアクセスすることもできます。この場合は、まず次のようにします。</para>
 414             <programlisting language="php"><![CDATA[
 415 $service = Zend_Gdata_Photos::AUTH_SERVICE_NAME;
 416 $client = Zend_Gdata_ClientLogin::getHttpClient($user, $pass, $service);
 417 $service = new Zend_Gdata_Photos($client);
 418
 419 $query = new Zend_Gdata_Photos_UserQuery();
 420 $query->setUser("sample.user");
 421
 422 try {
 423     $userFeed = $service->getUserFeed(null, $query);
 424 } catch (Zend_Gdata_App_Exception $e) {
 425     echo "エラー: " . $e->getMessage();
 426 }
 427 ]]></programlisting>
 428
 429             <para>クエリを作成すると、ユーザエントリオブジェクトも取得できるようになります。</para>
 430             <programlisting language="php"><![CDATA[
 431 $service = Zend_Gdata_Photos::AUTH_SERVICE_NAME;
 432 $client = Zend_Gdata_ClientLogin::getHttpClient($user, $pass, $service);
 433 $service = new Zend_Gdata_Photos($client);
 434
 435 $query = new Zend_Gdata_Photos_UserQuery();
 436 $query->setUser("sample.user");
 437 $query->setType("entry");
 438
 439 try {
 440     $userEntry = $service->getUserEntry($query);
 441 } catch (Zend_Gdata_App_Exception $e) {
 442     echo "エラー: " . $e->getMessage();
 443 }
 444 ]]></programlisting>
 445         </sect3>
 446
 447         <sect3 id="zend.gdata.photos.album_retrieval">
 448             <title>アルバムの取得</title>
 449             <para>このサービスには、アルバムのフィードやアルバムのコンテンツ一覧を取得する機能があります。</para>
 450
 451             <para>
 452                 アルバムのフィードにアクセスするには、クエリオブジェクトを作成してそれを <code>getAlbumFeed</code> に渡します。
 453             </para>
 454             <programlisting language="php"><![CDATA[
 455 $service = Zend_Gdata_Photos::AUTH_SERVICE_NAME;
 456 $client = Zend_Gdata_ClientLogin::getHttpClient($user, $pass, $service);
 457 $service = new Zend_Gdata_Photos($client);
 458
 459 $query = new Zend_Gdata_Photos_AlbumQuery();
 460 $query->setUser("sample.user");
 461 $query->setAlbumId("1");
 462
 463 try {
 464     $albumFeed = $service->getAlbumFeed($query);
 465 } catch (Zend_Gdata_App_Exception $e) {
 466     echo "エラー: " . $e->getMessage();
 467 }
 468 ]]></programlisting>
 469
 470             <para>
 471                 あるいは、<code>setAlbumName</code>
 472                 でクエリオブジェクトにアルバム名を指定することもできます。
 473                 アルバム名は アルバム ID とは互いに排他的です。
 474                 一方を指定すると、もう一方は取り消されます。
 475             </para>
 476
 477             <para>クエリを作成すると、アルバムエントリオブジェクトも取得できるようになります。</para>
 478             <programlisting language="php"><![CDATA[
 479 $service = Zend_Gdata_Photos::AUTH_SERVICE_NAME;
 480 $client = Zend_Gdata_ClientLogin::getHttpClient($user, $pass, $service);
 481 $service = new Zend_Gdata_Photos($client);
 482
 483 $query = new Zend_Gdata_Photos_AlbumQuery();
 484 $query->setUser("sample.user");
 485 $query->setAlbumId("1");
 486 $query->setType("entry");
 487
 488 try {
 489     $albumEntry = $service->getAlbumEntry($query);
 490 } catch (Zend_Gdata_App_Exception $e) {
 491     echo "エラー: " . $e->getMessage();
 492 }
 493 ]]></programlisting>
 494         </sect3>
 495
 496         <sect3 id="zend.gdata.photos.photo_retrieval">
 497             <title>写真の取得</title>
 498             <para>このサービスには、写真のフィードやコメント・タグ一覧を取得する機能があります。</para>
 499
 500             <para>
 501                 写真のフィードにアクセスするには、クエリオブジェクトを作成してそれを <code>getPhotoFeed</code> に渡します。
 502             </para>
 503             <programlisting language="php"><![CDATA[
 504 $service = Zend_Gdata_Photos::AUTH_SERVICE_NAME;
 505 $client = Zend_Gdata_ClientLogin::getHttpClient($user, $pass, $service);
 506 $service = new Zend_Gdata_Photos($client);
 507
 508 $query = new Zend_Gdata_Photos_PhotoQuery();
 509 $query->setUser("sample.user");
 510 $query->setAlbumId("1");
 511 $query->setPhotoId("100");
 512
 513 try {
 514     $photoFeed = $service->getPhotoFeed($query);
 515 } catch (Zend_Gdata_App_Exception $e) {
 516     echo "エラー: " . $e->getMessage();
 517 }
 518 ]]></programlisting>
 519
 520             <para>クエリを作成すると、写真エントリオブジェクトも取得できるようになります。</para>
 521             <programlisting language="php"><![CDATA[
 522 $service = Zend_Gdata_Photos::AUTH_SERVICE_NAME;
 523 $client = Zend_Gdata_ClientLogin::getHttpClient($user, $pass, $service);
 524 $service = new Zend_Gdata_Photos($client);
 525
 526 $query = new Zend_Gdata_Photos_PhotoQuery();
 527 $query->setUser("sample.user");
 528 $query->setAlbumId("1");
 529 $query->setPhotoId("100");
 530 $query->setType("entry");
 531
 532 try {
 533     $photoEntry = $service->getPhotoEntry($query);
 534 } catch (Zend_Gdata_App_Exception $e) {
 535     echo "エラー: " . $e->getMessage();
 536 }
 537 ]]></programlisting>
 538         </sect3>
 539
 540         <sect3 id="zend.gdata.photos.comment_retrieval">
 541             <title>コメントの取得</title>
 542             <para>
 543                 このサービスには、さまざまな形式のフィードからのコメントの取得をサポートしています。
 544                 クエリが返す結果の種類として "comment" を指定することで、
 545                 指定したユーザやアルバム、写真に関連づけられたコメントを取得できるようになります。
 546             </para>
 547
 548             <para>指定した写真のコメントを処理するには、次のようにします。</para>
 549             <programlisting language="php"><![CDATA[
 550 $service = Zend_Gdata_Photos::AUTH_SERVICE_NAME;
 551 $client = Zend_Gdata_ClientLogin::getHttpClient($user, $pass, $service);
 552 $service = new Zend_Gdata_Photos($client);
 553
 554 $query = new Zend_Gdata_Photos_PhotoQuery();
 555 $query->setUser("sample.user");
 556 $query->setAlbumId("1");
 557 $query->setPhotoId("100");
 558 $query->setKind("comment");
 559
 560 try {
 561     $photoFeed = $service->getPhotoFeed($query);
 562
 563     foreach ($photoFeed as $entry) {
 564         if ($entry instanceof Zend_Gdata_Photos_CommentEntry) {
 565             // コメントに対して何らかの処理をします
 566         }
 567     }
 568 } catch (Zend_Gdata_App_Exception $e) {
 569     echo "エラー: " . $e->getMessage();
 570 }
 571 ]]></programlisting>
 572         </sect3>
 573
 574         <sect3 id="zend.gdata.photos.tag_retrieval">
 575             <title>タグの取得</title>
 576             <para>
 577                 このサービスには、さまざまな形式のフィードからのタグの取得をサポートしています。
 578                 クエリが返す結果の種類として "tag" を指定することで、
 579                 指定した写真に関連づけられたタグを取得できるようになります。
 580             </para>
 581
 582             <para>指定した写真のタグを処理するには、次のようにします。</para>
 583             <programlisting language="php"><![CDATA[
 584 $service = Zend_Gdata_Photos::AUTH_SERVICE_NAME;
 585 $client = Zend_Gdata_ClientLogin::getHttpClient($user, $pass, $service);
 586 $service = new Zend_Gdata_Photos($client);
 587
 588 $query = new Zend_Gdata_Photos_PhotoQuery();
 589 $query->setUser("sample.user");
 590 $query->setAlbumId("1");
 591 $query->setPhotoId("100");
 592 $query->setKind("tag");
 593
 594 try {
 595     $photoFeed = $service->getPhotoFeed($query);
 596
 597     foreach ($photoFeed as $entry) {
 598         if ($entry instanceof Zend_Gdata_Photos_TagEntry) {
 599             // タグに対して何らかの処理をします
 600         }
 601     }
 602 } catch (Zend_Gdata_App_Exception $e) {
 603     echo "エラー: " . $e->getMessage();
 604 }
 605 ]]></programlisting>
 606         </sect3>
 607
 608     </sect2>
 609
 610     <sect2 id="zend.gdata.photos.creation">
 611         <title>エントリの作成</title>
 612         <para>このサービスには、アルバムや写真、コメント、そしてタグを作成する機能があります。</para>
 613
 614         <sect3 id="zend.gdata.photos.album_creation">
 615             <title>アルバムの作成</title>
 616             <para>このサービスは、認証済みユーザ用の新しいアルバムの作成をサポートしています。</para>
 617             <programlisting language="php"><![CDATA[
 618 $service = Zend_Gdata_Photos::AUTH_SERVICE_NAME;
 619 $client = Zend_Gdata_ClientLogin::getHttpClient($user, $pass, $service);
 620 $service = new Zend_Gdata_Photos($client);
 621
 622 $entry = new Zend_Gdata_Photos_AlbumEntry();
 623 $entry->setTitle($service->newTitle("test album"));
 624
 625 $service->insertAlbumEntry($entry);
 626 ]]></programlisting>
 627         </sect3>
 628
 629         <sect3 id="zend.gdata.photos.photo_creation">
 630             <title>写真の作成</title>
 631             <para>このサービスは、認証済みユーザ用の新しい写真の作成をサポートしています。</para>
 632             <programlisting language="php"><![CDATA[
 633 $service = Zend_Gdata_Photos::AUTH_SERVICE_NAME;
 634 $client = Zend_Gdata_ClientLogin::getHttpClient($user, $pass, $service);
 635 $service = new Zend_Gdata_Photos($client);
 636
 637 // $photo は、HTML フォームからアップロードされたファイルの名前です
 638
 639 $fd = $service->newMediaFileSource($photo["tmp_name"]);
 640 $fd->setContentType($photo["type"]);
 641
 642 $entry = new Zend_Gdata_Photos_PhotoEntry();
 643 $entry->setMediaSource($fd);
 644 $entry->setTitle($service->newTitle($photo["name"]));
 645
 646 $albumQuery = new Zend_Gdata_Photos_AlbumQuery;
 647 $albumQuery->setUser("sample.user");
 648 $albumQuery->setAlbumId("1");
 649
 650 $albumEntry = $service->getAlbumEntry($albumQuery);
 651
 652 $service->insertPhotoEntry($entry, $albumEntry);
 653 ]]></programlisting>
 654         </sect3>
 655
 656         <sect3 id="zend.gdata.photos.comment_creation">
 657             <title>コメントの作成</title>
 658             <para>このサービスは、写真への新しいコメントの作成をサポートしています。</para>
 659             <programlisting language="php"><![CDATA[
 660 $service = Zend_Gdata_Photos::AUTH_SERVICE_NAME;
 661 $client = Zend_Gdata_ClientLogin::getHttpClient($user, $pass, $service);
 662 $service = new Zend_Gdata_Photos($client);
 663
 664 $entry = new Zend_Gdata_Photos_CommentEntry();
 665 $entry->setTitle($service->newTitle("comment"));
 666 $entry->setContent($service->newContent("comment"));
 667
 668 $photoQuery = new Zend_Gdata_Photos_PhotoQuery;
 669 $photoQuery->setUser("sample.user");
 670 $photoQuery->setAlbumId("1");
 671 $photoQuery->setPhotoId("100");
 672 $photoQuery->setType('entry');
 673
 674 $photoEntry = $service->getPhotoEntry($photoQuery);
 675
 676 $service->insertCommentEntry($entry, $photoEntry);
 677 ]]></programlisting>
 678         </sect3>
 679
 680         <sect3 id="zend.gdata.photos.tag_creation">
 681             <title>タグの作成</title>
 682             <para>このサービスは、写真への新しいタグの作成をサポートしています。</para>
 683             <programlisting language="php"><![CDATA[
 684 $service = Zend_Gdata_Photos::AUTH_SERVICE_NAME;
 685 $client = Zend_Gdata_ClientLogin::getHttpClient($user, $pass, $service);
 686 $service = new Zend_Gdata_Photos($client);
 687
 688 $entry = new Zend_Gdata_Photos_TagEntry();
 689 $entry->setTitle($service->newTitle("tag"));
 690
 691 $photoQuery = new Zend_Gdata_Photos_PhotoQuery;
 692 $photoQuery->setUser("sample.user");
 693 $photoQuery->setAlbumId("1");
 694 $photoQuery->setPhotoId("100");
 695 $photoQuery->setType('entry');
 696
 697 $photoEntry = $service->getPhotoEntry($photoQuery);
 698
 699 $service->insertTagEntry($entry, $photoEntry);
 700 ]]></programlisting>
 701         </sect3>
 702
 703     </sect2>
 704
 705     <sect2 id="zend.gdata.photos.deletion">
 706         <title>エントリの削除</title>
 707         <para>このサービスには、アルバムや写真、コメント、そしてタグを削除する機能があります。</para>
 708
 709         <sect3 id="zend.gdata.photos.album_deletion">
 710             <title>アルバムの削除</title>
 711             <para>このサービスは、認証済みユーザ用のアルバムの削除をサポートしています。</para>
 712             <programlisting language="php"><![CDATA[
 713 $service = Zend_Gdata_Photos::AUTH_SERVICE_NAME;
 714 $client = Zend_Gdata_ClientLogin::getHttpClient($user, $pass, $service);
 715 $service = new Zend_Gdata_Photos($client);
 716
 717 $albumQuery = new Zend_Gdata_Photos_AlbumQuery;
 718 $albumQuery->setUser("sample.user");
 719 $albumQuery->setAlbumId("1");
 720 $albumQuery->setType('entry');
 721
 722 $entry = $service->getAlbumEntry($albumQuery);
 723
 724 $service->deleteAlbumEntry($entry, true);
 725 ]]></programlisting>
 726         </sect3>
 727
 728         <sect3 id="zend.gdata.photos.photo_deletion">
 729             <title>写真の削除</title>
 730             <para>このサービスは、認証済みユーザ用の写真の削除をサポートしています。</para>
 731             <programlisting language="php"><![CDATA[
 732 $service = Zend_Gdata_Photos::AUTH_SERVICE_NAME;
 733 $client = Zend_Gdata_ClientLogin::getHttpClient($user, $pass, $service);
 734 $service = new Zend_Gdata_Photos($client);
 735
 736 $photoQuery = new Zend_Gdata_Photos_PhotoQuery;
 737 $photoQuery->setUser("sample.user");
 738 $photoQuery->setAlbumId("1");
 739 $photoQuery->setPhotoId("100");
 740 $photoQuery->setType('entry');
 741
 742 $entry = $service->getPhotoEntry($photoQuery);
 743
 744 $service->deletePhotoEntry($entry, true);
 745 ]]></programlisting>
 746         </sect3>
 747
 748         <sect3 id="zend.gdata.photos.comment_deletion">
 749             <title>コメントの削除</title>
 750             <para>このサービスは、認証済みユーザのコメントの削除をサポートしています。</para>
 751             <programlisting language="php"><![CDATA[
 752 $service = Zend_Gdata_Photos::AUTH_SERVICE_NAME;
 753 $client = Zend_Gdata_ClientLogin::getHttpClient($user, $pass, $service);
 754 $service = new Zend_Gdata_Photos($client);
 755
 756 $photoQuery = new Zend_Gdata_Photos_PhotoQuery;
 757 $photoQuery->setUser("sample.user");
 758 $photoQuery->setAlbumId("1");
 759 $photoQuery->setPhotoId("100");
 760 $photoQuery->setType('entry');
 761
 762 $path = $photoQuery->getQueryUrl() . '/commentid/' . "1000";
 763
 764 $entry = $service->getCommentEntry($path);
 765
 766 $service->deleteCommentEntry($entry, true);
 767 ]]></programlisting>
 768         </sect3>
 769
 770         <sect3 id="zend.gdata.photos.tag_deletion">
 771             <title>タグの削除</title>
 772             <para>このサービスは、認証済みユーザのタグの削除をサポートしています。</para>
 773             <programlisting language="php"><![CDATA[
 774 $service = Zend_Gdata_Photos::AUTH_SERVICE_NAME;
 775 $client = Zend_Gdata_ClientLogin::getHttpClient($user, $pass, $service);
 776 $service = new Zend_Gdata_Photos($client);
 777
 778 $photoQuery = new Zend_Gdata_Photos_PhotoQuery;
 779 $photoQuery->setUser("sample.user");
 780 $photoQuery->setAlbumId("1");
 781 $photoQuery->setPhotoId("100");
 782 $photoQuery->setKind("tag");
 783 $query = $photoQuery->getQueryUrl();
 784
 785 $photoFeed = $service->getPhotoFeed($query);
 786
 787 foreach ($photoFeed as $entry) {
 788     if ($entry instanceof Zend_Gdata_Photos_TagEntry) {
 789         if ($entry->getContent() == $tagContent) {
 790             $tagEntry = $entry;
 791         }
 792     }
 793 }
 794
 795 $service->deleteTagEntry($tagEntry, true);
 796 ]]></programlisting>
 797         </sect3>
 798
 799         <sect3 id="zend.gdata.photos.optimistic_concurrenty">
 800             <title>楽観的な同時並行性 (削除時の注意)</title>
 801             <para>
 802                 Picasa Web Albums サービスを含めた GData のフィードは、
 803                 楽観的な同時並行性 (optimistic concurrency) を実装しています。
 804                 これは、変更内容を不意に上書きしてしまうことを防ぐバージョン管理システムです。
 805                 サービスクラスでエントリを削除する際に、
 806                 もし最後に取得した後でそのエントリが変更されていた場合は例外がスローされます。
 807                 ただし明示的にその他の設定をしている場合は別です
 808                 (この場合、更新後のエントリに対して削除を試みます)。
 809             </para>
 810
 811             <para>
 812                 削除時のバージョン管理の処理方法については <code>deleteAlbumEntry</code>
 813                 で見ることができます。
 814             </para>
 815             <programlisting language="php"><![CDATA[
 816 // $album は、削除したい albumEntry です
 817 try {
 818     $this->delete($album);
 819 } catch (Zend_Gdata_App_HttpException $e) {
 820     if ($e->getMessage()->getStatus() === 409) {
 821         $entry =
 822             new Zend_Gdata_Photos_AlbumEntry($e->getMessage()->getBody());
 823         $this->delete($entry->getLink('edit')->href);
 824     } else {
 825         throw $e;
 826     }
 827 }
 828 ]]></programlisting>
 829         </sect3>
 830
 831     </sect2>
 832 </sect1>