Uso del servicio Azure Storage Table o de Azure Cosmos DB for Table desde PHP

SE APLICA A: Table

• .NET
• Node.js
• Java
• C++
• PHP
• Ruby
• Python
• Go

Sugerencia

El contenido de este artículo se aplica a Azure Table Storage y Azure Cosmos DB for Table. Azure Cosmos DB for Table es una oferta prémium que ofrece tablas con rendimiento optimizado, distribución global e índices secundarios automáticos.

En este artículo se muestra cómo crear tablas, y almacenar los datos y realizar operaciones CRUD en ellos. Elija usar el servicio Azure Table Storage o Azure Cosmos DB for Table. Los ejemplos están escritos en PHP y usan la biblioteca de cliente de PHP de Azure Storage Table. Entre los escenarios descritos se incluyen la creación y eliminación de una tabla, y la inserción, eliminación y consulta de entidades de una tabla. Para obtener más información acerca de Azure Table service, vea la sección Pasos siguientes .

Creación de una cuenta de servicio de Azure

Puede trabajar con tablas mediante Azure Table Storage o Azure Cosmos DB. Para obtener más información sobre las diferencias entre las ofertas de tablas de estos dos servicios, consulte la introducción a API para Table. Debe crear una cuenta para el servicio que se va a utilizar. En las secciones siguientes se muestra cómo crear las cuentas de Azure Table Storage y Azure Cosmos DB, pero solo puede usar una de ellas.

Creación de una cuenta de Azure Storage

La manera más sencilla de crear una cuenta de almacenamiento de Azure es mediante Azure Portal. Para obtener más información, consulte Crear una cuenta de almacenamiento.

También se puede crear una cuenta de Azure Storage mediante Azure PowerShell o la CLI de Azure.

Si prefiere no crear una cuenta de almacenamiento en este momento, también puede utilizar el emulador de Azure Storage para ejecutar y probar el código en un entorno local. Para más información, consulte Uso del emulador de Azure Storage para desarrollo y pruebas.

Creación de una cuenta de Azure Cosmos DB for Table

Para obtener instrucciones sobre cómo crear una cuenta de Azure Cosmos DB for Table, consulte Creación de una cuenta de base de datos.

Creación de una aplicación PHP

El único requisito para crear una aplicación PHP para obtener acceso al servicio Storage Table o a Azure Cosmos DB for Table es hacer referencia a las clases del SDK azure-storage-table para PHP desde dentro de su código. Puede utilizar cualquier herramienta de desarrollo para crear la aplicación, incluido el Bloc de notas.

En esta guía, utilizará características del servicio Storage Table o Azure Cosmos DB a las que se puede llamar desde una aplicación PHP localmente, o bien mediante código que se ejecuta en un rol web, rol de trabajo o sitio web de Azure.

Obtención de la biblioteca de cliente

1. Cree un archivo con el nombre composer.json en la raíz del proyecto y agréguele el código siguiente:

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

2. Descargue composer.phar en la raíz.
3. Abra un símbolo del sistema y ejecute el siguiente comando en la raíz del proyecto:

   php composer.phar install
   

   También puede ir a la biblioteca de cliente de PHP de la tabla de almacenamiento de Azure en GitHub para clonar el código fuente.

Adición de referencias necesarias

Para usar el servicio Storage Table o las API de Azure Cosmos DB, debe:

• Hacer referencia al archivo autocargador mediante la instrucción require_once y
• Haga referencia a todas las clases que utilice.

En el siguiente ejemplo se muestra cómo incluir el archivo autocargador y hacer referencia a la clase TableRestProxy.

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

En los ejemplos que aparecen a continuación, la instrucción require_once aparecerá siempre, pero solo se hará referencia a las clases necesarias para la ejecución del ejemplo.

Incorporación de la cadena de conexión

Puede conectarse a la cuenta de Azure Storage o Azure Cosmos DB for Table. Obtenga la cadena de conexión en función del tipo de cuenta que esté usando.

Adición de una conexión del servicio Storage Table

Para crear una instancia de un cliente del servicio Storage Table, primero debe disponer de una cadena de conexión válida. El formato de las cadenas de conexión del servicio Storage Table es:

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

Adición de una conexión de Emulador de Storage

Para obtener acceso al almacenamiento del emulador:

UseDevelopmentStorage = true

Adición de una conexión de Azure Cosmos DB

Para crear una instancia de un cliente de Azure Cosmos DB Table, primero debe disponer de una cadena de conexión válida. El formato de la cadena de conexión de Azure Cosmos DB es:

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

Para crear un cliente de Azure Table service o Azure Cosmos DB, debe usar la clase TableRestProxy. Puede:

• pasarle directamente la cadena de conexión, o bien
• usar CloudConfigurationManager (CCM) para buscar la cadena de conexión en varios orígenes externos:
  • de manera predeterminada, admite un origen externo: variables de entorno.
  • Puede agregar nuevos orígenes extendiendo la clase ConnectionStringSource.

En los ejemplos descritos aquí, la cadena de conexión se pasa directamente.

require_once 'vendor/autoload.php';

use MicrosoftAzure\Storage\Table\TableRestProxy;

$tableClient = TableRestProxy::createTableService($connectionString);

Creación de una tabla

Puede crear una tabla con un objeto A TableRestProxy con el método createTable. Al crear una tabla, puede establecer un tiempo de espera para Table service. (Para más información sobre el tiempo de espera de Table service, consulte Configuracióon de los tiempos de espera para las operaciones de Table service).

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
}

Para información sobre las restricciones que se aplican a los nombres de las tablas, consulte Introducción al modelo de datos de Table service.

Adición de una entidad a una tabla

Para agregar una entidad a una tabla, cree un nuevo objeto Entity y páselo a TableRestProxy->insertEntity. Tenga en cuenta que al crear una entidad, es necesario especificar los valores de PartitionKey y RowKey. Estos valores son los identificadores exclusivos de la entidad y se pueden consultar más rápidamente que las demás propiedades. El sistema usa PartitionKey para distribuir automáticamente las entidades de la tabla entre numerosos nodos de Storage. Las entidades con la misma PartitionKey se almacenan en el mismo nodo. (Las operaciones que afecten a entidades almacenadas en el mismo nodo se realizarán mejor que aquellas que afecten a entidades almacenadas en nodos distintos). RowKey es el identificador exclusivo de una entidad dentro de una partición.

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();
}

Para información sobre las propiedades y los tipos de tabla, consulte Introducción al modelo de datos de Table service.

La clase TableRestProxy ofrece dos métodos alternativos para insertar entidades: insertOrMergeEntity y insertOrReplaceEntity. Para usar estos métodos, cree una nueva Entity y pásela como un parámetro para cualquiera de los métodos. Ambos métodos insertarán la entidad si todavía no existe. Si ya existe la entidad, insertOrMergeEntity actualizará los valores de las propiedades existentes y agregará las propiedades que no existan, mientras que insertOrReplaceEntity reemplazará por completo la entidad existente. En el siguiente ejemplo se muestra cómo usar el método insertOrMergeEntity. Si todavía no existe ninguna entidad con PartitionKey "tasksSeattle" y RowKey "1", se insertará. Sin embargo, si ya se insertó previamente (como se muestra en el ejemplo anterior), se actualizará la propiedad DueDate y se agregará la propiedad Status. Las propiedades Description y Location también se actualizan, pero con valores que a efectos prácticos no provocarán ningún cambio en ellas. Si estas dos últimas propiedades no se agregaron como se muestra en el ejemplo, sino que existían en la entidad objetivo, sus valores actuales permanecerán invariables.

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 />";
}

una sola entidad

El método TableRestProxy->getEntity permite recuperar una sola entidad consultando sus valores de PartitionKey y RowKey. En el ejemplo siguiente, la clave de partición tasksSeattle y la clave de fila 1 se pasan al método 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();

todas las entidades de una partición

Las consultas a entidades se basan en filtros (para más información, consulte Consulta de tablas y entidades). Para recuperar todas las entidades de una partición, utilice el filtro "PartitionKey eq partition_name". En el siguiente ejemplo se muestra cómo recuperar todas las entidades de la partición tasksSeattle pasando un filtro al método 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 />";
}

un subconjunto de entidades de una partición

El mismo patrón utilizado en el ejemplo anterior se puede aplicar a la recuperación de cualquier subconjunto de entidades de una partición. El subconjunto de entidades que recupere dependerá del filtro que utilice (para más información, consulte Consulta de tablas y entidades). En el siguiente ejemplo se muestra cómo usar un filtro para recuperar todas las entidades con un valor concreto para Location y un valor para DueDate anterior a una fecha determinada.

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 />";
}

un subconjunto de propiedades de las entidades

Es posible recuperar un subconjunto de propiedades de las entidades mediante una consulta. Esta técnica, denominada proyección, reduce el ancho de banda y puede mejorar el rendimiento de las consultas, en especial en el caso de entidades de gran tamaño. Para especificar la propiedad que desea recuperar, pase el nombre de la propiedad al método Query->addSelectField. Puede llamar a este método varias veces para agregar más propiedades. Tras ejecutar TableRestProxy->queryEntities, las entidades que se recuperen solo presentarán las propiedades seleccionadas. (Si desea recuperar un subconjunto de entidades de tabla, utilice un filtro tal y como se muestra en las consultas anteriores).

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 />";
}

Actualización de una entidad

Puede actualizar una entidad existente con los métodos Entity->setProperty y Entity->addProperty en la entidad y, a continuación, con una llamada a TableRestProxy->updateEntity. En el siguiente ejemplo se recupera una entidad, se modifica una propiedad, se elimina otra propiedad y se agrega una nueva propiedad. Tenga en cuenta que para eliminar una propiedad debe establecer su valor en 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 />";
}

Eliminación de una entidad

Para eliminar una entidad, pase el nombre de la tabla y los valores PartitionKey y RowKey de la entidad al método 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 />";
}

En las comprobaciones de simultaneidad, puede determinar que se elimine la propiedad Etag de una entidad utilizando el método DeleteEntityOptions->setEtag y pasando el objeto DeleteEntityOptions a deleteEntity como cuarto parámetro.

operaciones de tabla

El método TableRestProxy->batch permite ejecutar varias operaciones en una única solicitud. Este patrón consiste en agregar operaciones al objeto BatchRequest y, a continuación, pasar el objeto BatchRequest al método TableRestProxy->batch. Para agregar una operación a un objeto BatchRequest , puede llamar a cualquiera de los siguientes métodos varias veces:

• addInsertEntity (agrega una operación insertEntity)
• addUpdateEntity (agrega una operación updateEntity)
• addMergeEntity (agrega una operación mergeEntity)
• addInsertOrReplaceEntity (agrega una operación insertOrReplaceEntity)
• addInsertOrMergeEntity (agrega una operación insertOrMergeEntity)
• addDeleteEntity (agrega una operación deleteEntity)

En el siguiente ejemplo se muestra cómo ejecutar las operaciones insertEntity y deleteEntity en una única solicitud.

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 />";
}

Para más información sobre el procesamiento por lotes de las operaciones de Table, consulte Transacciones con grupos de entidades.

Eliminar una tabla

Finalmente, para eliminar una tabla, pase su nombre al método 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 />";
}

Pasos siguientes

Ahora que está familiarizado con los aspectos básicos de Azure Table service y Azure Cosmos DB, use estos vínculos para obtener más información.

• El Explorador de Microsoft Azure Storage es una aplicación independiente y gratuita de Microsoft que permite trabajar visualmente con los datos de Azure Storage en Windows, macOS y Linux.

• Centro para desarrolladores de PHP.