Az Azure Storage Table szolgáltatás vagy az Azure Cosmos DB for Table használata PHP-ből
A KÖVETKEZŐRE VONATKOZIK: Tábla
Figyelmeztetés
Ez a projekt a közösség életciklusának támogatási szakaszában van. Végül az összes társított ügyfélkódtár véglegesen ki lesz vonva. A projekt kivezetésével és alternatíváival kapcsolatos további információkért lásd : Kivonási értesítés: Azure Storage PHP-ügyfélkódtárak.
Tipp
A cikk tartalma az Azure Table Storage-ra és az Azure Cosmos DB for Tablere vonatkozik. A Table API egy prémium szintű ajánlat a table storage számára, amely átviteli sebességre optimalizált táblákat, globális elosztást és automatikus másodlagos indexeket kínál.
Ez a cikk bemutatja, hogyan hozhat létre táblákat, tárolhatja az adatokat, és hogyan hajthat végre CRUD-műveleteket az adatokon. Válassza ki az Azure Table szolgáltatást vagy az Azure Cosmos DB for Table szolgáltatást. A kódminták PHP nyelven íródtak, és az Azure Storage Table PHP-hoz készült ügyféloldali kódtárát használják. Az ismertetett forgatókönyvek a táblák létrehozásával és törlésével, valamint a táblaentitások beszúrásával, törlésével és lekérdezésével foglalkoznak.
Azure-szolgáltatásfiók létrehozása
A táblákkal az Azure Table Storage vagy az Azure Cosmos DB használatával dolgozhat. Ha többet szeretne megtudni a táblaajánlatok közötti különbségekről ebben a két szolgáltatásban, tekintse meg az API for Table áttekintését. Létre kell hoznia egy fiókot a használni kívánt szolgáltatáshoz. Az alábbi szakaszok bemutatják, hogyan hozható létre az Azure Table Storage és az Azure Cosmos DB-fiók is, de csak az egyiket használhatja.
Azure Table Storage
Az Azure Storage-fiók létrehozásának legegyszerűbb módja a Azure Portal használata. További tudnivalókért lásd: Create a storage account (Tárfiók létrehozása).
Ezenkívül az Azure PowerShell vagy az Azure CLI használatával is létrehozhat egy Azure-tárfiókot.
Ha jelenleg nem szeretne tárfiókot létrehozni, az Azure Storage Emulator használatával helyi környezetben is futtathatja és tesztelheti a kódot. További információ: Az Azure Storage Emulator használata fejlesztéshez és teszteléshez.
Azure Cosmos DB for Table
Az Azure Cosmos DB for Table-fiók létrehozásával kapcsolatos utasításokért lásd: Adatbázisfiók létrehozása.
PHP-alkalmazás létrehozása
A Storage Table szolgáltatás vagy az Azure Cosmos DB for Table eléréséhez egyetlen követelmény egy PHP-alkalmazás létrehozása, ha a kódon belül hivatkozik a PHP-hoz készült azure-storage-table SDK osztályaira. Az alkalmazás létrehozásához bármilyen fejlesztői eszközt (pl. Jegyzettömböt) használhat.
Ebben az útmutatóban az Azure Table Storage vagy az Azure Cosmos DB for Table olyan funkcióit használja, amelyek egy PHP-alkalmazásból hívhatók meg. Az alkalmazás helyileg vagy egy Azure-beli webes szerepkörön, feldolgozói szerepkörön vagy webhelyen futó kódban is futtatható.
Az ügyfélkönyvtár lekérése
Hozzon létre egy composer.json nevű fájlt a projekt gyökérkönyvtárában, és adja hozzá az alábbi kódot:
{ "require": { "microsoft/azure-storage-table": "*" } }
Töltse le a composer.phar fájlt a gyökérkönyvtárba.
Nyissa meg a parancssort, és hajtsa végre az alábbi parancsot a projekt gyökérkönyvtárában:
php composer.phar install
Másik megoldásként navigáljon az Azure Storage Table PHP ügyféloldali kódtárához a GitHubon, és klónozza a forráskódot.
Szükséges referenciák hozzáadása
A Storage Table szolgáltatás vagy az Azure Cosmos DB API-k használatához a következőket kell tennie:
- Hivatkozzon az automatikus betöltő fájlra a require_once utasítás használatával, és
- hivatkozzon bármely felhasznált osztályra.
A következő példa bemutatja, hogyan használható az automatikus betöltő fájl és hogyan lehet a TableRestProxy osztályra hivatkozni.
require_once 'vendor/autoload.php';
use MicrosoftAzure\Storage\Table\TableRestProxy;
Az itt látható példákban az require_once
utasítás mindig megjelenik, de csak a végrehajtáshoz szükséges osztályokra hivatkozunk.
A kapcsolati karakterlánc hozzáadása
Csatlakozhat az Azure Storage-fiókhoz vagy az Azure Cosmos DB for Table-fiókhoz. Kérje le a kapcsolati karakterlánc a használt fiók típusa alapján.
Storage Table szolgáltatási kapcsolat hozzáadása
Storage Table szolgáltatási ügyfél példányosításához először is rendelkeznie kell egy érvényes kapcsolati sztringgel. A Storage szolgáltatás kapcsolati sztringjének formátuma:
$connectionString = "DefaultEndpointsProtocol=[http|https];AccountName=[yourAccount];AccountKey=[yourKey]"
Storage Emulator-kapcsolat hozzáadása
Az emulátor tárolójának elérése:
UseDevelopmentStorage = true
Azure Cosmos DB-kapcsolat hozzáadása
Azure Cosmos DB Table-ügyfél példányosításához először is rendelkeznie kell egy érvényes kapcsolati sztringgel. Az Azure Cosmos DB kapcsolati sztringjének formátuma:
$connectionString = "DefaultEndpointsProtocol=[https];AccountName=[myaccount];AccountKey=[myaccountkey];TableEndpoint=[https://myendpoint/]";
Azure Table Service-ügyfél vagy Azure Cosmos DB-ügyfél létrehozásához a TableRestProxy osztályt kell használnia. A következőket teheti:
- A kapcsolati sztringet továbbíthatja közvetlenül, vagy
- A CloudConfigurationManager (CCM) használatával ellenőrizze a kapcsolati karakterlánc több külső forrását:
- Alapértelmezés szerint csak egy külső forrást támogat: a környezeti változókat.
- Új forrásokat a
ConnectionStringSource
osztály kiterjesztésével adhat hozzá.
Az itt ismertetett példák esetében a kapcsolati sztringet közvetlenül továbbítjuk.
require_once 'vendor/autoload.php';
use MicrosoftAzure\Storage\Table\TableRestProxy;
$tableClient = TableRestProxy::createTableService($connectionString);
Tábla létrehozása
A TableRestProxy objektum lehetővé teszi egy tábla létrehozását a createTable metódussal. Tábla létrehozásakor beállíthatja a Table Service időkorlátját. A Table Service időtúllépésével kapcsolatos további információkért lásd: Időtúllépések beállítása a Table Service-műveletekhez.
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
}
További információt a táblák nevére vonatkozó korlátozásokról a Table Service adatmodelljét ismertető témakörben talál.
Entitás hozzáadása a táblához
Ha entitást szeretne hozzáadni egy táblához, hozzon létre egy új Entity objektumot, és adja át a TableRestProxy-insertEntity> elemnek. Entitás létrehozásakor meg kell adnia egy és RowKey
értéketPartitionKey
. Ezek az entitások egy entitás egyedi azonosítói, és olyan értékek, amelyek gyorsabban lekérdezhetők, mint más entitástulajdonságok. A rendszer a PartitionKey
használatával automatikusan elosztja a tábla entitásait számos tárcsomópont között. Az ugyanazzal a PartitionKey
tulajdonsággal rendelkező entitások tárolása ugyanazon a csomóponton történik. Az ugyanazon a csomóponton tárolt több entitáson végzett műveletek jobban teljesítenek, mint a különböző csomópontokon tárolt entitásokon. A RowKey
az entitás egyedi azonosítója egy partíción belül.
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();
}
További információt a táblatulajdonságokról és -típusokról a Table Service adatmodelljét ismertető témakörben talál.
A TableRestProxy osztály két alternatív metódust kínál az entitások beszúrásához: az insertOrMergeEntity és az insertOrReplaceEntity metódust. A két metódus használatához hozzon létre egy új entitást, és továbbítsa azt valamelyik metódusnak paraméterként. Minden metódus beszúrja az entitást, ha nem létezik. Ha az entitás már létezik, az insertOrMergeEntity frissíti a tulajdonságértékeket, ha a tulajdonságok már léteznek, és új tulajdonságokat ad hozzá, ha nem léteznek, míg az insertOrReplaceEntity teljes mértékben lecserél egy meglévő entitást. Az alábbi példa a használatát insertOrMergeEntity
mutatja be. Ha a "tasksSeattle" és RowKey
az "1" entitás PartitionKey
még nem létezik, akkor az entitás be lesz szúrva. Ha azonban már létezik (az előző példában látható módon), a DueDate
tulajdonság frissül, és hozzáadja a Status
tulajdonságot. A Description
és Location
tulajdonságok is frissülnek, de olyan értékekkel, amelyek révén lényegében nem változnak. Ha ez utóbbi két tulajdonság nem lett hozzáadva a példában látható módon, de léteznek a célentitáson, a meglévő értékek változatlanok maradnak.
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 />";
}
Egyetlen entitás lekérdezése
A TableRestProxy-getEntity> metódus lehetővé teszi egyetlen entitás lekérését a és RowKey
a lekérdezésévelPartitionKey
. Az itt látható példában a partíciókulcs tasksSeattle
és a sorkulcs 1
a getEntity metódusnak lesz átadva.
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();
Egy partíció összes entitásának lekérése
Az entitás-lekérdezések szűrők használatával jönnek létre. További információ: Táblák és entitások lekérdezése. A partíció összes entitásának lekéréséhez használja a szűrőt PartitionKey eq partition_name
. Az alábbi példa bemutatja, hogyan kérheti le a tasksSeattle
partíció minden entitását úgy, hogy egy szűrőt továbbít a queryEntities metódusnak.
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 />";
}
Entitások egy részének lekérése egy partíción belül
Az előző példában használt minta felhasználható entitások bármilyen részhalmazának lekérésére egy partíción belül. A használt szűrő határozza meg a lekért entitások részhalmazát. További információ: Táblák és entitások lekérdezése. Az alábbi példa bemutatja, hogyan lehet szűrővel lekérni a megadott Location
dátumnál kisebb dátumú entitásokat DueDate
.
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 />";
}
Az entitástulajdonságok egy részének lekérése
Egy lekérdezéssel lekérhető az entitástulajdonságok egy része. Ez a leképezésnek hívott technika csökkenti a sávszélesség felhasználását, és javíthatja a lekérdezési teljesítményt, főleg a nagy entitások esetén. A beolvasandó tulajdonság megadásához adja meg a tulajdonság nevét a Query->addSelectField
metódusnak. Ezt a metódust többször is meghívhatja, ha több tulajdonságot szeretne hozzáadni. A végrehajtás TableRestProxy->queryEntities
után a visszaadott entitások csak a kiválasztott tulajdonságokkal rendelkeznek. Ha a Table entitások egy részhalmazát szeretné visszaadni, használjon szűrőt az előző lekérdezésekben látható módon.
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 />";
}
Entitás frissítése
Egy meglévő entitást frissíthet az entitás Entity-setProperty> és Entity-addProperty> metódusával, majd meghívhatja a TableRestProxy-updateEntity> metódust. A következő példa visszaad egy entitást, módosít egy tulajdonságot, eltávolít egy másik tulajdonságot, és hozzáad egy újat. A tulajdonságot úgy távolíthatja el, hogy null értékűre állítja.
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 />";
}
Entitás törlése
Egy entitás törléséhez adja meg a tábla nevét, valamint az entitás PartitionKey
nevét és RowKey
a TableRestProxy-deleteEntity> metódust .
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 />";
}
Egyidejűségi ellenőrzések esetén beállíthatja, hogy egy entitás Etagje törölhető legyen a DeleteEntityOptions-setEtag> metódussal, és a DeleteEntityOptions objektumot a deleteEntity paraméterre továbbítja negyedik paraméterként.
Kötegelt táblaműveletek
A TableRestProxy-batch> metódussal több műveletet is végrehajthat egyetlen kérelemben. Ebben a mintában műveleteket kell hozzáadni a BatchRequest objektumhoz, majd átadni a BatchRequest objektumot a TableRestProxy-batch> metódusnak. Ha egy műveletet szeretne hozzáadni a BatchRequest objektumhoz, az alábbi metódusok bármelyikét többször is meghívhatja:
Description | |
---|---|
addInsertEntity |
Beszúrási művelet hozzáadása |
addUpdateEntity |
UpdateEntity művelet hozzáadása |
addMergeEntity |
MergeEntity művelet hozzáadása |
addInsertOrReplaceEntity |
InsertOrReplaceEntity művelet hozzáadása |
addInsertOrMergeEntity |
InsertOrMergeEntity művelet hozzáadása |
addDeleteEntity |
DeleteEntity művelet hozzáadása |
A következő példa az insertEntity és a deleteEntity művelet egy kérésben történő végrehajtásának módját mutatja be.
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 />";
}
További információk a táblaműveletek kötegeléséről: Entitáscsoport-tranzakciók végrehajtása.
Tábla törlése
Végül egy tábla törléséhez adja át a tábla nevét a TableRestProxy-deleteTable> metódusnak.
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 />";
}
Kapcsolódó tartalom
- A Microsoft Azure Storage Explorer egy ingyenes, önálló alkalmazás, amelynek segítségével vizuálisan dolgozhat Azure Storage-adatokkal Windows, macOS és Linux rendszereken.
- PHP fejlesztői központ.