Azure Storage Table-service of Azure Cosmos DB for Table gebruiken vanuit PHP

VAN TOEPASSING OP: Tabel

Waarschuwing

Dit project bevindt zich in de ondersteuningsfase van de community van de levenscyclus. Uiteindelijk worden alle gekoppelde clientbibliotheken definitief buiten gebruik gesteld. Zie Kennisgeving over buitengebruikstelling : Azure Storage PHP-clientbibliotheken voor meer informatie over buitengebruikstelling en alternatieven voor het gebruik van dit project.

Tip

De inhoud in dit artikel is van toepassing op Azure Table Storage en Azure Cosmos DB for Table. De API voor Tabel is een premium-aanbieding voor tabelopslag die tabellen die zijn geoptimaliseerd voor doorvoer, wereldwijde distributie en automatische secundaire indexen biedt.

Dit artikel laat zien hoe u tabellen maakt, uw gegevens opslaat en CRUD-bewerkingen op de gegevens uitvoert. Kies de Azure Table-service of de Azure Cosmos DB for Table. De voorbeelden zijn geschreven in PHP en maken gebruik van de clientbibliotheek voor PHP voor Azure Storage-tabellen. De volgende scenario's worden behandeld: een tabel maken en verwijderen en entiteiten in een tabel invoegen, verwijderen en hierop query's uitvoeren.

Azure-serviceaccount maken

U kunt in Azure Table Storage of in Azure Cosmos DB met tabellen werken. Zie overzicht van API for Table voor meer informatie over de verschillen tussen tabelaanbiedingen in deze twee services. U moet een account maken voor de service die u gaat gebruiken. De volgende secties laten zien hoe u zowel een Azure Table Storage- als een Azure Cosmos DB-account maakt. U kunt echter slechts één daarvan gebruiken.

Azure-tabelopslag

De eenvoudigste manier om uw eerste Azure-opslagaccount te maken, is via de Azure-portal. Zie Een opslagaccount maken voor meer informatie.

U kunt ook een Azure Storage-account maken met behulp van Azure PowerShell of de Azure CLI.

Als u op dit moment liever nog geen opslagaccount maakt, kunt u ook de Azure-opslagemulator gebruiken om de code in een lokale omgeving uit te voeren en te testen. Zie De Azure-opslagemulator gebruiken voor ontwikkelen en testen voor meer informatie.

Azure Cosmos DB voor tabel

Zie Een databaseaccount maken voor instructies voor het maken van een Azure Cosmos DB for Table-account.

Een PHP-toepassing maken

De enige vereiste voor het maken van een PHP-toepassing voor toegang tot de Storage Table-service of Azure Cosmos DB for Table is om vanuit uw code te verwijzen naar klassen in de azure-storage-table-SDK voor PHP. U kunt elk ontwikkelprogramma gebruiken om uw toepassing te maken, waaronder Kladblok.

In deze handleiding gebruikt u Azure Table Storage of Azure Cosmos DB for Table-functies die kunnen worden aangeroepen vanuit een PHP-toepassing. De toepassing kan lokaal of in code worden uitgevoerd binnen een Azure-webrol, werkrol of website.

De clientbibliotheek ophalen

  1. Maak een bestand met de naam composer.json in de hoofdmap van uw project en voeg de volgende code toe:

    {
    "require": {
     "microsoft/azure-storage-table": "*"
    }
    }
    
  2. Download composer.phar naar de hoofdmap.

  3. Open een opdrachtprompt en voer de volgende opdracht uit in de hoofdmap van uw project:

    php composer.phar install
    

    U kunt ook naar de clientbibliotheek voor PHP voor Azure Storage-tabellen op GitHub gaan om de broncode te klonen.

Vereiste verwijzingen toevoegen

Als u de Azure Storage-tabelservice of Azure Cosmos DB-API's wilt gebruiken, moet u het volgende doen:

  • Maak een verwijzing naar het autoloaderbestand met de instructie require_once en
  • een verwijzing naar alle klassen die u gebruikt.

In het volgende voorbeeld wordt getoond hoe u het autoloaderbestand opneemt en een verwijzing maakt naar de klasse TableRestProxy.

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

In de voorbeelden hier wordt de require_once instructie altijd weergegeven, maar alleen naar de klassen die nodig zijn om het voorbeeld uit te voeren, wordt verwezen.

Uw verbindingsreeks toevoegen

U kunt verbinding maken met het Azure-opslagaccount of het Azure Cosmos DB for Table-account. Haal de verbindingsreeks op op basis van het type account dat u gebruikt.

Een verbinding voor de Azure Storage-tabelservice toevoegen

U moet eerst over een geldige verbindingsreeks beschikken voordat u een instantie kunt maken van een client voor de Azure Storage-tabelservice. De indeling voor de verbindingsreeks voor de Azure Storage-tabelservice is:

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

Een verbinding voor de opslagemulator toevoegen

U kunt als volgt toegang krijgen tot de opslagemulator:

UseDevelopmentStorage = true

Een Azure Cosmos DB-verbinding toevoegen

U moet eerst over een geldige verbindingsreeks beschikken voordat u een instantie kunt maken van een Azure Cosmos DB Table-client. De indeling voor de Azure Cosmos DB-verbindingsreeks is:

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

Als u een client voor de Azure Storage-tabelservice of een Azure Cosmos DB-client wilt maken, moet u de klasse TableRestProxy gebruiken. U kunt:

  • De verbindingsreeks rechtstreeks aan deze klasse doorgeven of
  • De CCM (CloudConfigurationManager) gebruiken om meerdere externe bronnen te controleren op de verbindingsreeks:
    • Deze wordt standaard geleverd met ondersteuning voor één externe bron: omgevingsvariabelen.
    • U kunt nieuwe bronnen toevoegen door de klasse ConnectionStringSource uit te breiden.

In de voorbeelden die hier worden beschreven, wordt de verbindingsreeks rechtstreeks doorgegeven.

require_once 'vendor/autoload.php';

use MicrosoftAzure\Storage\Table\TableRestProxy;

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

Een tabel maken

Met het object TableRestProxy kunt u een tabel maken via de methode createTable. Bij het maken van een tabel kunt u de time-out voor de tabelservice instellen. Zie Time-outs instellen voor tabelservicebewerkingen voor meer informatie over de time-out van de tabelservice.

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
}

Zie Het gegevensmodel van de tabelservice voor meer informatie over beperkingen voor tabelnamen.

Een entiteit toevoegen aan een tabel

Als u een entiteit aan een tabel wilt toevoegen, maakt u een nieuw entiteitsobject en geeft u dit door aan TableRestProxy-insertEntity>. Wanneer u een entiteit maakt, moet u een PartitionKey en RowKeyopgeven. Deze entiteiten zijn de unieke id's voor een entiteit en zijn waarden die sneller kunnen worden opgevraagd dan andere entiteitseigenschappen. Het systeem maakt gebruik van PartitionKey om de entiteiten van de tabel automatisch over veel Storage-knooppunten te verdelen. Entiteiten met dezelfde PartitionKey worden op hetzelfde knooppunt opgeslagen. Bewerkingen op meerdere entiteiten die zijn opgeslagen op hetzelfde knooppunt, presteren beter dan op entiteiten die zijn opgeslagen op verschillende knooppunten. De RowKey is de unieke id van een entiteit binnen een partitie.

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

Zie Het gegevensmodel van de tabelservice voor meer informatie over tabeleigenschappen en -typen.

U kunt met de klasse TableRestProxy op twee manieren entiteiten invoegen: insertOrMergeEntity en insertOrReplaceEntity. Als u deze methoden wilt gebruiken, maakt u een nieuwe entiteit en geeft u deze als parameter door aan een van de methoden. Elke methode voegt de entiteit in als deze niet bestaat. Als de entiteit al bestaat, werkt insertOrMergeEntity de eigenschapswaarden bij als de eigenschappen al bestaan en worden nieuwe eigenschappen toegevoegd als deze nog niet bestaan, terwijl insertOrReplaceEntity een bestaande entiteit volledig vervangt. In het volgende voorbeeld ziet u hoe u gebruikt insertOrMergeEntity. Als de entiteit met PartitionKey 'tasksSeattle' en RowKey '1' nog niet bestaat, wordt die entiteit vervolgens ingevoegd. Als deze echter al bestaat (zoals in het vorige voorbeeld), wordt de DueDate eigenschap bijgewerkt en wordt de Status eigenschap toegevoegd. De eigenschappen Description en Location worden ook bijgewerkt, maar met waarden waardoor ze feitelijk ongewijzigd blijven. Als deze laatste twee eigenschappen niet zijn toegevoegd, zoals wordt weergegeven in het voorbeeld, maar wel bestaan op de doelentiteit, blijven de bestaande waarden ongewijzigd.

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

Eén entiteit ophalen

Met de methode TableRestProxy-getEntity> kunt u één entiteit ophalen door een query uit te voeren op PartitionKey en RowKey. In het voorbeeld hier worden de partitiesleutel tasksSeattle en rijsleutel 1 doorgegeven aan de methode 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();

Alle entiteiten in een partitie ophalen

Entiteitsquery's worden samengesteld met behulp van filters. Zie Query's uitvoeren op tabellen en entiteiten voor meer informatie. Als u alle entiteiten in de partitie wilt ophalen, gebruikt u het filter PartitionKey eq partition_name. In het volgende voorbeeld wordt getoond hoe u alle entiteiten in de partitie tasksSeattle ophaalt door een filter door te geven aan de methode 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 />";
}

Een subset van entiteiten in een partitie ophalen

Het patroon uit het vorige voorbeeld kan ook worden gebruikt voor het ophalen van een subset van entiteiten in een partitie. Het filter dat u gebruikt, bepaalt de subset van entiteiten die u ophaalt. Zie Query's uitvoeren op tabellen en entiteiten voor meer informatie. In het volgende voorbeeld ziet u hoe u een filter gebruikt om alle entiteiten op te halen met een specifieke Location en een DueDate datum die kleiner is dan een opgegeven datum.

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

Een subset van entiteitseigenschappen ophalen

U kunt met een query een subset van entiteitseigenschappen ophalen. Deze methode, projectie genoemd, verbruikt minder bandbreedte en kan de queryprestaties verbeteren, vooral bij grote entiteiten. Als u een eigenschap wilt opgeven die moet worden opgehaald, geeft u de naam van de eigenschap door aan de Query->addSelectField methode. U kunt deze methode meerdere keren aanroepen om meer eigenschappen toe te voegen. Nadat u hebt uitgevoerd TableRestProxy->queryEntities, hebben de geretourneerde entiteiten alleen de geselecteerde eigenschappen. Als u een subset van tabelentiteiten wilt retourneren, gebruikt u een filter zoals weergegeven in de vorige query's.

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

Een entiteit bijwerken

U kunt een bestaande entiteit bijwerken met behulp van de methoden Entity-setProperty> en Entity-addProperty> op de entiteit en vervolgens TableRestProxy-updateEntity> aanroepen. In het volgende voorbeeld wordt een entiteit opgehaald, één eigenschap gewijzigd, een andere eigenschap verwijderd en wordt een nieuwe eigenschap toegevoegd. U kunt een eigenschap verwijderen door de waarde in te stellen op 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 />";
}

Een entiteit verwijderen

Als u een entiteit wilt verwijderen, geeft u de tabelnaam en de en RowKey van PartitionKey de entiteit door aan de methode 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 />";
}

Voor gelijktijdigheidscontroles kunt u de Etag instellen voor een entiteit die moet worden verwijderd door de methode DeleteEntityOptions-setEtag> te gebruiken en het object DeleteEntityOptions door te geven aan deleteEntity als vierde parameter.

Batchbewerkingen voor tabellen

Met de methode TableRestProxy-batch> kunt u meerdere bewerkingen in één aanvraag uitvoeren. Het patroon hier omvat het toevoegen van bewerkingen aan het BatchRequest-object en het vervolgens doorgeven van het BatchRequest-object aan de TableRestProxy-batch-methode>. Als u een bewerking wilt toevoegen aan een BatchRequest-object, kunt u een van de volgende methoden meerdere keren aanroepen:

Description
addInsertEntity Voegt een insertEntity-bewerking toe
addUpdateEntity Een updateEntity-bewerking toevoegen
addMergeEntity Voegt een mergeEntity-bewerking toe
addInsertOrReplaceEntity Voegt een insertOrReplaceEntity-bewerking toe
addInsertOrMergeEntity Voegt een insertOrMergeEntity-bewerking toe
addDeleteEntity Voegt een deleteEntity-bewerking toe

In het volgende voorbeeld wordt getoond hoe u de bewerkingen insertEntity en deleteEntity uitvoert in één aanvraag.

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

Zie Entiteitsgroepstransacties uitvoeren voor meer informatie over batchbewerkingen voor tabellen.

Een tabel verwijderen

Als u ten slotte een tabel wilt verwijderen, geeft u de tabelnaam door aan de methode 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 />";
}