Come usare l'archiviazione tabelle da PHP

Suggerimento

Il contenuto in questo articolo si applica all'archivio tabelle Basic originale di Azure. Tuttavia, è ora disponibile un'offerta Premium per l'archivio tabelle di Azure in anteprima pubblica che include tabelle con ottimizzazione per la velocità effettiva, distribuzione globale e indici secondari automatici. Per altre informazioni e per provare la nuova esperienza Premium, vedere Azure Cosmos DB: API di tabella. Il linguaggio di programmazione usato in questo articolo non è ancora supportato nell'offerta Premium, ma verrà aggiunto in futuro.

Overview

Questa guida illustra come eseguire scenari comuni con il servizio tabelle di Azure. Gli esempi sono scritti in PHP e usano Azure SDK per PHP. Gli scenari presentati includono creazione ed eliminazione di una tabella, inserimento ed eliminazione di entità ed esecuzione di query sulle entità in una tabella. Per altre informazioni sul servizio tabelle di Azure, vedere la sezione Passaggi successivi .

Informazioni sul Servizio tabelle

Il servizio di archiviazione tabelle di Azure consente di archiviare grandi quantità di dati strutturati. Il servizio è un datastore NoSQL che accetta chiamate autenticate dall'interno e dall'esterno del cloud di Azure. Le tabelle di Azure sono ideali per l'archiviazione di dati strutturati non relazionali. Di seguito sono riportati gli utilizzi più comuni per il servizio tabelle.

  • Archiviazione di terabyte di dati strutturati in grado di servire applicazioni su scala Web
  • Archiviazione di set di dati che non richiedono join complessi, chiavi esterne o stored procedure e che possono essere denormalizzati per l'accesso rapido
  • Esecuzione rapida di query sui dati mediante un indice cluster
  • Accesso ai dati tramite il protocollo OData e query LINQ con librerie .NET WCF Data Service

È possibile utilizzare il servizio tabelle per archiviare e interrogare grandi set di dati strutturati non relazionali, con tabelle scalabili in base all'aumento della domanda

Concetti del servizio tabelle

Il servizio tabelle contiene i componenti seguenti:

Diagramma dei componenti del servizio tabelle

  • Formato dell'URL: il codice fa riferimento alle tabelle in un account usando il formato di indirizzo seguente:
    http://<storage account>.table.core.windows.net/<table>

    È possibile fare riferimento direttamente alle tabelle di Azure utilizzando questo indirizzo con il protocollo OData. Per altre informazioni, vedere OData.org.

  • Account di archiviazione: l'accesso ad Archiviazione di Azure viene eseguito esclusivamente tramite un account di archiviazione. Per informazioni sulla capacità dell'account di archiviazione, vedere Obiettivi di scalabilità e prestazioni per Archiviazione di Azure .
  • Tabella: una tabella è una raccolta di entità. Le tabelle non impongono uno schema sulle entità, pertanto una singola tabella può contenere entità che presentano set di proprietà diversi. Il numero di tabelle che un account di archiviazione può contenere è limitato solo in base al limite di capacità dell'account di archiviazione.
  • Entità: un'entità è un set di proprietà, simile a una riga di database. Un'entità può avere una dimensione massima di 1 MB.
  • Proprietà: una proprietà è una coppia nome-valore. Ogni entità può includere fino a 252 proprietà per l'archiviazione dei dati. Ogni entità dispone inoltre di 3 proprietà di sistema che specificano una chiave di partizione, una chiave di riga e un timestamp. Le entità con la stessa chiave di partizione possono essere interrogate più rapidamente e inserite o aggiornate in operazioni atomiche. La chiave di riga di un'entità ne rappresenta l'identificatore univoco all'interno di una partizione.

Per informazioni sulle proprietà e i tipi di tabelle, vedere Informazioni sul modello di dati del servizio tabelle.

Creare un account di archiviazione di Azure

Il modo più semplice per creare il primo account di archiviazione di Azure consiste nell'usare il portale di Azure. Per altre informazioni, vedere Creare un account di archiviazione.

È anche possibile creare un account di archiviazione di Azure usando Azure PowerShell, l'interfaccia della riga di comando di Azure o la libreria client del provider di risorse di archiviazione per .NET.

Se si preferisce non creare un account di archiviazione in questa fase, è anche possibile usare l'emulatore di archiviazione di Azure per eseguire e testare il codice in un ambiente locale. Per altre informazioni, vedere Usare l'emulatore di archiviazione di Azure per sviluppo e test.

Creare un'applicazione PHP

Per creare un'applicazione PHP che accede al Servizio tabelle di Azure, è sufficiente fare riferimento alle classi in Azure SDK per PHP dall'interno del codice. Per creare l'applicazione, è possibile usare qualsiasi strumento di sviluppo, incluso il Blocco note.

In questa guida vengono usate le funzionalità del servizio tabelle che possono essere chiamate da un'applicazione PHP in locale o nel codice in esecuzione in un ruolo Web, in un ruolo di lavoro o in un sito Web di Azure.

Acquisire le librerie client di Azure

Installazione tramite Composer

  1. Installare Git. Si noti che in Windows, è anche necessario aggiungere l'eseguibile Git alla variabile di ambiente PATH.
  2. Creare un file denominato composer.json nella radice del progetto, quindi aggiungere nel file il codice seguente:

    {
      "require": {
        "microsoft/windowsazure": "^0.4"
      }
    }
    
  3. Scaricare composer.phar nella radice del progetto.
  4. Aprire un prompt dei comandi ed eseguire il comando seguente nella radice del progetto

    php composer.phar install
    

Configurare l'applicazione per accedere al Servizio tabelle

Per utilizzare le API del Servizio tabelle di Azure, è necessario:

  1. Fare riferimento al file autoloader mediante l'istruzione require_once
  2. Fare riferimento a tutte le eventuali classi utilizzabili.

Nell'esempio seguente viene indicato come includere il file autoloader e fare riferimento alla classe ServicesBuilder .

Nota

Gli esempi in questo articolo presuppongono che siano state installate le librerie client PHP per Azure tramite Composer. Se le librerie sono state installate manualmente, sarà necessario fare riferimento al file autoloader WindowsAzure.php .

require_once 'vendor/autoload.php';
use WindowsAzure\Common\ServicesBuilder;

Negli esempi seguenti viene mostrata sempre l'istruzione require_once , ma si fa riferimento solo alle classi necessarie per l'esecuzione dell'esempio.

Configurare una connessione di archiviazione di Azure

Per creare un'istanza di un client del servizio tabelle di Azure, è necessario avere prima una stringa di connessione valida. Il formato della stringa di connessione del servizio tabelle è:

Per accedere a un servizio attivo:

DefaultEndpointsProtocol=[http|https];AccountName=[yourAccount];AccountKey=[yourKey]

Per accedere alla memoria dell'emulatore:

UseDevelopmentStorage=true

Per creare un client di servizio di Azure, è necessario usare la classe ServicesBuilder . È possibile:

  • passare la stringa di connessione direttamente a essa o
  • utilizzare CloudConfigurationManager (CCM) per cercare la stringa di connessione in più origini esterne:
    • per impostazione predefinita, viene fornito con il supporto per un'origine esterna, ovvero le variabili ambientali
    • è possibile aggiungere nuove origini estendendo la classe ConnectionStringSource

Per gli esempi illustrati in questo articolo, la stringa di connessione verrà passata direttamente.

require_once 'vendor/autoload.php';

use WindowsAzure\Common\ServicesBuilder;

$tableRestProxy = ServicesBuilder::getInstance()->createTableService($connectionString);

Creare una tabella

Un oggetto TableRestProxy consente di creare una tabella usando il metodo createTable. Durante la creazione di una tabella, è possibile impostare il timeout del servizio tabelle. Per altre informazioni sul timeout del servizio tabelle, vedere Setting Timeouts for Table Service Operations (Impostazione di timeout per le operazioni del servizio tabelle).

require_once 'vendor\autoload.php';

use WindowsAzure\Common\ServicesBuilder;
use MicrosoftAzure\Storage\Common\ServiceException;

// Create table REST proxy.
$tableRestProxy = ServicesBuilder::getInstance()->createTableService($connectionString);

try    {
    // Create table.
    $tableRestProxy->createTable("mytable");
}
catch(ServiceException $e){
    $code = $e->getCode();
    $error_message = $e->getMessage();
    // Handle exception based on error codes and messages.
    // Error codes and messages can be found here:
    // http://msdn.microsoft.com/library/azure/dd179438.aspx
}

Per informazioni sulle restrizioni ai nomi delle tabelle, vedere Understanding the Table Service Data Model (Informazioni sul modello di dati del servizio tabelle).

Aggiungere un'entità a una tabella

Per aggiungere un'entità a una tabella, creare un nuovo oggetto Entity e passarlo a TableRestProxy->insertEntity. Si noti che durante la creazione di un'entità, è necessario specificare le chiavi PartitionKey e RowKey. Si tratta di identificatori univoci dell'entità e sono valori che possono essere interrogati molto più velocemente rispetto ad altre proprietà dell'entità. Il sistema usa PartitionKey per distribuire automaticamente le entità della tabella su molti nodi di archiviazione. Le entità con lo stesso PartitionKey vengono archiviate nello stesso nodo. Operazioni su più entità archiviate nello stesso nodo vengono eseguite più efficacemente che non su entità archiviate in nodi diversi. RowKey è l'ID univoco di un'entità all'interno di una partizione.

require_once 'vendor/autoload.php';

use WindowsAzure\Common\ServicesBuilder;
use MicrosoftAzure\Storage\Common\ServiceException;
use MicrosoftAzure\Storage\Table\Models\Entity;
use MicrosoftAzure\Storage\Table\Models\EdmType;

// Create table REST proxy.
$tableRestProxy = ServicesBuilder::getInstance()->createTableService($connectionString);

$entity = new Entity();
$entity->setPartitionKey("tasksSeattle");
$entity->setRowKey("1");
$entity->addProperty("Description", null, "Take out the trash.");
$entity->addProperty("DueDate",
                        EdmType::DATETIME,
                        new DateTime("2012-11-05T08:15:00-08:00"));
$entity->addProperty("Location", EdmType::STRING, "Home");

try{
    $tableRestProxy->insertEntity("mytable", $entity);
}
catch(ServiceException $e){
    // Handle exception based on error codes and messages.
    // Error codes and messages are here:
    // http://msdn.microsoft.com/library/azure/dd179438.aspx
    $code = $e->getCode();
    $error_message = $e->getMessage();
}

Per informazioni sulle proprietà e i tipi di tabelle, vedere Understanding the Table Service Data Model (Informazioni sul modello di dati del servizio tabelle).

La classe TableRestProxy offre due metodi alternativi per l'inserimento di entità: insertOrMergeEntity e insertOrReplaceEntity. Per utilizzare questi metodi, creare una nuova Entity e passarla come parametro a uno dei due metodi. Ogni metodo inserirà l'entità se non esiste già. Se l'entità esiste già, insertOrMergeEntity aggiornerà i valori delle proprietà esistenti e aggiungerà nuove proprietà se non esistono, mentre insertOrReplaceEntity sostituirà completamente un'entità esistente. Nell'esempio seguente viene illustrato come utilizzare insertOrMergeEntity. Se l'entità con PartitionKey "tasksSeattle" e RowKey "1" non esiste già, verrà inserita. Se è stata inserita in precedenza (come illustrato nell'esempio precedente), la proprietà DueDate verrà aggiornata e verrà aggiunta la proprietà Status. Verranno aggiornate anche le proprietà Description e Location, ma con valori che non apporteranno alcuna modifica. Se queste due ultime proprietà non sono state aggiunte come illustrato nell'esempio, ma erano disponibili nell'entità di destinazione, i loro valori esistenti non subiranno alcuna modifica.

require_once 'vendor/autoload.php';

use WindowsAzure\Common\ServicesBuilder;
use MicrosoftAzure\Storage\Common\ServiceException;
use MicrosoftAzure\Storage\Table\Models\Entity;
use MicrosoftAzure\Storage\Table\Models\EdmType;

// Create table REST proxy.
$tableRestProxy = ServicesBuilder::getInstance()->createTableService($connectionString);

//Create new entity.
$entity = new Entity();

// PartitionKey and RowKey are required.
$entity->setPartitionKey("tasksSeattle");
$entity->setRowKey("1");

// If entity exists, existing properties are updated with new values and
// new properties are added. Missing properties are unchanged.
$entity->addProperty("Description", null, "Take out the trash.");
$entity->addProperty("DueDate", EdmType::DATETIME, new DateTime()); // Modified the DueDate field.
$entity->addProperty("Location", EdmType::STRING, "Home");
$entity->addProperty("Status", EdmType::STRING, "Complete"); // Added Status field.

try    {
    // Calling insertOrReplaceEntity, instead of insertOrMergeEntity as shown,
    // would simply replace the entity with PartitionKey "tasksSeattle" and RowKey "1".
    $tableRestProxy->insertOrMergeEntity("mytable", $entity);
}
catch(ServiceException $e){
    // Handle exception based on error codes and messages.
    // Error codes and messages are here:
    // http://msdn.microsoft.com/library/azure/dd179438.aspx
    $code = $e->getCode();
    $error_message = $e->getMessage();
    echo $code.": ".$error_message."<br />";
}

Recuperare una singola entità

Il metodo TableRestProxy->getEntity consente di recuperare una singola entità eseguendo una query su PartitionKey e RowKey. Nell'esempio seguente la chiave di partizione tasksSeattle e la chiave di riga 1 vengono passate al metodo getEntity.

require_once 'vendor/autoload.php';

use WindowsAzure\Common\ServicesBuilder;
use MicrosoftAzure\Storage\Common\ServiceException;

// Create table REST proxy.
$tableRestProxy = ServicesBuilder::getInstance()->createTableService($connectionString);

try    {
    $result = $tableRestProxy->getEntity("mytable", "tasksSeattle", 1);
}
catch(ServiceException $e){
    // Handle exception based on error codes and messages.
    // Error codes and messages are here:
    // http://msdn.microsoft.com/library/azure/dd179438.aspx
    $code = $e->getCode();
    $error_message = $e->getMessage();
    echo $code.": ".$error_message."<br />";
}

$entity = $result->getEntity();

echo $entity->getPartitionKey().":".$entity->getRowKey();

Recuperare tutte le entità di una partizione

Le query di entità vengono create usando i filtri. Per altre informazioni, vedere Querying Tables and Entities (Query di tabelle ed entità). Per recuperare tutte le entità in una partizione usare il filtro "PartitionKey eq partition_name". Nell'esempio seguente viene illustrato come recuperare tutte le entità nella partizione tasksSeattle passando un filtro al metodo queryEntities .

require_once 'vendor/autoload.php';

use WindowsAzure\Common\ServicesBuilder;
use MicrosoftAzure\Storage\Common\ServiceException;

// Create table REST proxy.
$tableRestProxy = ServicesBuilder::getInstance()->createTableService($connectionString);

$filter = "PartitionKey eq 'tasksSeattle'";

try    {
    $result = $tableRestProxy->queryEntities("mytable", $filter);
}
catch(ServiceException $e){
    // Handle exception based on error codes and messages.
    // Error codes and messages are here:
    // http://msdn.microsoft.com/library/azure/dd179438.aspx
    $code = $e->getCode();
    $error_message = $e->getMessage();
    echo $code.": ".$error_message."<br />";
}

$entities = $result->getEntities();

foreach($entities as $entity){
    echo $entity->getPartitionKey().":".$entity->getRowKey()."<br />";
}

Recuperare un subset di entità in una partizione

Lo stesso modello applicato nell'esempio precedente può essere usato per recuperare un subset di entità in una partizione. Il subset di entità recuperato viene determinato dal filtro usato. Per altre informazioni, vedere Querying Tables and Entities (Query di tabelle ed entità). L'esempio seguente illustra come usare un filtro per recuperare tutte le entità con un valore Location specifico e un valore DueDate precedente a una data specificata.

require_once 'vendor/autoload.php';

use WindowsAzure\Common\ServicesBuilder;
use MicrosoftAzure\Storage\Common\ServiceException;

// Create table REST proxy.
$tableRestProxy = ServicesBuilder::getInstance()->createTableService($connectionString);

$filter = "Location eq 'Office' and DueDate lt '2012-11-5'";

try    {
    $result = $tableRestProxy->queryEntities("mytable", $filter);
}
catch(ServiceException $e){
    // Handle exception based on error codes and messages.
    // Error codes and messages are here:
    // http://msdn.microsoft.com/library/azure/dd179438.aspx
    $code = $e->getCode();
    $error_message = $e->getMessage();
    echo $code.": ".$error_message."<br />";
}

$entities = $result->getEntities();

foreach($entities as $entity){
    echo $entity->getPartitionKey().":".$entity->getRowKey()."<br />";
}

Recuperare un subset di proprietà di entità

È possibile recuperare un subset di proprietà di entità eseguendo una query. Questa tecnica, denominata proiezione, consente di ridurre la larghezza di banda e di migliorare le prestazioni della query, in particolare per entità di grandi dimensioni. Per specificare la proprietà da recuperare, passare il nome della proprietà al metodo Query->addSelectField. Per aggiungere altre proprietà, è possibile chiamare questo metodo più volte. Dopo l'esecuzione di TableRestProxy->queryEntities, per le entità restituite saranno presenti solo le proprietà selezionate. Se si desidera restituire un subset di entità di tabella, utilizzare un filtro come illustrato nelle query precedenti.

require_once 'vendor/autoload.php';

use WindowsAzure\Common\ServicesBuilder;
use MicrosoftAzure\Storage\Common\ServiceException;
use MicrosoftAzure\Storage\Table\Models\QueryEntitiesOptions;

// Create table REST proxy.
$tableRestProxy = ServicesBuilder::getInstance()->createTableService($connectionString);

$options = new QueryEntitiesOptions();
$options->addSelectField("Description");

try    {
    $result = $tableRestProxy->queryEntities("mytable", $options);
}
catch(ServiceException $e){
    // Handle exception based on error codes and messages.
    // Error codes and messages are here:
    // http://msdn.microsoft.com/library/azure/dd179438.aspx
    $code = $e->getCode();
    $error_message = $e->getMessage();
    echo $code.": ".$error_message."<br />";
}

// All entities in the table are returned, regardless of whether
// they have the Description field.
// To limit the results returned, use a filter.
$entities = $result->getEntities();

foreach($entities as $entity){
    $description = $entity->getProperty("Description")->getValue();
    echo $description."<br />";
}

Aggiornare un'entità

È possibile aggiornare un'entità esistente usando i metodi Entity->setProperty e Entity->addProperty sull'entità e quindi chiamando TableRestProxy->updateEntity. Nell'esempio seguente viene recuperata un'entità, modificata una proprietà, rimossa un'altra proprietà e aggiunta una nuova proprietà. Si noti che per rimuovere una proprietà, è necessario impostarne il valore su Null.

require_once 'vendor/autoload.php';

use WindowsAzure\Common\ServicesBuilder;
use MicrosoftAzure\Storage\Common\ServiceException;
use MicrosoftAzure\Storage\Table\Models\Entity;
use MicrosoftAzure\Storage\Table\Models\EdmType;

// Create table REST proxy.
$tableRestProxy = ServicesBuilder::getInstance()->createTableService($connectionString);

$result = $tableRestProxy->getEntity("mytable", "tasksSeattle", 1);

$entity = $result->getEntity();

$entity->setPropertyValue("DueDate", new DateTime()); //Modified DueDate.

$entity->setPropertyValue("Location", null); //Removed Location.

$entity->addProperty("Status", EdmType::STRING, "In progress"); //Added Status.

try    {
    $tableRestProxy->updateEntity("mytable", $entity);
}
catch(ServiceException $e){
    // Handle exception based on error codes and messages.
    // Error codes and messages are here:
    // http://msdn.microsoft.com/library/azure/dd179438.aspx
    $code = $e->getCode();
    $error_message = $e->getMessage();
    echo $code.": ".$error_message."<br />";
}

Eliminare un'entità

Per eliminare un'entità passare il nome della tabella e le chiavi PartitionKey e RowKey dell'entità al metodo TableRestProxy->deleteEntity.

require_once 'vendor/autoload.php';

use WindowsAzure\Common\ServicesBuilder;
use MicrosoftAzure\Storage\Common\ServiceException;

// Create table REST proxy.
$tableRestProxy = ServicesBuilder::getInstance()->createTableService($connectionString);

try    {
    // Delete entity.
    $tableRestProxy->deleteEntity("mytable", "tasksSeattle", "2");
}
catch(ServiceException $e){
    // Handle exception based on error codes and messages.
    // Error codes and messages are here:
    // http://msdn.microsoft.com/library/azure/dd179438.aspx
    $code = $e->getCode();
    $error_message = $e->getMessage();
    echo $code.": ".$error_message."<br />";
}

Si noti che per effettuare controlli di concorrenza è possibile impostare il valore Etag per un'entità da eliminare usando il metodo DeleteEntityOptions->setEtag e passando l'oggetto DeleteEntityOptions a deleteEntity come quarto parametro.

Operazioni batch su tabella

Il metodo TableRestProxy->batch consente di eseguire più operazioni in una sola richiesta. In questo caso è necessario aggiungere le operazioni all'oggetto BatchRequest e quindi passare l'oggetto BatchRequest al metodo TableRestProxy->batch. Per aggiungere un'operazione all'oggetto BatchRequest , è possibile chiamare più volte uno dei metodi seguenti:

  • addInsertEntity (per aggiungere un'operazione insertEntity)
  • addUpdateEntity (per aggiungere un'operazione updateEntity)
  • addMergeEntity (per aggiungere un'operazione mergeEntity)
  • addInsertOrReplaceEntity (per aggiungere un'operazione insertOrReplaceEntity)
  • addInsertOrMergeEntity (per aggiungere un'operazione insertOrMergeEntity)
  • addDeleteEntity (per aggiungere un'operazione deleteEntity)

L'esempio seguente illustra come eseguire le operazioni insertEntity e deleteEntity in una sola richiesta:

require_once 'vendor/autoload.php';

use WindowsAzure\Common\ServicesBuilder;
use MicrosoftAzure\Storage\Common\ServiceException;
use MicrosoftAzure\Storage\Table\Models\Entity;
use MicrosoftAzure\Storage\Table\Models\EdmType;
use MicrosoftAzure\Storage\Table\Models\BatchOperations;

    // Create table REST proxy.
$tableRestProxy = ServicesBuilder::getInstance()->createTableService($connectionString);

// Create list of batch operation.
$operations = new BatchOperations();

$entity1 = new Entity();
$entity1->setPartitionKey("tasksSeattle");
$entity1->setRowKey("2");
$entity1->addProperty("Description", null, "Clean roof gutters.");
$entity1->addProperty("DueDate",
                        EdmType::DATETIME,
                        new DateTime("2012-11-05T08:15:00-08:00"));
$entity1->addProperty("Location", EdmType::STRING, "Home");

// Add operation to list of batch operations.
$operations->addInsertEntity("mytable", $entity1);

// Add operation to list of batch operations.
$operations->addDeleteEntity("mytable", "tasksSeattle", "1");

try    {
    $tableRestProxy->batch($operations);
}
catch(ServiceException $e){
    // Handle exception based on error codes and messages.
    // Error codes and messages are here:
    // http://msdn.microsoft.com/library/azure/dd179438.aspx
    $code = $e->getCode();
    $error_message = $e->getMessage();
    echo $code.": ".$error_message."<br />";
}

Per altre informazioni su operazioni batch su tabelle, vedere Performing Entity Group Transactions (Esecuzione di transazioni di gruppi di entità).

Eliminare una tabella

Infine, per eliminare una tabella, passare il nome della tabella al metodo TableRestProxy->deleteTable.

require_once 'vendor/autoload.php';

use WindowsAzure\Common\ServicesBuilder;
use MicrosoftAzure\Storage\Common\ServiceException;

// Create table REST proxy.
$tableRestProxy = ServicesBuilder::getInstance()->createTableService($connectionString);

try    {
    // Delete table.
    $tableRestProxy->deleteTable("mytable");
}
catch(ServiceException $e){
    // Handle exception based on error codes and messages.
    // Error codes and messages are here:
    // http://msdn.microsoft.com/library/azure/dd179438.aspx
    $code = $e->getCode();
    $error_message = $e->getMessage();
    echo $code.": ".$error_message."<br />";
}

Passaggi successivi

A questo punto, dopo avere appreso le nozioni di base del servizio tabelle di Azure, usare i collegamenti seguenti per altre informazioni su attività di archiviazione più complesse.