Come usare il servizio tabelle di Archiviazione di Azure o Azure Cosmos DB per tabella da PHP

SI APPLICA A: Tabella

Questo articolo illustra come creare tabelle, archiviare i dati ed eseguire operazioni CRUD sui dati. Scegliere il servizio tabelle di Azure o Azure Cosmos DB per tabella. Gli esempi sono scritti in PHP e usano la libreria client PHP per Tabella di archiviazione di Azure. Gli scenari presentati includono operazioni di creazione ed eliminazione di una tabella, nonché di inserimento, eliminazione ed esecuzione di query sulle entità di una tabella.

Creare un account del servizio di Azure

È possibile usare le tabelle con l'archiviazione tabelle di Azure o con Azure Cosmos DB. Per altre informazioni sulle differenze tra le offerte di tabelle in questi due servizi, vedere la panoramica dell'API per la tabella. È necessario creare un account per il servizio che verrà usato. Le sezioni seguenti illustrano come creare sia l'archiviazione tabelle di Azure che l'account Azure Cosmos DB, tuttavia è possibile scegliere tra uno dei due.

Archiviazione tabelle di Azure

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

È possibile anche creare un account di archiviazione di Azure usando Azure PowerShell o l'interfaccia della riga di comando di Azure.

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.

Azure Cosmos DB for Table

Per istruzioni sulla creazione di un account Azure Cosmos DB per tabella, vedere Creare un account di database.

Creare un'applicazione PHP

L'unico requisito per creare un'applicazione PHP per accedere al servizio tabelle di archiviazione o Azure Cosmos DB per table consiste nel fare riferimento alle classi nell'SDK di tabella di archiviazione di azure per PHP dall'interno del codice. Per creare l'applicazione, è possibile usare qualsiasi strumento di sviluppo, incluso il Blocco note.

In questa guida si usa Archiviazione tabelle di Azure o Azure Cosmos DB per le funzionalità di tabella che possono essere chiamate dall'interno di un'applicazione PHP. L'applicazione può essere eseguita in locale o nel codice in esecuzione all'interno di un ruolo Web di Azure, ruolo di lavoro o sito Web.

Ottenere la libreria client

1. Creare un file denominato composer.json nella radice del progetto e aggiungere nel file il codice seguente:

   {
   "require": {
    "microsoft/azure-storage-table": "*"
   }
   }
   

2. Scaricare composer.phar nella radice.

3. Aprire un prompt dei comandi ed eseguire il comando seguente nella radice del progetto:

   php composer.phar install
   

   In alternativa, passare alla libreria client PHP per Tabella di archiviazione di Azure in GitHub per clonare il codice sorgente.

Aggiungere i riferimenti necessari

Per usare il servizio Tabella di archiviazione o le API di Azure Cosmos DB, è necessario:

• Fare riferimento al file autoloader mediante l'istruzione require_once.
• Fare riferimento a tutte le classi usate.

L'esempio seguente illustra come includere il file autoloader e fare riferimento alla classe TableRestProxy.

require_once 'vendor/autoload.php';
use MicrosoftAzure\Storage\Table\TableRestProxy;

Negli esempi riportati di seguito viene sempre visualizzata l'istruzione require_once , ma viene fatto riferimento solo alle classi necessarie per l'esecuzione dell'esempio.

Aggiungere la stringa di connessione

È possibile connettersi all'account di archiviazione di Azure o all'account Azure Cosmos DB per tabella. Ottenere la stringa di connessione in base al tipo di account in uso.

Aggiungere una connessione al servizio Tabella di archiviazione

Per creare un'istanza di un client del servizio Tabella di archiviazione, è necessario avere prima una stringa di connessione valida. Di seguito è riportato il formato della stringa di connessione al servizio Tabella di archiviazione:

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

Aggiungere una connessione all'emulatore di archiviazione

Per accedere all'emulatore di archiviazione:

UseDevelopmentStorage = true

Aggiungere una connessione ad Azure Cosmos DB

Per creare un'istanza di un client del servizio tabelle di Azure Cosmos DB, è necessario avere prima una stringa di connessione valida. Di seguito è riportato il formato della stringa di connessione ad Azure Cosmos DB:

$connectionString = "DefaultEndpointsProtocol=[https];AccountName=[myaccount];AccountKey=[myaccountkey];TableEndpoint=[https://myendpoint/]";

Per creare un client del servizio tabelle di Azure o di Azure Cosmos DB, è necessario usare la classe TableRestProxy. È possibile:

• passare la stringa di connessione direttamente a essa o
• Usare CloudConfigurationManager (CCM) per controllare più origini esterne per l'stringa di connessione:
  • 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 viene passata direttamente.

require_once 'vendor/autoload.php';

use MicrosoftAzure\Storage\Table\TableRestProxy;

$tableClient = TableRestProxy::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 Impostazione dei timeout per le operazioni del servizio tabelle.

require_once 'vendor\autoload.php';

use MicrosoftAzure\Storage\Table\TableRestProxy;
use MicrosoftAzure\Storage\Common\Exceptions\ServiceException;

// Create Table REST proxy.
$tableClient = TableRestProxy::createTableService($connectionString);

try    {
    // Create table.
    $tableClient->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:
    // https://learn.microsoft.com/rest/api/storageservices/Table-Service-Error-Codes
}

Per informazioni sulle restrizioni ai nomi delle tabelle, vedere 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>. Quando si crea un'entità, è necessario specificare un PartitionKey oggetto e RowKey. Queste entità sono gli identificatori univoci per un'entità e sono valori che possono essere sottoposti a query più velocemente rispetto ad altre proprietà di entità. Il sistema usa PartitionKey per distribuire automaticamente le entità della tabella in molti nodi di archiviazione. Le entità con lo stesso PartitionKey vengono archiviate nello stesso nodo. Le operazioni su più entità archiviate nello stesso nodo eseguono prestazioni migliori rispetto alle entità archiviate in nodi diversi. RowKey è l'ID univoco di un'entità all'interno di una partizione.

require_once 'vendor/autoload.php';

use MicrosoftAzure\Storage\Table\TableRestProxy;
use MicrosoftAzure\Storage\Common\Exceptions\ServiceException;
use MicrosoftAzure\Storage\Table\Models\Entity;
use MicrosoftAzure\Storage\Table\Models\EdmType;

// Create table REST proxy.
$tableClient = TableRestProxy::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{
    $tableClient->insertEntity("mytable", $entity);
}
catch(ServiceException $e){
    // Handle exception based on error codes and messages.
    // Error codes and messages are here:
    // https://learn.microsoft.com/rest/api/storageservices/Table-Service-Error-Codes
    $code = $e->getCode();
    $error_message = $e->getMessage();
}

Per informazioni sulle proprietà e i tipi di tabelle, vedere 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 inserisce l'entità se non esiste. Se l'entità esiste già, insertOrMergeEntity aggiorna i valori delle proprietà se le proprietà esistono già e aggiunge nuove proprietà se non esistono, mentre insertOrReplaceEntity sostituisce completamente un'entità esistente. Nell'esempio riportato di seguito viene illustrato come usare insertOrMergeEntity. Se l'entità con PartitionKey "tasksSeattle" e RowKey "1" non esiste già, tale entità viene inserita. Tuttavia, se esiste già (come illustrato nell'esempio precedente), la DueDate proprietà viene aggiornata e la Status proprietà viene aggiunta. Verranno aggiornate anche le proprietà Description e Location, ma con valori che non apporteranno alcuna modifica. Se queste ultime due proprietà non sono state aggiunte come illustrato nell'esempio, ma esistono nell'entità di destinazione, i valori esistenti rimarranno invariati.

require_once 'vendor/autoload.php';

use MicrosoftAzure\Storage\Table\TableRestProxy;
use MicrosoftAzure\Storage\Common\Exceptions\ServiceException;
use MicrosoftAzure\Storage\Table\Models\Entity;
use MicrosoftAzure\Storage\Table\Models\EdmType;

// Create table REST proxy.
$tableClient = TableRestProxy::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".
    $tableClient->insertOrMergeEntity("mytable", $entity);
}
catch(ServiceException $e){
    // Handle exception based on error codes and messages.
    // Error codes and messages are here:
    // https://learn.microsoft.com/rest/api/storageservices/Table-Service-Error-Codes
    $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 per il relativo PartitionKey e RowKey. Nell'esempio seguente, la chiave di partizione e la chiave tasksSeattle1 di riga vengono passate al metodo getEntity .

require_once 'vendor/autoload.php';

use MicrosoftAzure\Storage\Table\TableRestProxy;
use MicrosoftAzure\Storage\Common\Exceptions\ServiceException;

// Create table REST proxy.
$tableClient = TableRestProxy::createTableService($connectionString);

try    {
    $result = $tableClient->getEntity("mytable", "tasksSeattle", 1);
}
catch(ServiceException $e){
    // Handle exception based on error codes and messages.
    // Error codes and messages are here:
    // https://learn.microsoft.com/rest/api/storageservices/Table-Service-Error-Codes
    $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 costruite usando filtri. Per altre informazioni, vedere Esecuzione di query su tabelle ed entità. Per recuperare tutte le entità nella 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 MicrosoftAzure\Storage\Table\TableRestProxy;
use MicrosoftAzure\Storage\Common\Exceptions\ServiceException;

// Create table REST proxy.
$tableClient = TableRestProxy::createTableService($connectionString);

$filter = "PartitionKey eq 'tasksSeattle'";

try    {
    $result = $tableClient->queryEntities("mytable", $filter);
}
catch(ServiceException $e){
    // Handle exception based on error codes and messages.
    // Error codes and messages are here:
    // https://learn.microsoft.com/rest/api/storageservices/Table-Service-Error-Codes
    $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 filtro usato determina il subset di entità recuperate. Per altre informazioni, vedere Esecuzione di query su tabelle ed entità. Nell'esempio seguente viene illustrato come usare un filtro per recuperare tutte le entità con una specifica Location e una DueDate data inferiore a quella specificata.

require_once 'vendor/autoload.php';

use MicrosoftAzure\Storage\Table\TableRestProxy;
use MicrosoftAzure\Storage\Common\Exceptions\ServiceException;

// Create table REST proxy.
$tableClient = TableRestProxy::createTableService($connectionString);

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

try    {
    $result = $tableClient->queryEntities("mytable", $filter);
}
catch(ServiceException $e){
    // Handle exception based on error codes and messages.
    // Error codes and messages are here:
    // https://learn.microsoft.com/rest/api/storageservices/Table-Service-Error-Codes
    $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 una proprietà da recuperare, passare il nome della proprietà al Query->addSelectField metodo . Per aggiungere altre proprietà, è possibile chiamare questo metodo più volte. Dopo l'esecuzione TableRestProxy->queryEntities, le entità restituite avranno solo le proprietà selezionate. Se si vuole restituire un subset di entità Table, usare un filtro come illustrato nelle query precedenti.

require_once 'vendor/autoload.php';

use MicrosoftAzure\Storage\Table\TableRestProxy;
use MicrosoftAzure\Storage\Common\Exceptions\ServiceException;
use MicrosoftAzure\Storage\Table\Models\QueryEntitiesOptions;

// Create table REST proxy.
$tableClient = TableRestProxy::createTableService($connectionString);

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

try    {
    $result = $tableClient->queryEntities("mytable", $options);
}
catch(ServiceException $e){
    // Handle exception based on error codes and messages.
    // Error codes and messages are here:
    // https://learn.microsoft.com/rest/api/storageservices/Table-Service-Error-Codes
    $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 nell'entità e quindi chiamare TableRestProxy-updateEntity>>. Nell'esempio seguente viene recuperata un'entità, modificata una proprietà, rimossa un'altra proprietà e aggiunta una nuova proprietà. È possibile rimuovere una proprietà impostandone il valore su Null.

require_once 'vendor/autoload.php';

use MicrosoftAzure\Storage\Table\TableRestProxy;
use MicrosoftAzure\Storage\Common\Exceptions\ServiceException;
use MicrosoftAzure\Storage\Table\Models\Entity;
use MicrosoftAzure\Storage\Table\Models\EdmType;

// Create table REST proxy.
$tableClient = TableRestProxy::createTableService($connectionString);

$result = $tableClient->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    {
    $tableClient->updateEntity("mytable", $entity);
}
catch(ServiceException $e){
    // Handle exception based on error codes and messages.
    // Error codes and messages are here:
    // https://learn.microsoft.com/rest/api/storageservices/Table-Service-Error-Codes
    $code = $e->getCode();
    $error_message = $e->getMessage();
    echo $code.": ".$error_message."<br />";
}

Eliminare un'entità

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

require_once 'vendor/autoload.php';

use MicrosoftAzure\Storage\Table\TableRestProxy;
use MicrosoftAzure\Storage\Common\Exceptions\ServiceException;

// Create table REST proxy.
$tableClient = TableRestProxy::createTableService($connectionString);

try    {
    // Delete entity.
    $tableClient->deleteEntity("mytable", "tasksSeattle", "2");
}
catch(ServiceException $e){
    // Handle exception based on error codes and messages.
    // Error codes and messages are here:
    // https://learn.microsoft.com/rest/api/storageservices/Table-Service-Error-Codes
    $code = $e->getCode();
    $error_message = $e->getMessage();
    echo $code.": ".$error_message."<br />";
}

Per i controlli di concorrenza, è possibile impostare Etag per un'entità da eliminare usando il metodo DeleteEntityOptions-setEtag> e passando l'oggetto DeleteEntityOptions come quarto parametro.

Operazioni batch su tabella

Il metodo TableRestProxy-batch> consente di eseguire più operazioni in una singola richiesta. Il modello comporta l'aggiunta di operazioni all'oggetto BatchRequest e quindi il passaggio dell'oggetto BatchRequest al metodo TableRestProxy-batch>. Per aggiungere un'operazione all'oggetto BatchRequest , è possibile chiamare più volte uno dei metodi seguenti:

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

require_once 'vendor/autoload.php';

use MicrosoftAzure\Storage\Table\TableRestProxy;
use MicrosoftAzure\Storage\Common\Exceptions\ServiceException;
use MicrosoftAzure\Storage\Table\Models\Entity;
use MicrosoftAzure\Storage\Table\Models\EdmType;
use MicrosoftAzure\Storage\Table\Models\BatchOperations;

// Configure a connection string for Storage Table service.
$connectionString = "DefaultEndpointsProtocol=[http|https];AccountName=[yourAccount];AccountKey=[yourKey]"

// Create table REST proxy.
$tableClient = TableRestProxy::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    {
    $tableClient->batch($operations);
}
catch(ServiceException $e){
    // Handle exception based on error codes and messages.
    // Error codes and messages are here:
    // https://learn.microsoft.com/rest/api/storageservices/Table-Service-Error-Codes
    $code = $e->getCode();
    $error_message = $e->getMessage();
    echo $code.": ".$error_message."<br />";
}

Per altre informazioni sull'invio in batch di operazioni su tabelle, vedere 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 MicrosoftAzure\Storage\Table\TableRestProxy;
use MicrosoftAzure\Storage\Common\Exceptions\ServiceException;

// Create table REST proxy.
$tableClient = TableRestProxy::createTableService($connectionString);

try    {
    // Delete table.
    $tableClient->deleteTable("mytable");
}
catch(ServiceException $e){
    // Handle exception based on error codes and messages.
    // Error codes and messages are here:
    // https://learn.microsoft.com/rest/api/storageservices/Table-Service-Error-Codes
    $code = $e->getCode();
    $error_message = $e->getMessage();
    echo $code.": ".$error_message."<br />";
}

Contenuti correlati

• Microsoft Azure Storage Explorer è un'app autonoma gratuita di Microsoft che consente di rappresentare facilmente dati di Archiviazione di Azure in Windows, macOS e Linux.
• Centro sviluppatori PHP.