Jak używać usługi Azure Storage Table Service lub usługi Azure Cosmos DB dla tabel w języku PHP
DOTYCZY: Tabela
Ostrzeżenie
Ten projekt znajduje się na etapie wsparcia społeczności w cyklu życia. Ostatecznie wszystkie skojarzone biblioteki klienckie zostaną trwale wycofane. Aby uzyskać więcej informacji na temat wycofywania i alternatyw dla korzystania z tego projektu, zobacz Powiadomienie o wycofaniu: Biblioteki klienta PHP usługi Azure Storage.
Porada
Zawartość tego artykułu dotyczy usług Azure Table Storage i Azure Cosmos DB dla tabel. Interfejs API dla tabel to oferta Premium dla magazynu tabel, która oferuje tabele zoptymalizowane pod kątem przepływności, dystrybucję globalną i automatyczne indeksy pomocnicze.
W tym artykule pokazano, jak tworzyć tabele, przechowywać dane i wykonywać operacje CRUD na danych. Wybierz usługę Azure Table Service lub usługę Azure Cosmos DB dla tabeli. Przykłady są napisane w języku PHP i korzystają z biblioteki klienta usługi Azure Table Storage dla języka PHP. Przedstawione scenariusze obejmują tworzenie i usuwanie tabel, wstawianie i usuwanie jednostek w tabeli oraz wykonywanie zapytań dotyczących jednostek.
Tworzenie konta usługi platformy Azure
Możesz pracować z tabelami przy użyciu usługi Azure Table Storage lub usługi Azure Cosmos DB. Aby dowiedzieć się więcej o różnicach między ofertami tabel w tych dwóch usługach, zobacz omówienie interfejsu API dla tabel. Musisz utworzyć konto dla usługi, której będziesz używać. W poniższych sekcjach pokazano, jak utworzyć zarówno usługę Azure Table Storage, jak i konto usługi Azure Cosmos DB, jednak możesz po prostu użyć jednego z nich.
Azure Table Storage
Najprostszym sposobem utworzenia konta usługi Azure Storage jest użycie Azure Portal. Więcej informacji można znaleźć w temacie Tworzenie konta magazynu.
Możesz utworzyć konto usługi Azure Storage przy użyciu programu Azure PowerShell lub interfejsu wiersza polecenia platformy Azure.
Jeśli w tej chwili nie chcesz tworzyć konta magazynu, możesz również użyć emulatora usługi Azure Storage do uruchomienia i przetestowania kodu w środowisku lokalnym. Aby uzyskać więcej informacji, zobacz Use the Azure Storage Emulator for development and testing (Używanie emulatora usługi Azure Storage do programowania i testowania).
Usługa Azure Cosmos DB dla tabeli
Aby uzyskać instrukcje dotyczące tworzenia konta usługi Azure Cosmos DB dla tabel, zobacz Tworzenie konta bazy danych.
Tworzenie aplikacji języka PHP
Jedynym wymaganiem do utworzenia aplikacji PHP w celu uzyskania dostępu do usługi Storage Table Service lub usługi Azure Cosmos DB dla tabeli jest odwołanie się do klas w zestawie SDK azure-storage-table dla języka PHP z poziomu kodu. Do utworzenia aplikacji możesz użyć dowolnych narzędzi programistycznych, w tym programu Notatnik.
W tym przewodniku użyjesz usługi Azure Table Storage lub Usługi Azure Cosmos DB dla funkcji tabel, które można wywołać z poziomu aplikacji PHP. Aplikacja może działać lokalnie lub w kodzie działającym w ramach roli internetowej, roli procesu roboczego lub witryny internetowej platformy Azure.
Pobieranie biblioteki klienta
Utwórz plik o nazwie composer.json w katalogu głównym projektu i dodaj do niego następujący kod:
{ "require": { "microsoft/azure-storage-table": "*" } }
Pobierz plik composer.phar do katalogu głównego.
Otwórz wiersz polecenia i uruchom następujące polecenie w katalogu głównym projektu:
php composer.phar install
Możesz też przejść do biblioteki klienta usługi Azure Table Storage dla języka PHP w witrynie GitHub i sklonować kod źródłowy.
Dodawanie wymaganych odwołań
Aby korzystać z usługi Azure Table Storage lub interfejsów API usługi Azure Cosmos DB, należy:
- Dodać odwołanie do pliku automatycznej ładowarki przy użyciu instrukcji require_once.
- Dodać odwołanie do wszystkich używanych klas.
Poniższy przykład pokazuje, w jaki sposób dołączyć plik automatycznej ładowarki i dodać odwołanie do klasy TableRestProxy.
require_once 'vendor/autoload.php';
use MicrosoftAzure\Storage\Table\TableRestProxy;
W przykładach w tym miejscu require_once
instrukcja jest zawsze wyświetlana, ale przywołuje się tylko klasy niezbędne do wykonania przykładu.
Dodawanie parametry połączenia
Możesz nawiązać połączenie z kontem usługi Azure Storage lub kontem usługi Azure Cosmos DB dla tabeli. Pobierz parametry połączenia na podstawie typu używanego konta.
Dodawanie połączenia z usługą Azure Table Storage
Aby zainicjować klienta usługi Azure Table Storage, wymagane są prawidłowe parametry połączenia. Format parametrów połączenia usługi Table Storage jest następujący:
$connectionString = "DefaultEndpointsProtocol=[http|https];AccountName=[yourAccount];AccountKey=[yourKey]"
Dodawanie połączenia emulatora magazynu
Aby uzyskać dostęp do emulatora usługi Azure Storage:
UseDevelopmentStorage = true
Dodawanie połączenia z usługą Azure Cosmos DB
Aby zainicjować klienta usługi Azure Cosmos DB Table, wymagane są prawidłowe parametry połączenia. Format parametrów połączenia usługi Azure Cosmos DB jest następujący:
$connectionString = "DefaultEndpointsProtocol=[https];AccountName=[myaccount];AccountKey=[myaccountkey];TableEndpoint=[https://myendpoint/]";
Aby utworzyć klienta usługi Azure Table Storage lub Azure Cosmos DB, należy użyć klasy TableRestProxy. Możesz:
- Przekazać parametry połączenia bezpośrednio.
- Użyj klasy CloudConfigurationManager (CCM), aby sprawdzić wiele źródeł zewnętrznych dla parametry połączenia:
- Domyślnie obsługiwane jest jedno źródło zewnętrzne — zmienne środowiskowe.
- Możesz dodać nowe źródła, rozszerzając klasę
ConnectionStringSource
.
W przedstawionych tutaj przykładach parametry połączenia są przekazywane bezpośrednio.
require_once 'vendor/autoload.php';
use MicrosoftAzure\Storage\Table\TableRestProxy;
$tableClient = TableRestProxy::createTableService($connectionString);
Tworzenie tabeli
Obiekt TableRestProxy umożliwia utworzenie tabeli przy użyciu metody createTable. Tworząc tabelę, możesz ustawić limit czasu dla usługi Table Storage. Aby uzyskać więcej informacji na temat limitu czasu usługi Table Service, zobacz Ustawianie limitów czasu dla operacji usługi 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
}
Aby uzyskać szczegółowe informacje na temat ograniczeń dotyczących nazw tabel, zobacz Understanding the Table Service Data Model (Omówienie modelu danych usługi Table Storage).
Dodawanie jednostki do tabeli
Aby dodać jednostkę do tabeli, utwórz nowy obiekt Entity i przekaż go do metody TableRestProxy-insertEntity>. Podczas tworzenia jednostki należy określić elementy i PartitionKey
RowKey
. Te jednostki są unikatowymi identyfikatorami jednostki i są wartościami, które mogą być odpytywane szybciej niż inne właściwości jednostki. System używa wartości PartitionKey
, aby automatycznie rozłożyć jednostki tabeli w wielu węzłach usługi Azure Storage. Jednostki z tą samą wartością PartitionKey
są przechowywane w tym samym węźle. Operacje na wielu jednostkach przechowywanych w tym samym węźle działają lepiej niż w przypadku jednostek przechowywanych w różnych węzłach. Wartość RowKey
to unikatowy identyfikator jednostki w partycji.
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();
}
Aby uzyskać szczegółowe informacje na temat właściwości i typów tabel, zobacz Understanding the Table Service Data Model (Omówienie modelu danych usługi Table Storage).
Klasa TableRestProxy oferuje dwie inne metody wstawiania jednostek: insertOrMergeEntity i insertOrReplaceEntity. Aby użyć tych metod, utwórz nowy obiekt Entity i przekaż go jako parametr do jednej z tych metod. Każda metoda wstawia jednostkę, jeśli nie istnieje. Jeśli jednostka już istnieje, insertOrMergeEntity aktualizuje wartości właściwości, jeśli właściwości już istnieją i dodaje nowe właściwości, jeśli nie istnieją, podczas gdy insertOrReplaceEntity całkowicie zastępuje istniejącą jednostkę. W poniższym przykładzie pokazano, jak używać polecenia insertOrMergeEntity
. Jeśli jednostka z elementami PartitionKey
"tasksSeattle" i RowKey
"1" jeszcze nie istnieje, ta jednostka zostanie wstawiona. Jeśli jednak już istnieje (jak pokazano w poprzednim przykładzie), DueDate
właściwość zostanie zaktualizowana i Status
właściwość zostanie dodana. Właściwości Description
i Location
również zostaną zaktualizowane, ale nowe wartości będą takie same. Jeśli te dwie ostatnie właściwości nie zostały dodane, jak pokazano w przykładzie, ale istniały w jednostce docelowej, ich istniejące wartości pozostaną niezmienione.
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 />";
}
Pobieranie pojedynczej jednostki
Metoda TableRestProxy-getEntity> umożliwia pobranie pojedynczej jednostki przez wykonywanie zapytań dotyczących jej PartitionKey
elementów i RowKey
. W tym przykładzie klucz tasksSeattle
partycji i klucz 1
wiersza są przekazywane do metody 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();
Pobieranie wszystkich jednostek w partycji
Zapytania dotyczące jednostek są tworzone przy użyciu filtrów. Aby uzyskać więcej informacji, zobacz Wykonywanie zapytań dotyczących tabel i jednostek. Aby pobrać wszystkie jednostki w partycji, użyj filtru PartitionKey eq partition_name
. Następujący przykład pokazuje, w jaki sposób pobrać wszystkie jednostki w partycji tasksSeattle
, przekazując filtr do metody 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 />";
}
Pobieranie podzestawu jednostek w partycji
Schemat użyty w poprzednim przykładzie umożliwia również pobranie dowolnego podzestawu jednostek z partycji. Używany filtr określa podzestaw pobieranych jednostek. Aby uzyskać więcej informacji, zobacz Wykonywanie zapytań dotyczących tabel i jednostek. W poniższym przykładzie pokazano, jak za pomocą filtru pobrać wszystkie jednostki z określoną Location
datą i DueDate
mniejszą niż określona data.
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 />";
}
Pobieranie podzestawu właściwości jednostki
Zapytanie umożliwia także pobranie podzestawu właściwości jednostki. Ta technika, nazywana projekcją, zmniejsza przepustowość i może poprawić wydajność zapytań, zwłaszcza w przypadku dużych jednostek. Aby określić właściwość do pobrania, przekaż nazwę właściwości do Query->addSelectField
metody . Tę metodę można wywołać wiele razy, aby dodać więcej właściwości. Po wykonaniu TableRestProxy->queryEntities
zwracane jednostki będą miały tylko wybrane właściwości. Jeśli chcesz zwrócić podzestaw jednostek tabeli, użyj filtru, jak pokazano w poprzednich zapytaniach.
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 />";
}
Aktualizowanie jednostki
Istniejącą jednostkę można zaktualizować przy użyciu metod Entity-setProperty> i Entity-addProperty> w jednostce, a następnie wywołać metodę TableRestProxy-updateEntity>. W poniższym przykładzie po pobraniu jednostki jedna właściwość zostanie zmodyfikowana, inna usunięta, a do tego zostanie dodana nowa właściwość. Właściwość można usunąć, ustawiając jej wartość na 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 />";
}
Usuwanie jednostki
Aby usunąć jednostkę, przekaż nazwę tabeli oraz jednostki PartitionKey
i RowKey
do metody 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 />";
}
W przypadku sprawdzania współbieżności można ustawić element Etag dla jednostki do usunięcia przy użyciu metody DeleteEntityOptions-setEtag> i przekazać obiekt DeleteEntityOptions do deleteEntityEntity jako czwarty parametr.
Zbiorcze operacje na tabeli
Metoda TableRestProxy-batch> umożliwia wykonywanie wielu operacji w jednym żądaniu. Wzorzec w tym miejscu obejmuje dodawanie operacji do obiektu BatchRequest, a następnie przekazywanie obiektu BatchRequest do metody TableRestProxy-batch>. Aby dodać operację do obiektu BatchRequest, możesz wywołać dowolną z następujących metod (można to zrobić wiele razy):
Opis | |
---|---|
addInsertEntity |
Dodaje operację insertEntity |
addUpdateEntity |
Dodaje operację updateEntity |
addMergeEntity |
Dodaje operację mergeEntity |
addInsertOrReplaceEntity |
Dodaje operację insertOrReplaceEntity |
addInsertOrMergeEntity |
Dodaje operację insertOrMergeEntity |
addDeleteEntity |
Dodaje operację deleteEntity |
Poniższy przykład przedstawia sposób wykonania operacji insertEntity i deleteEntity w ramach jednego żądania.
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 />";
}
Aby uzyskać więcej informacji na temat tworzenia partii operacji, zobacz Performing Entity Group Transactions (Wykonywanie transakcji w grupach jednostek).
Usuwanie tabeli
Na koniec, aby usunąć tabelę, przekaż nazwę tabeli do metody 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 />";
}
Zawartość pokrewna
- Microsoft Azure Storage Explorer jest bezpłatną aplikacją autonomiczną oferowaną przez firmę Microsoft, która umożliwia wizualną pracę z danymi w usłudze Azure Storage w systemach Windows, macOS i Linux.
- Centrum deweloperów JĘZYKA PHP.