Utilisation de l’API du service de Table de Stockage Azure ou de Azure Cosmos DB for Table à partir de code PHP

S’APPLIQUE À : Table

Cet article vous montre comment créer des tables, stocker vos données et effectuer des opérations CRUD sur les données. Choisissez le service Table Azure ou Azure Cosmos DB for Table. Les exemples sont écrits en PHP et utilisent la bibliothèque de client PHP pour le service de Table de Stockage Azure. Les tâches couvertes incluent la création et la suppression d’une table, ainsi que l’insertion, la suppression et l’interrogation d’entités dans une table.

Créer un compte de service Azure

Vous pouvez travailler avec des tables à l’aide du Stockage Table Azure ou d’Azure Cosmos DB. Pour en savoir plus sur les différences entre les offres de table dans ces deux services, consultez la Vue d’ensemble de l’API pour Table. Vous devez créer un compte pour le service que vous allez utiliser. Les sections suivantes montrent comment créer un stockage Table Azure et le compte Azure Cosmos DB, mais vous pouvez simplement utiliser l’un d’eux.

Stockage Table Azure

Le moyen le plus simple de créer un compte de stockage Azure est d’utiliser le portail Azure. Pour plus d’informations, consultez la page Créer un compte de stockage.

Il est également possible de créer un compte de stockage Azure avec Azure PowerShell ou Azure CLI.

Si vous préférez ne pas créer de compte de stockage pour le moment, vous avez la possibilité d’utiliser l’émulateur de stockage Azure pour exécuter et tester votre code dans un environnement local. Pour plus d’informations, consultez Utiliser l’émulateur de stockage Azure pour le développement et le test.

Azure Cosmos DB for Table

Pour obtenir des instructions sur la création d’un compte Azure Cosmos DB for Table, consultez Créer un compte de base de données.

Création d'une application PHP

La création d’une application PHP pour accéder à l’API du service de Table de Stockage Azure ou à Azure Cosmos DB for Table présente une seule exigence : référencer des classes du Kit de développement logiciel (SDK) de Table de Stockage Azure pour PHP à partir de votre code. Vous pouvez utiliser tous les outils de développement pour créer votre application, y compris Bloc-notes.

Dans ce guide, vous utilisez les fonctionnalités Stockage Table Azure ou Azure Cosmos DB for Table qui peuvent être appelées à partir d’une application PHP. L’application peut s’exécuter localement ou dans du code exécuté au sein d’un rôle web Azure, d’un rôle de travail ou d’un site web.

Obtenir la bibliothèque de client

1. Créez un fichier nommé composer.json à la racine de votre projet et ajoutez-y le code suivant :

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

2. Téléchargez composer.phar à la racine.

3. Ouvrez une invite de commandes et exécutez la commande suivante à la racine du projet :

   php composer.phar install
   

   Vous pouvez également accéder à la bibliothèque de client PHP du service de Table de Stockage Azure sur GitHub pour cloner le code source.

Ajouter les références requises

Pour utiliser les API du service de Table de Stockage Azure ou d’Azure Cosmos DB, vous devez :

• référencer le fichier de chargeur automatique à l’aide de l’instruction require_once ; et
• référencer toutes les classes utilisées.

L’exemple suivant montre comment inclure le fichier du chargeur automatique et référencer la classe TableRestProxy.

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

Dans les exemples ici, l’instruction require_once est toujours affichée, mais seules les classes nécessaires à l’exécution de l’exemple sont référencées.

Ajouter votre chaîne de connexion

Vous pouvez vous connecter au compte de stockage Azure ou au compte Azure Cosmos DB for Table. Obtenez les chaîne de connexion en fonction du type de compte que vous utilisez.

Ajouter une connexion au service de Table de Stockage Azure

Pour instancier un client de service de Table de Stockage Azure, vous devez disposer au préalable d’une chaîne de connexion valide. Le format de la chaîne de connexion au service de Table de Stockage Azure est le suivant :

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

Ajouter une connexion à l’émulateur de stockage

Pour accéder au stockage de l’émulateur :

UseDevelopmentStorage = true

Ajouter une connexion à Azure Cosmos DB

Pour instancier un client de Table Azure Cosmos DB, vous devez disposer au préalable d’une chaîne de connexion valide. Le format de la chaîne de connexion à Azure Cosmos DB est le suivant :

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

Pour créer un client de service de Table de Stockage Azure ou un client Azure Cosmos DB, vous devez utiliser la classe TableRestProxy. Vous pouvez :

• lui transmettre directement la chaîne de connexion ; ou
• utiliser CloudConfigurationManager (CCM) pour vérifier plusieurs sources externes pour la chaîne de connexion :
  • Par défaut, il prend en charge une source externe : les variables d’environnement.
  • Vous pouvez ajouter de nouvelles sources en étendant la classe ConnectionStringSource.

Dans les exemples ci-dessous, la chaîne de connexion est passée directement.

require_once 'vendor/autoload.php';

use MicrosoftAzure\Storage\Table\TableRestProxy;

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

Créer une table

Vous pouvez créer une table avec un objet TableRestProxy via la méthode createTable. Au moment de créer une table, vous pouvez définir le délai d'expiration du service de Table. Pour plus d’informations sur le délai d’expiration du service Table, consultez Définition de délais d’expiration pour les opérations de service de table.

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
}

Pour plus d’informations sur les restrictions au niveau des noms de table, consultez Présentation du modèle de données du service de Table.

Ajout d'une entité à une table

Pour ajouter une entité à une table, créez un objet Entity et transmettez-le à TableRestProxy->insertEntity. Lorsque vous créez une entité, vous devez spécifier un PartitionKey et RowKey. Ces entités sont les identificateurs uniques d’une entité et sont des valeurs qui peuvent être interrogées plus rapidement que d’autres propriétés d’entité. Le système utilise PartitionKey pour distribuer automatiquement les entités de la table sur plusieurs nœuds de stockage. Les entités partageant la même clé PartitionKey sont stockées sur le même nœud. Les opérations sur plusieurs entités stockées sur le même nœud fonctionnent mieux que sur les entités stockées sur différents nœuds. La clé RowKey est l’ID unique d’une entité au sein d’une partition.

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

Pour plus d’informations sur les propriétés et les types de table, consultez Présentation du modèle de données du service de Table.

La classe TableRestProxy offre deux autres méthodes pour insérer des entités : insertOrMergeEntity et insertOrReplaceEntity. Pour utiliser ces méthodes, créez un objet Entity et transmettez-le en tant que paramètre à l'une ou l'autre des méthodes. Chaque méthode insère l’entité si elle n’existe pas. Si l’entité existe déjà, insertOrMergeEntity met à jour les valeurs de propriété si les propriétés existent déjà et ajoute de nouvelles propriétés si elles n’existent pas, tandis que insertOrReplaceEntity remplace complètement une entité existante. L'exemple suivant montre comment utiliser insertOrMergeEntity. Si l’entité avec PartitionKey « tasksSeattle » et RowKey « 1 » n’existe pas déjà, cette entité est alors insérée. Toutefois, si elle existe déjà (comme illustré dans l’exemple précédent), la DueDate propriété est mise à jour et la Status propriété est ajoutée. Les propriétés Description et Location sont également mises à jour, mais avec des valeurs qui de fait les laissent inchangées. Si ces deux dernières propriétés n’ont pas été ajoutées comme indiqué dans l’exemple, mais qu’elles existaient sur l’entité cible, leurs valeurs existantes resteraient inchangées.

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

Extraction d'une seule entité

La méthode TableRestProxy->getEntity vous permet de récupérer une seule entité via une requête portant sur ses clés PartitionKey et RowKey. Dans l’exemple ici, la clé tasksSeattle de partition et la clé 1 de ligne sont passées à la méthode 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();

Extraction de toutes les entités d'une partition

Les requêtes d’entité sont construites à l’aide de filtres. Pour plus d’informations, consultez Interrogation de tables et d’entités. Pour récupérer toutes les entités dans la partition, utilisez le filtre PartitionKey eq partition_name. L’exemple suivant montre comment récupérer toutes les entités de la partition tasksSeattle en passant un filtre à la méthode 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 />";
}

Extraction d'un sous-ensemble d'entités dans une partition

Pour extraire un sous-ensemble d'entités dans une partition, il est possible d'utiliser le modèle de l'exemple précédent. Le filtre que vous utilisez détermine le sous-ensemble d’entités que vous récupérez. Pour plus d’informations, consultez Interrogation de tables et d’entités. L’exemple suivant montre comment utiliser un filtre pour récupérer toutes les entités avec une date spécifique Location et une DueDate date inférieure à une date spécifiée.

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

Extraction d'un sous-ensemble de propriétés d'entité

Une requête peut extraire un sous-ensemble de propriétés d'entité. Cette technique, nommée projection, réduit la consommation de bande passante et peut améliorer les performances des requêtes, notamment pour les entités volumineuses. Pour spécifier une propriété à récupérer, transmettez le nom de la propriété à la Query->addSelectField méthode . Vous pouvez appeler cette méthode plusieurs fois pour ajouter des propriétés supplémentaires. Une fois que vous avez exécuté TableRestProxy->queryEntities, les entités retournées n’auront que les propriétés sélectionnées. Si vous souhaitez retourner un sous-ensemble d’entités Table, utilisez un filtre comme indiqué dans les requêtes précédentes.

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

Mise à jour d'une entité

Vous pouvez mettre à jour une entité existante en lui appliquant les méthodes Entity->setProperty and Entity->addProperty, puis en appelant TableRestProxy->updateEntity. Dans l'exemple suivant, une entité est extraite, une propriété modifiée, une autre propriété supprimée et une nouvelle propriété ajoutée. Vous pouvez supprimer une propriété en définissant sa valeur sur 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 />";
}

Suppression d’une entité

Pour supprimer une entité, passez le nom de la table ainsi que les clés PartitionKey et RowKey à la méthode 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 />";
}

Pour les contrôles d’accès concurrentiel, vous pouvez définir la suppression de la propriété Etag d’une entité en employant la méthode DeleteEntityOptions->setEtag et en transmettant l’objet DeleteEntityOptions à deleteEntity en tant que quatrième paramètre.

Traitement par lots d'opérations de table

La méthode TableRestProxy->batch permet d’exécuter plusieurs opérations dans une même demande. Ce modèle implique d’ajouter des opérations à l’objet BatchRequest et de transmettre l’objet BatchRequest à la méthode TableRestProxy->batch. Pour ajouter une opération à un objet BatchRequest , vous pouvez appeler l'une des méthodes suivantes à plusieurs reprises :

L’exemple suivant montre comment exécuter des opérations insertEntity et deleteEntity en une seule requête.

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

Pour plus d’informations sur le traitement par lots d’opérations de table, consultez Exécution de transactions de groupe d’entités.

Suppression d’une table

Enfin, pour supprimer une table, transmettez son nom à la méthode 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 />";
}

Contenu connexe

• Microsoft Azure Storage Explorer est une application autonome et gratuite de Microsoft qui vous permet d’exploiter visuellement les données de Stockage Azure sur Windows, macOS et Linux.
• Centre de développement PHP.