repo_zf1/documentation/manual/ja/module_specs/Zend_Gdata_Spreadsheets.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<!-- EN-Revision: 17175 -->
<sect1 id="zend.gdata.spreadsheets">
    <title>Google Spreadsheets の使用法</title>

    <para>
        Google Spreadsheets データ <acronym>API</acronym> を使用すると、
        スプレッドシートの中身を Google データ <acronym>API</acronym> フィード形式で閲覧したり
        それを更新したりすることができるようになります。
        あるユーザのスプレッドシートの一覧を取得したり、
        既存のスプレッドシートのワークシートを編集・削除したり、
        ワークシートの中身を問い合わせたりといったことも可能です。
    </para>

    <para>
        Google Spreadsheets <acronym>API</acronym> についての詳細な情報は
        <ulink url="http://code.google.com/apis/spreadsheets/overview.html">http://code.google.com/apis/spreadsheets/overview.html</ulink>
        を参照ください。
    </para>

    <sect2 id="zend.gdata.spreadsheets.creating">
        <title>スプレッドシートの作成</title>
        <para>
            Spreadsheets データ <acronym>API</acronym> は、現在はプログラム上でのスプレッドシートの
            作成・削除はサポートしていません。
        </para>
    </sect2>

    <sect2 id="zend.gdata.spreadsheets.listspreadsheets">
        <title>スプレッドシートの一覧の取得</title>
        <para>
            特定のユーザのスプレッドシートの一覧を取得するには
            Spredsheets サービスの <code>getSpreadsheetFeed</code> メソッドを使用します。
            このサービスが返す <classname>Zend_Gdata_Spreadsheets_SpreadsheetFeed</classname>
            オブジェクトに、認証済みユーザのスプレッドシート一覧が格納されます。
        </para>

        <programlisting language="php"><![CDATA[
$service = Zend_Gdata_Spreadsheets::AUTH_SERVICE_NAME;
$client = Zend_Gdata_ClientLogin::getHttpClient($user, $pass, $service);
$spreadsheetService = new Zend_Gdata_Spreadsheets($client);
$feed = $spreadsheetService->getSpreadsheetFeed();
]]></programlisting>
    </sect2>

     <sect2 id="zend.gdata.spreadsheets.listworksheets">
        <title>ワークシートの一覧の取得</title>
        <para>
            ひとつのスプレッドシートの中には複数のワークシートがあります。
            各スプレッドシートは、その内部のすべてのワークシートをあらわすメタフィード含んでいます。
        </para>

        <para>
            スプレッドシートのキー
            (すでに取得済みの <classname>Zend_Gdata_Spreadsheets_SpreadsheetEntry</classname>
            オブジェクトの &lt;id&gt;)
            を指定すると、そのスプレッドシートのワークシート一覧を含むフィードを取得できます。
        </para>

        <programlisting language="php"><![CDATA[
$query = new Zend_Gdata_Spreadsheets_DocumentQuery();
$query->setSpreadsheetKey($spreadsheetKey);
$feed = $spreadsheetService->getWorksheetFeed($query);
]]></programlisting>

        <para>
            この結果である <classname>Zend_Gdata_Spreadsheets_WorksheetFeed</classname>
            オブジェクトは、サーバからのレスポンスを表します。
            その他の場合と同じように、このフィードには
            <classname>Zend_Gdata_Spreadsheets_WorksheetEntry </classname> オブジェクト
            (<code>$feed->entries</code>) の一覧が含まれます。
            個々のオブジェクトがひとつのワークシートを表します。
        </para>

    </sect2>

    <sect2 id="zend.gdata.spreadsheets.listfeeds">
        <title>リストベースのフィードの扱い</title>
        <para>
            ワークシートには通常複数の行が含まれ、各行には複数のセルが存在します。
            ワークシートのデータを取得するには、リストベースのフィード
            (各エントリがひとつの行を表す) かあるいはセルベースのフィード
            (各エントリがひとつのセルを表す) を使用します。
            セルベースのフィードについては、
            「<link linkend="zend.gdata.spreadsheets.cellfeeds">セルベースのフィードの扱い</link>」
            を参照ください。
        </para>

        <para>
            以下の節では、リストベースのフィードを取得して行を追加し、
            さまざまなパラメータを指定してクエリを送信する方法を説明します。
        </para>

        <para>
            リストフィードでは、スプレッドシート内のデータについていくつかの前提条件があります。
        </para>

        <para>
            リストフィードでは、ワークシートの最初の行をヘッダ行として扱います。
            Spreadsheets は、ヘッダ行のセルの名前をもとにして
            <acronym>XML</acronym> 要素を動的に作成します。
            Gdata フィードを提供したいユーザは、
            ワークシートの一行目にカラムヘッダ以外を書いてはいけません。
        </para>

        <para>
            リストフィードには、先頭行の次の行から最初に空行が現れるまでのすべての行が含まれます。
            空行が登場した時点でデータセットが終了します。
            期待通りのデータがフィードに含まれていない場合は、
            ワークシートの内容を確認して途中に空行がないかどうかを見てみましょう。
            特に、二行目が空行だったりするとリストフィードには一切データが含まれなくなります。
        </para>

        <para>
            リストフィードの行は、そのワークシートが持っているのと同じだけのカラムを保持します。
        </para>

        <sect3 id="zend.gdata.spreadsheets.listfeeds.get">
            <title>リストベースのフィードの取得</title>
            <para>
                ワークシートのリストフィードを取得するには、Spreadsheets サービスの
                <code>getListFeed</code> メソッドを使用します。
            </para>

            <programlisting language="php"><![CDATA[
$query = new Zend_Gdata_Spreadsheets_ListQuery();
$query->setSpreadsheetKey($spreadsheetKey);
$query->setWorksheetId($worksheetId);
$listFeed = $spreadsheetService->getListFeed($query);
]]></programlisting>

            <para>
                その結果得られた <classname>Zend_Gdata_Spreadsheets_ListFeed</classname>
                オブジェクトである <varname>$listfeed</varname> が、サーバからのレスポンスを表します。
                またこのフィードは <classname>Zend_Gdata_Spreadsheets_ListEntry</classname>
                オブジェクトの配列 (<code>$listFeed->entries</code>)
                を含んでおり、この配列の各要素がワークシートのひとつの行を表します。
            </para>

            <para>
              各 <classname>Zend_Gdata_Spreadsheets_ListEntry</classname> には配列
              <code>custom</code> が含まれ、これがその行のデータを保持します。
              この配列の内容を取り出して表示するには次のようにします。
            </para>

            <programlisting language="php"><![CDATA[
$rowData = $listFeed->entries[1]->getCustom();
foreach($rowData as $customEntry) {
  echo $customEntry->getColumnName() . " = " . $customEntry->getText();
}
]]></programlisting>

            <para>
              もうひとつの配列である <code>customByName</code>
              を使用すると、エントリのセルに対して名前を指定して直接アクセスできるようになります。
              これは、特定のヘッダにアクセスしたい場合などに便利です。
            </para>

            <programlisting language="php"><![CDATA[
$customEntry = $listFeed->entries[1]->getCustomByName('my_heading');
echo $customEntry->getColumnName() . " = " . $customEntry->getText();
]]></programlisting>
        </sect3>

        <sect3 id="zend.gdata.spreadsheets.listfeeds.reverse">
            <title>逆順での行の並べ替え</title>

            <para>
                デフォルトでは、フィード内の行の並び順は GUI
                で見たときの行の並び順と同じです。つまり行番号順ということです。
                行を逆順で取得するには、<classname>Zend_Gdata_Spreadsheets_ListQuery</classname>
                オブジェクトの reverse プロパティを true に設定します。
            </para>

            <programlisting language="php"><![CDATA[
$query = new Zend_Gdata_Spreadsheets_ListQuery();
$query->setSpreadsheetKey($spreadsheetKey);
$query->setWorksheetId($worksheetId);
$query->setReverse('true');
$listFeed = $spreadsheetService->getListFeed($query);
]]></programlisting>

            <para>
                もしワークシート内での位置ではなく特定のカラムの値で
                (あるいはその逆順で) 並べ替えたい場合は、
                <classname>Zend_Gdata_Spreadsheets_ListQuery</classname>
                オブジェクトの <code>orderby</code> の値を
                <code>column:&lt;そのカラムのヘッダ&gt;</code>
                とします。
            </para>
        </sect3>

        <sect3 id="zend.gdata.spreadsheets.listfeeds.sq">
            <title>構造化問い合わせ</title>

            <para>
                <classname>Zend_Gdata_Spreadsheets_ListQuery</classname> の
                <code>sq</code> を設定することで、
                指定した条件を満たすエントリだけのフィードを得ることができます。
                たとえば、個人データを記録したワークシートがあるとしましょう。
                ひとつの行に一人のデータが記録されています。
                この中から名前が "John" で年齢が 25 才より大きい人のデータだけを抜き出したい場合は、
                次のように <code>sq</code> を設定します。
            </para>

            <programlisting language="php"><![CDATA[
$query = new Zend_Gdata_Spreadsheets_ListQuery();
$query->setSpreadsheetKey($spreadsheetKey);
$query->setWorksheetId($worksheetId);
$query->setSpreadsheetQuery('name=John and age>25');
$listFeed = $spreadsheetService->getListFeed($query);
]]></programlisting>
        </sect3>

        <sect3 id="zend.gdata.spreadsheets.listfeeds.addrow">
            <title>行の追加</title>

            <para>
                スプレッドシートに行を追加するには、Spreadsheet サービスの
                <code>insertRow</code> メソッドを使用します。
            </para>

            <programlisting language="php"><![CDATA[
$insertedListEntry = $spreadsheetService->insertRow($rowData,
                                                    $spreadsheetKey,
                                                    $worksheetId);
]]></programlisting>

            <para>
                <varname>$rowData</varname> パラメータには、
                カラムのキーとその値を関連付けた配列を指定します。
                このメソッドは、追加した行に対応する
                <classname>Zend_Gdata_Spreadsheets_SpreadsheetsEntry</classname>
                オブジェクトを返します。
            </para>

            <para>
                Spreadsheets は、リストベースのフィードの一番最後の行の直後に新しい行を追加します。
                つまり、最初に登場する空行の直前ということです。
            </para>
        </sect3>

        <sect3 id="zend.gdata.spreadsheets.listfeeds.editrow">
            <title>行の編集</title>

            <para>
                <classname>Zend_Gdata_Spreadsheets_ListEntry</classname>
                オブジェクトを取得したら、Spreadsheet サービスの
                <code>updateRow</code> メソッドを使用してその中身を更新することができます。
            </para>

            <programlisting language="php"><![CDATA[
$updatedListEntry = $spreadsheetService->updateRow($oldListEntry,
                                                   $newRowData);
]]></programlisting>

            <para>
                <varname>$oldListEntry</varname> パラメータには、更新するエントリを指定します。
                <varname>$newRowData</varname> はカラムのキーと値を関連付けた配列です。
                これを新しいデータとして使用します。このメソッドは、更新した行に対応する
                <classname>Zend_Gdata_Spreadsheets_SpreadsheetsEntry</classname>
                オブジェクトを返します。
            </para>
        </sect3>

        <sect3 id="zend.gdata.spreadsheets.listfeeds.deleterow">
            <title>行の削除</title>

            <para>
                行を削除するには、単に
                <classname>Zend_Gdata_Spreadsheets</classname> オブジェクトの
                <code>deleteRow</code> メソッドをコールするだけです。
                削除したい既存のエントリを指定します。
            </para>

            <programlisting language="php"><![CDATA[
$spreadsheetService->deleteRow($listEntry);
]]></programlisting>

            <para>
                あるいは、そのエントリ自身の <code>delete</code>
                メソッドをコールするという手もあります。
            </para>

            <programlisting language="php"><![CDATA[
$listEntry->delete();
]]></programlisting>
        </sect3>

    </sect2>

    <sect2 id="zend.gdata.spreadsheets.cellfeeds">
        <title>セルベースのフィードの扱い</title>

        <para>
            セルベースのフィードでは、各エントリがひとつのセルを表します。
        </para>

        <para>
            ひとつのワークシートで
            セルベースのフィードとリストベースのフィードを同時に使用するのはやめておきましょう。
        </para>

        <sect3 id="zend.gdata.spreadsheets.cellfeeds.get">
            <title>セルベースのフィードの取得</title>
            <para>
                ワークシートのセルフィードを取得するには、Spreadsheets サービスの
                <code>getCellFeed</code> メソッドを使用します。
            </para>

            <programlisting language="php"><![CDATA[
$query = new Zend_Gdata_Spreadsheets_CellQuery();
$query->setSpreadsheetKey($spreadsheetKey);
$query->setWorksheetId($worksheetId);
$cellFeed = $spreadsheetService->getCellFeed($query);
]]></programlisting>

            <para>
                その結果得られた <classname>Zend_Gdata_Spreadsheets_CellFeed</classname>
                オブジェクトである <varname>$cellFeed</varname> が、サーバからのレスポンスを表します。
                またこのフィードは <classname>Zend_Gdata_Spreadsheets_CellEntry</classname>
                オブジェクトの配列 (<code>$cellFeed>entries</code>)
                を含んでおり、この配列の各要素がワークシートのひとつのセルを表します。
                この情報を表示するには次のようにします。
            </para>

            <programlisting language="php"><![CDATA[
foreach($cellFeed as $cellEntry) {
  $row = $cellEntry->cell->getRow();
  $col = $cellEntry->cell->getColumn();
  $val = $cellEntry->cell->getText();
  echo "$row, $col = $val\n";
}
]]></programlisting>

        </sect3>

        <sect3 id="zend.gdata.spreadsheets.cellfeeds.cellrangequery">
            <title>セルの範囲の問い合わせ</title>

            <para>
                ワークシートの最初のカラムのセルを取得したいとしましょう。
                次のようにすると、最初のカラムだけを含むセルフィードを取得することができます。
            </para>

            <programlisting language="php"><![CDATA[
$query = new Zend_Gdata_Spreadsheets_CellQuery();
$query->setMinCol(1);
$query->setMaxCol(1);
$query->setMinRow(2);
$feed = $spreadsheetService->getCellsFeed($query);
]]></programlisting>

            <para>
                これは、二行目以降のデータの最初のカラムのみのデータを返します。
            </para>
        </sect3>

        <sect3 id="zend.gdata.spreadsheets.cellfeeds.updatecell">
            <title>セルの内容の変更</title>

            <para>
                セルの内容を変更するには、
                行、カラム、そして新しい値を指定して
                <code>updateCell</code> をコールします。
            </para>

            <programlisting language="php"><![CDATA[
$updatedCell = $spreadsheetService->updateCell($row,
                                               $col,
                                               $inputValue,
                                               $spreadsheetKey,
                                               $worksheetId);
]]></programlisting>

            <para>
                新しいデータが、ワークシートの指定した位置に配置されます。
                指定したセルに既にデータが存在する場合は、上書きされます。
                注意: <code>updateCell</code> を使用すると、
                もともとそのセルが空であった場合もデータを更新します。
            </para>
        </sect3>

    </sect2>

</sect1>