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
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": "*" } }
Download composer.phar naar de hoofdmap.
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 RowKey
opgeven. 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 />";
}
Gerelateerde inhoud
- Microsoft Azure Storage Explorer is een gratis, zelfstandige app van Microsoft waarmee u visueel met Azure Storage-gegevens kunt werken in Windows, macOS en Linux.
- PHP-ontwikkelaarscentrum.