repo_zf1/documentation/manual/de/module_specs/Zend_Service_WindowsAzure_Table.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 19991 -->
<!-- Reviewed: no -->
<sect1 id="zend.service.windowsazure.storage.table">
    <title>Zend_Service_WindowsAzure_Storage_Table</title>

    <para>
        Der Table Service bietet einen strukturierten Speicher in der Form von Tabellen.
    </para>

    <para>
        Tabellen Speicher wird von Windows Azure als REST API angeboten die von der Klasse
        <classname>Zend_Service_WindowsAzure_Storage_Table</classname> umhüllt ist um ein natives
        PHP Interface zum Speicher Konto zu bieten.
    </para>

    <para>
        Dieses Thema zeigt einige Beispiele der Verwendung der Klasse
        <classname>Zend_Service_WindowsAzure_Storage_Table</classname>. Andere Features sind im
        Download Paket enthalten sowie in den detailierten API Dokumentationen dieser Features.
    </para>

    <para>
        Es ist zu beachten das bei der Entwicklung der Tabellen Speicher (in der SDK von Windows
        Azure) nicht alle Features unterstützt welche von dieser API angeboten werden. Deshalb sind
        die Beispiele welche auf dieser Seite aufgeführt sind, dazu gedacht auf Windows Azure
        Produktions Tabellen Speichern verwendet zu werden.
    </para>

    <sect2 id="zend.service.windowsazure.storage.table.api">
        <title>Operationen auf Tabellen</title>

        <para>
            Dieses Thema zeigt einige Beispiele für Operationen welche auf Tabellen ausgeführt
            werden können.
        </para>

        <sect3 id="zend.service.windowsazure.storage.table.api.create">
            <title>Erstellung einer Tabelle</title>

            <para>
                Bei Verwendung des folgenden Codes, kann eine Tabelle auf dem Windows Azure
                Produktions Tabellen Speicher erstellt werden.
            </para>

            <example id="zend.service.windowsazure.storage.table.api.create.example">
                <title>Erstellen einer Tabelle</title>

                <programlisting language="php"><![CDATA[
$storageClient = new Zend_Service_WindowsAzure_Storage_Table(
    'table.core.windows.net', 'myaccount', 'myauthkey'
);
$result = $storageClient->createTable('testtable');

echo 'Der neue Name der Tabelle ist: ' . $result->Name;
]]></programlisting>
            </example>
        </sect3>

        <sect3 id="zend.service.windowsazure.storage.table.api.list">
            <title>Ausgeben aller Tabellen</title>

            <para>
                Bei Verwendung des folgendes Codes, kann eine Liste alle Tabellen im Windows Azure
                Produktions Tabellen Speicher abgefragt werden.
            </para>

            <example id="zend.service.windowsazure.storage.table.api.list.example">
                <title>Ausgeben aller Tabellen</title>

                <programlisting language="php"><![CDATA[
$storageClient = new Zend_Service_WindowsAzure_Storage_Table(
    'table.core.windows.net', 'myaccount', 'myauthkey'
);
$result = $storageClient->listTables();
foreach ($result as $table) {
    echo 'Der Name der Tabelle ist: ' . $table->Name . "\r\n";
}
]]></programlisting>
            </example>
        </sect3>
    </sect2>

    <sect2 id="zend.service.windowsazure.storage.table.entities">
        <title>Operationen auf Entitäten</title>

        <para>
            Tabellen speichern Daten als Sammlung von Entitäten. Entitäten sind so ähnlich wie
            Zeilen. Eine Entität hat einen primären Schlüssel und ein Set von Eigenschaften. Eine
            Eigenschaft ist ein benanntes, Typ-Werte Paar, ähnlich einer Spalte.
        </para>

        <para>
            Der Tabellen Service erzwingt kein Schema für Tabellen, deshalb können zwei Entitäten in
            der selben Tabelle unterschiedliche Sets von Eigenschaften haben. Entwickler können
            auswählen das ein Schema auf Seite des Clients erzwungen wird. Eine Tabelle kann eine
            beliebige Anzahl an Entitäten enthalten.
        </para>

        <para>
            <classname>Zend_Service_WindowsAzure_Storage_Table</classname> bietet 2 Wege um mit
            Entitäten zu arbeiten:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    Erzwungenes Schema
                </para>
            </listitem>

            <listitem>
                <para>
                    Nicht erzwungenes Schema
                </para>
            </listitem>
        </itemizedlist>

        <para>
            Alle Beispiel verwenden die folgende erwzungene Schema Klasse.
        </para>

        <example id="zend.service.windowsazure.storage.table.entities.schema">
            <title>Erzwungenes Schema welches in Beispielen verwendet wird</title>

            <programlisting language="php"><![CDATA[
class SampleEntity extends Zend_Service_WindowsAzure_Storage_TableEntity
{
    /**
    * @azure Name
    */
    public $Name;

    /**
    * @azure Age Edm.Int64
    */
    public $Age;

    /**
    * @azure Visible Edm.Boolean
    */
    public $Visible = false;
}
]]></programlisting>
        </example>

        <para>
            Note that if no schema class is passed into table storage methods,
            <classname>Zend_Service_WindowsAzure_Storage_Table</classname> automatically works with
            <classname>Zend_Service_WindowsAzure_Storage_DynamicTableEntity</classname>.
        </para>

        <sect3 id="zend.service.windowsazure.storage.table.entities.enforced">
            <title>Enforced schema entities</title>

            <para>
                To enforce a schema on the client side using the
                <classname>Zend_Service_WindowsAzure_Storage_Table</classname> class, you can create
                a class which inherits
                <classname>Zend_Service_WindowsAzure_Storage_TableEntity</classname>.  This class
                provides some basic functionality for the
                <classname>Zend_Service_WindowsAzure_Storage_Table</classname> class to work with a
                client-side schema.
            </para>

            <para>
                Base properties provided by
                <classname>Zend_Service_WindowsAzure_Storage_TableEntity</classname> are:
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                        PartitionKey (exposed through <methodname>getPartitionKey()</methodname> and
                        <methodname>setPartitionKey()</methodname>)
                    </para>
                </listitem>

                <listitem>
                    <para>
                        RowKey (exposed through <methodname>getRowKey()</methodname> and
                        <methodname>setRowKey()</methodname>)
                    </para>
                </listitem>

                <listitem>
                    <para>
                        Timestamp (exposed through <methodname>getTimestamp()</methodname> and
                        <methodname>setTimestamp()</methodname>)
                    </para>
                </listitem>

                <listitem>
                    <para>
                        Etag value (exposed through <methodname>getEtag()</methodname> and
                        <methodname>setEtag()</methodname>)
                    </para>
                </listitem>
            </itemizedlist>

            <para>
                Here's a sample class inheriting
                <classname>Zend_Service_WindowsAzure_Storage_TableEntity</classname>:
            </para>

            <example id="zend.service.windowsazure.storage.table.entities.enforced.schema">
                <title>Sample enforced schema class</title>

                <programlisting language="php"><![CDATA[
class SampleEntity extends Zend_Service_WindowsAzure_Storage_TableEntity
{
    /**
     * @azure Name
     */
    public $Name;

    /**
     * @azure Age Edm.Int64
     */
    public $Age;

    /**
     * @azure Visible Edm.Boolean
     */
    public $Visible = false;
}
]]></programlisting>
            </example>

            <para>
                The <classname>Zend_Service_WindowsAzure_Storage_Table</classname> class will map
                any class inherited from
                <classname>Zend_Service_WindowsAzure_Storage_TableEntity</classname> to Windows
                Azure table storage entities with the correct data type and property name. All there
                is to storing a property in Windows Azure is adding a docblock comment to a public
                property or public getter/setter, in the following format:
            </para>

            <example id="zend.service.windowsazure.storage.table.entities.enforced.schema-property">
                <title>Enforced property</title>

                <programlisting language="php"><![CDATA[
/**
 * @azure <property name in Windows Azure> <optional property type>
 */
public $<property name in PHP>;
]]></programlisting>
            </example>

            <para>
                Let's see how to define a propety "Age" as an integer on Windows Azure table
                storage:
            </para>

            <example id="zend.service.windowsazure.storage.table.entities.enforced.schema-property-sample">
                <title>Sample enforced property</title>

                <programlisting language="php"><![CDATA[
/**
 * @azure Age Edm.Int64
 */
public $Age;
]]></programlisting>
            </example>

            <para>
                Note that a property does not necessarily have to be named the same on Windows Azure
                table storage. The Windows Azure table storage property name can be defined as well
                as the type.
            </para>

            <para>
                The following data types are supported:
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                        <constant>Edm.Binary</constant> - An array of bytes up to 64 KB in size.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <constant>Edm.Boolean</constant> - A boolean value.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <constant>Edm.DateTime</constant> - A 64-bit value expressed as Coordinated
                        Universal Time (UTC). The supported DateTime range begins from 12:00
                        midnight, January 1, 1601 A.D. (C.E.), Coordinated Universal Time (UTC). The
                        range ends at December 31st, 9999.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <constant>Edm.Double</constant> - A 64-bit floating point value.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <constant>Edm.Guid</constant> - A 128-bit globally unique identifier.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <constant>Edm.Int32</constant> - A 32-bit integer.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <constant>Edm.Int64</constant> - A 64-bit integer.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <constant>Edm.String</constant> - A UTF-16-encoded value. String values may
                        be up to 64 KB in size.
                    </para>
                </listitem>
            </itemizedlist>
        </sect3>

        <sect3 id="zend.service.windowsazure.storage.table.entities.dynamic">
            <title>No enforced schema entities (a.k.a. DynamicEntity)</title>

            <para>
                To use the <classname>Zend_Service_WindowsAzure_Storage_Table</classname> class
                without defining a schema, you can make use of the
                <classname>Zend_Service_WindowsAzure_Storage_DynamicTableEntity</classname> class.
                This class inherits <classname>Zend_Service_WindowsAzure_Storage_TableEntity</classname>
                like an enforced schema class does, but contains additional logic to make it dynamic
                and not bound to a schema.
            </para>

            <para>
                Base properties provided by
                <classname>Zend_Service_WindowsAzure_Storage_DynamicTableEntity</classname> are:
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                        PartitionKey (exposed through <methodname>getPartitionKey()</methodname> and
                        <methodname>setPartitionKey()</methodname>)
                    </para>
                </listitem>

                <listitem>
                    <para>
                        RowKey (exposed through <methodname>getRowKey()</methodname> and
                        <methodname>setRowKey()</methodname>)
                    </para>
                </listitem>

                <listitem>
                    <para>
                        Timestamp (exposed through <methodname>getTimestamp()</methodname> and
                        <methodname>setTimestamp()</methodname>)
                    </para>
                </listitem>

                <listitem>
                    <para>
                        Etag value (exposed through <methodname>getEtag()</methodname> and
                        <methodname>setEtag()</methodname>)
                    </para>
                </listitem>
            </itemizedlist>

            <para>
                Other properties can be added on the fly. Their Windows Azure table storage type
                will be determined on-the-fly:
            </para>

            <example id="zend.service.windowsazure.storage.table.entities.dynamic.schema">
                <title>Dynamicaly adding properties to Zend_Service_WindowsAzure_Storage_DynamicTableEntity</title>

                <programlisting language="php"><![CDATA[
$target = new Zend_Service_WindowsAzure_Storage_DynamicTableEntity(
    'partition1', '000001'
);
$target->Name = 'Name'; // Will add property "Name" of type "Edm.String"
$target->Age  = 25;     // Will add property "Age" of type "Edm.Int32"
]]></programlisting>
            </example>

            <para>
                Optionally, a property type can be enforced:
            </para>

            <example id="zend.service.windowsazure.storage.table.entities.dynamic.schema-forcedproperties">
                <title>Forcing property types on Zend_Service_WindowsAzure_Storage_DynamicTableEntity</title>

                <programlisting language="php"><![CDATA[
$target = new Zend_Service_WindowsAzure_Storage_DynamicTableEntity(
    'partition1', '000001'
);
$target->Name = 'Name'; // Will add property "Name" of type "Edm.String"
$target->Age  = 25;     // Will add property "Age" of type "Edm.Int32"

// Change type of property "Age" to "Edm.Int32":
$target->setAzurePropertyType('Age', 'Edm.Int64');
]]></programlisting>
            </example>

            <para>
                The <classname>Zend_Service_WindowsAzure_Storage_Table</classname> class
                automatically works with
                <classname>Zend_Service_WindowsAzure_Storage_TableEntity</classname> if no specific
                class is passed into Table Storage methods.
            </para>
        </sect3>

        <sect3 id="zend.service.windowsazure.storage.table.entities.api">
            <title>Entities API examples</title>

            <sect4 id="zend.service.windowsazure.storage.table.entities.api.insert">
                <title>Inserting an entity</title>

                <para>
                    Using the following code, an entity can be inserted into a table named
                    "testtable".  Note that the table has already been created before.
                </para>

                <example id="zend.service.windowsazure.storage.table.api.entities.insert.example">
                    <title>Inserting an entity</title>

                    <programlisting language="php"><![CDATA[
$entity = new SampleEntity ('partition1', 'row1');
$entity->FullName = "Maarten";
$entity->Age = 25;
$entity->Visible = true;

$storageClient = new Zend_Service_WindowsAzure_Storage_Table(
    'table.core.windows.net', 'myaccount', 'myauthkey'
);
$result = $storageClient->insertEntity('testtable', $entity);

// Check the timestamp and etag of the newly inserted entity
echo 'Timestamp: ' . $result->getTimestamp() . "\n";
echo 'Etag: ' . $result->getEtag() . "\n";
]]></programlisting>
                </example>
            </sect4>

            <sect4 id="zend.service.windowsazure.storage.table.entities.api.retrieve-by-id">
                <title>Retrieving an entity by partition key and row key</title>

                <para>
                    Using the following code, an entity can be retrieved by partition key and row
                    key.  Note that the table and entity have already been created before.
                </para>

                <example id="zend.service.windowsazure.storage.table.entities.api.retrieve-by-id.example">
                    <title>Retrieving an entity by partition key and row key</title>

                    <programlisting language="php"><![CDATA[
$storageClient = new Zend_Service_WindowsAzure_Storage_Table(
    'table.core.windows.net', 'myaccount', 'myauthkey'
);
$entity= $storageClient->retrieveEntityById(
    'testtable', 'partition1', 'row1', 'SampleEntity'
);
]]></programlisting>
                </example>
            </sect4>

            <sect4 id="zend.service.windowsazure.storage.table.entities.api.updating">
                <title>Updating an entity</title>

                <para>
                    Using the following code, an entity can be updated. Note that the table and
                    entity have already been created before.
                </para>

                <example id="zend.service.windowsazure.storage.table.api.entities.updating.example">
                    <title>Updating an entity</title>

                    <programlisting language="php"><![CDATA[
$storageClient = new Zend_Service_WindowsAzure_Storage_Table(
    'table.core.windows.net', 'myaccount', 'myauthkey'
);
$entity = $storageClient->retrieveEntityById(
    'testtable', 'partition1', 'row1', 'SampleEntity'
);

$entity->Name = 'New name';
$result = $storageClient->updateEntity('testtable', $entity);
]]></programlisting>
                </example>

                <para>
                    If you want to make sure the entity has not been updated before, you can make
                    sure the <acronym>Etag</acronym> of the entity is checked. If the entity already
                    has had an update, the update will fail to make sure you do not overwrite any
                    newer data.
                </para>

                <example id="zend.service.windowsazure.storage.table.entities.api.updating.example-etag">
                    <title>Updating an entity (with Etag check)</title>

                    <programlisting language="php"><![CDATA[
$storageClient = new Zend_Service_WindowsAzure_Storage_Table(
    'table.core.windows.net', 'myaccount', 'myauthkey'
);
$entity = $storageClient->retrieveEntityById(
    'testtable', 'partition1', 'row1', 'SampleEntity'
);

$entity->Name = 'New name';

// last parameter instructs the Etag check:
$result = $storageClient->updateEntity('testtable', $entity, true);
]]></programlisting>
                </example>
            </sect4>

            <sect4 id="zend.service.windowsazure.storage.table.entities.api.delete">
                <title>Deleting an entity</title>

                <para>
                    Using the following code, an entity can be deleted.  Note that the table and
                    entity have already been created before.
                </para>

                <example id="zend.service.windowsazure.storage.table.entities.api.delete.example">
                    <title>Deleting an entity</title>

                    <programlisting language="php"><![CDATA[
$storageClient = new Zend_Service_WindowsAzure_Storage_Table(
    'table.core.windows.net', 'myaccount', 'myauthkey'
);
$entity = $storageClient->retrieveEntityById(
    'testtable', 'partition1', 'row1', 'SampleEntity'
);
$result = $storageClient->deleteEntity('testtable', $entity);
]]></programlisting>
                </example>
            </sect4>
        </sect3>

        <sect3 id="zend.service.windowsazure.storage.table.entities.querying">
            <title>Performing queries</title>

            <para>
                Queries in <classname>Zend_Service_WindowsAzure_Storage_Table</classname> table
                storage can be performed in two ways:
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                        By manually creating a filter condition (involving learning a new query
                        language)
                    </para>
                </listitem>

                <listitem>
                    <para>
                        By using the fluent interface provided by the
                        <classname>Zend_Service_WindowsAzure_Storage_Table</classname>
                    </para>
                </listitem>
            </itemizedlist>

            <para>
                Using the following code, a table can be queried using a filter condition.  Note
                that the table and entities have already been created before.
            </para>

            <example id="zend.service.windowsazure.storage.table.entities.querying.query-filter">
                <title>Performing queries using a filter condition</title>

                <programlisting language="php"><![CDATA[
$storageClient = new Zend_Service_WindowsAzure_Storage_Table(
    'table.core.windows.net', 'myaccount', 'myauthkey'
);
$entities = $storageClient->storageClient->retrieveEntities(
    'testtable',
    'Name eq \'Maarten\' and PartitionKey eq \'partition1\'',
    'SampleEntity'
);

foreach ($entities as $entity) {
    echo 'Name: ' . $entity->Name . "\n";
}
]]></programlisting>
            </example>

            <para>
                Using the following code, a table can be queried using a fluent interface.  Note
                that the table and entities have already been created before.
            </para>

            <example id="zend.service.windowsazure.storage.table.api.entities.query-fluent">
                <title>Performing queries using a fluent interface</title>

                <programlisting language="php"><![CDATA[
$storageClient = new Zend_Service_WindowsAzure_Storage_Table(
    'table.core.windows.net', 'myaccount', 'myauthkey'
);
$entities = $storageClient->storageClient->retrieveEntities(
    'testtable',
    $storageClient->select()
                  ->from($tableName)
                  ->where('Name eq ?', 'Maarten')
                  ->andWhere('PartitionKey eq ?', 'partition1'),
    'SampleEntity'
);

foreach ($entities as $entity) {
    echo 'Name: ' . $entity->Name . "\n";
}
]]></programlisting>
            </example>
        </sect3>

        <sect3 id="zend.service.windowsazure.storage.table.entities.batch">
            <title>Batch operations</title>

            <para>
                This topic demonstrates how to use the table entity group transaction features
                provided by Windows Azure table storage. Windows Azure table storage supports batch
                transactions on entities that are in the same table and belong to the same partition
                group. A transaction can include at most 100 entities.
            </para>

            <para>
                The following example uses a batch operation (transaction) to insert a set of
                entities into the "testtable" table. Note that the table has already been created
                before.
            </para>

            <example id="zend.service.windowsazure.storage.table.api.batch">
                <title>Executing a batch operation</title>

                <programlisting language="php"><![CDATA[
$storageClient = new Zend_Service_WindowsAzure_Storage_Table(
    'table.core.windows.net', 'myaccount', 'myauthkey'
);

// Start batch
$batch = $storageClient->startBatch();

// Insert entities in batch
$entities = generateEntities();
foreach ($entities as $entity) {
    $storageClient->insertEntity($tableName, $entity);
}

// Commit
$batch->commit();
]]></programlisting>
            </example>
        </sect3>
    </sect2>

    <sect2 id="zend.service.windowsazure.storage.table.sessionhandler">
        <title>Table storage session handler</title>

        <para>
            When running a PHP application on the Windows Azure platform in a load-balanced mode
            (running 2 Web Role instances or more), it is important that PHP session data can be
            shared between multiple Web Role instances. The Windows Azure SDK for PHP provides the
            <classname>Zend_Service_WindowsAzure_SessionHandler</classname> class, which uses
            Windows Azure Table Storage as a session handler for PHP applications.
        </para>

        <para>
            To use the <classname>Zend_Service_WindowsAzure_SessionHandler</classname> session
            handler, it should be registered as the default session handler for your PHP
            application:
        </para>

        <example id="zend.service.windowsazure.storage.table.api.sessionhandler-register">
            <title>Registering table storage session handler</title>

            <programlisting language="php"><![CDATA[
$storageClient = new Zend_Service_WindowsAzure_Storage_Table(
    'table.core.windows.net', 'myaccount', 'myauthkey'
);

$sessionHandler = new Zend_Service_WindowsAzure_SessionHandler(
    $storageClient , 'sessionstable'
);
$sessionHandler->register();
]]></programlisting>
        </example>

        <para>
            The above classname registers the
            <classname>Zend_Service_WindowsAzure_SessionHandler</classname> session handler and will
            store sessions in a table called "sessionstable".
        </para>

        <para>
            After registration of the
            <classname>Zend_Service_WindowsAzure_SessionHandler</classname> session handler,
            sessions can be started and used in the same way as a normal PHP session:
        </para>

        <example id="zend.service.windowsazure.storage.table.api.sessionhandler-usage">
            <title>Using table storage session handler</title>

            <programlisting role="php"><![CDATA[
$storageClient = new Zend_Service_WindowsAzure_Storage_Table(
    'table.core.windows.net', 'myaccount', 'myauthkey'
);

$sessionHandler = new Zend_Service_WindowsAzure_SessionHandler(
    $storageClient , 'sessionstable'
);
$sessionHandler->register();

session_start();

if (!isset($_SESSION['firstVisit'])) {
    $_SESSION['firstVisit'] = time();
}

// ...
]]></programlisting>
        </example>

        <warning>
            <para>
                The <classname>Zend_Service_WindowsAzure_SessionHandler</classname> session handler
                should be registered before a call to <functionname>session_start()</functionname>
                is made!
            </para>
        </warning>
    </sect2>
</sect1>