Szybki Start: jak używać kolejek Service Bus przy użyciu języka PHPQuickstart: How to use Service Bus queues with PHP

W ramach tego samouczka nauczysz się tworzyć aplikacje PHP do wysyłania komunikatów do i odbierania komunikatów z kolejki Service Bus.In this tutorial, you learn how to create PHP applications to send messages to and receive messages from a Service Bus queue.

Wymagania wstępnePrerequisites

  1. Subskrypcja platformy Azure.An Azure subscription. Do wykonania kroków tego samouczka potrzebne jest konto platformy Azure.To complete this tutorial, you need an Azure account. Możesz aktywować korzyści dla subskrybentów MSDN lub utworzyć bezpłatne konto.You can activate your MSDN subscriber benefits or sign up for a free account.
  2. Jeśli nie masz kolejki do współpracy z programem, postępuj zgodnie z instrukcjami w temacie Use Azure Portal, aby utworzyć kolejkę Service Bus w celu utworzenia kolejki.If you don't have a queue to work with, follow steps in the Use Azure portal to create a Service Bus queue article to create a queue.
    1. Zapoznaj się z krótkim omówieniem kolejek Service Bus.Read the quick overview of Service Bus queues.

    2. Utwórz przestrzeń nazw Service Bus.Create a Service Bus namespace.

    3. Pobierz Parametry połączenia.Get the connection string.

      Uwaga

      W tym samouczku utworzysz kolejkę w przestrzeni nazw Service Bus przy użyciu języka PHP.You will create a queue in the Service Bus namespace by using PHP in this tutorial.

  3. Zestaw Azure SDK dla środowiska PHPAzure SDK for PHP

Tworzenie aplikacji języka PHPCreate a PHP application

Jedynym wymaganiem do tworzenia aplikacji języka PHP, która uzyskuje dostęp do Blob service platformy Azure, jest odwołanie do klas w zestawie Azure SDK dla języka PHP z poziomu kodu.The only requirement for creating a PHP application that accesses the Azure Blob service is the referencing of classes in the Azure SDK for PHP from within your code. Możesz użyć dowolnych narzędzi programistycznych do utworzenia aplikacji lub Notatnika.You can use any development tools to create your application, or Notepad.

Uwaga

W instalacji PHP musi być zainstalowane i włączone rozszerzenie OpenSSL .Your PHP installation must also have the OpenSSL extension installed and enabled.

W tym przewodniku zostaną użyte funkcje usługi, które można wywoływać z poziomu aplikacji w języku PHP lokalnie lub w kodzie uruchomionym w ramach roli sieci Web, roli procesu roboczego lub witryny internetowej platformy Azure.In this guide, you will use service features, which can be called from within a PHP application locally, or in code running within an Azure web role, worker role, or website.

Pobierz biblioteki klienckie platformy AzureGet the Azure client libraries

Instalowanie przez układaczInstall via Composer

  1. Utwórz plik o nazwie composer.js w folderze głównym projektu i Dodaj do niego następujący kod:Create a file named composer.json in the root of your project and add the following code to it:

    {
      "require": {
        "microsoft/windowsazure": "*"
      }
    }
    
  2. Pobierz układacz. PHAR w katalogu głównym projektu.Download composer.phar in your project root.

  3. Otwórz wiersz polecenia i wykonaj następujące polecenie w katalogu głównym projektuOpen a command prompt and execute the following command in your project root

    php composer.phar install
    

Skonfiguruj aplikację do używania Service BusConfigure your application to use Service Bus

Aby skorzystać z interfejsów API Service Bus Queue, wykonaj następujące czynności:To use the Service Bus queue APIs, do the following:

  1. Odwołuje się do pliku automatycznej ładowarki przy użyciu instrukcji require_once .Reference the autoloader file using the require_once statement.
  2. Odwołuje się do dowolnych klas, które mogą być używane.Reference any classes you might use.

Poniższy przykład pokazuje, jak dołączyć plik automatycznej ładowarki i odwołać się do ServicesBuilder klasy.The following example shows how to include the autoloader file and reference the ServicesBuilder class.

Uwaga

W tym przykładzie (i innych przykładach w tym artykule) założono, że zainstalowano biblioteki klienckie PHP dla systemu Azure przez układacz.This example (and other examples in this article) assumes you have installed the PHP Client Libraries for Azure via Composer. Jeśli biblioteki zostały zainstalowane ręcznie lub jako pakiet php, należy odwołać się do pliku automatycznej ładowarki windowsazure. php .If you installed the libraries manually or as a PEAR package, you must reference the WindowsAzure.php autoloader file.

require_once 'vendor/autoload.php';
use WindowsAzure\Common\ServicesBuilder;

W poniższych przykładach require_once instrukcja będzie zawsze wyświetlana, ale przywoływane są tylko klasy niezbędne do wykonania tego przykładu.In the examples below, the require_once statement will always be shown, but only the classes necessary for the example to execute are referenced.

Skonfiguruj połączenie Service BusSet up a Service Bus connection

Aby utworzyć wystąpienie klienta Service Bus, należy najpierw dysponować prawidłowymi parametrami połączenia w tym formacie:To instantiate a Service Bus client, you must first have a valid connection string in this format:

Endpoint=[yourEndpoint];SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=[Primary Key]

Gdzie Endpoint jest zazwyczaj format [yourNamespace].servicebus.windows.net .Where Endpoint is typically of the format [yourNamespace].servicebus.windows.net.

Aby utworzyć dowolnego klienta usługi platformy Azure, należy użyć ServicesBuilder klasy.To create any Azure service client, you must use the ServicesBuilder class. Oto co możesz zrobić:You can:

  • Przekaż parametry połączenia bezpośrednio do niego.Pass the connection string directly to it.
  • Użyj CloudConfigurationManager (CCM) , aby sprawdzić wiele zewnętrznych źródeł parametrów połączenia:Use the CloudConfigurationManager (CCM) to check multiple external sources for the connection string:
    • Domyślnie jest on dostarczany z obsługą jednego zewnętrznego źródła — zmienne środowiskoweBy default it comes with support for one external source - environmental variables
    • Możesz dodać nowe źródła, rozszerzając ConnectionStringSource klasęYou can add new sources by extending the ConnectionStringSource class

W przedstawionych tutaj przykładach parametry połączenia są przekazywane bezpośrednio.For the examples outlined here, the connection string is passed directly.

require_once 'vendor/autoload.php';

use WindowsAzure\Common\ServicesBuilder;

$connectionString = "Endpoint=[yourEndpoint];SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=[Primary Key]";

$serviceBusRestProxy = ServicesBuilder::getInstance()->createServiceBusService($connectionString);

Tworzenie kolejkiCreate a queue

Operacje zarządzania dla kolejek Service Busych można wykonywać za pośrednictwem ServiceBusRestProxy klasy.You can perform management operations for Service Bus queues via the ServiceBusRestProxy class. ServiceBusRestProxyObiekt jest konstruowany za pośrednictwem ServicesBuilder::createServiceBusService metody fabryki z odpowiednimi parametrami połączenia, które hermetyzują uprawnienia tokenu do zarządzania nim.A ServiceBusRestProxy object is constructed via the ServicesBuilder::createServiceBusService factory method with an appropriate connection string that encapsulates the token permissions to manage it.

Poniższy przykład pokazuje, jak utworzyć wystąpienie obiektu ServiceBusRestProxy i wywołać, ServiceBusRestProxy->createQueue Aby utworzyć kolejkę o nazwie myqueue w MySBNamespace przestrzeni nazw usługi:The following example shows how to instantiate a ServiceBusRestProxy and call ServiceBusRestProxy->createQueue to create a queue named myqueue within a MySBNamespace service namespace:

require_once 'vendor/autoload.php';

use WindowsAzure\Common\ServicesBuilder;
use WindowsAzure\Common\ServiceException;
use WindowsAzure\ServiceBus\Models\QueueInfo;

// Create Service Bus REST proxy.
$serviceBusRestProxy = ServicesBuilder::getInstance()->createServiceBusService($connectionString);

try    {
    $queueInfo = new QueueInfo("myqueue");

    // Create queue.
    $serviceBusRestProxy->createQueue($queueInfo);
}
catch(ServiceException $e){
    // Handle exception based on error codes and messages.
    // Error codes and messages are here: 
    // https://docs.microsoft.com/rest/api/storageservices/Common-REST-API-Error-Codes
    $code = $e->getCode();
    $error_message = $e->getMessage();
    echo $code.": ".$error_message."<br />";
}

Uwaga

Możesz użyć listQueues metody dla obiektów, ServiceBusRestProxy Aby sprawdzić, czy kolejka o określonej nazwie już istnieje w przestrzeni nazw.You can use the listQueues method on ServiceBusRestProxy objects to check if a queue with a specified name already exists within a namespace.

Wysyłanie komunikatów do kolejkiSend messages to a queue

Aby wysłać komunikat do kolejki Service Bus, aplikacja wywołuje ServiceBusRestProxy->sendQueueMessage metodę.To send a message to a Service Bus queue, your application calls the ServiceBusRestProxy->sendQueueMessage method. Poniższy kod pokazuje, jak wysłać komunikat do myqueue kolejki utworzonej wcześniej w MySBNamespace przestrzeni nazw usługi.The following code shows how to send a message to the myqueue queue previously created within the MySBNamespace service namespace.

require_once 'vendor/autoload.php';

use WindowsAzure\Common\ServicesBuilder;
use WindowsAzure\Common\ServiceException;
use WindowsAzure\ServiceBus\Models\BrokeredMessage;

// Create Service Bus REST proxy.
$serviceBusRestProxy = ServicesBuilder::getInstance()->createServiceBusService($connectionString);

try    {
    // Create message.
    $message = new BrokeredMessage();
    $message->setBody("my message");

    // Send message.
    $serviceBusRestProxy->sendQueueMessage("myqueue", $message);
}
catch(ServiceException $e){
    // Handle exception based on error codes and messages.
    // Error codes and messages are here: 
    // https://docs.microsoft.com/rest/api/storageservices/Common-REST-API-Error-Codes
    $code = $e->getCode();
    $error_message = $e->getMessage();
    echo $code.": ".$error_message."<br />";
}

Komunikaty wysyłane do (i odbieranych z) Service Bus kolejki są wystąpieniami klasy BrokeredMessage .Messages sent to (and received from) Service Bus queues are instances of the BrokeredMessage class. Obiekty BrokeredMessage mają zestaw standardowych metod i właściwości, które są używane do przechowywania niestandardowych właściwości specyficznych dla aplikacji oraz treści dowolnych danych aplikacji.BrokeredMessage objects have a set of standard methods and properties that are used to hold custom application-specific properties, and a body of arbitrary application data.

Kolejki usługi Service Bus obsługują maksymalny rozmiar komunikatu 256 KB w warstwie Standardowa i 1 MB w warstwie Premium.Service Bus queues support a maximum message size of 256 KB in the Standard tier and 1 MB in the Premium tier. Nagłówek, który zawiera standardowe i niestandardowe właściwości aplikacji, może mieć maksymalny rozmiar 64 KB.The header, which includes the standard and custom application properties, can have a maximum size of 64 KB. Nie ma żadnego limitu liczby komunikatów w kolejce, ale jest ograniczenie całkowitego rozmiaru komunikatów przechowywanych przez kolejkę.There is no limit on the number of messages held in a queue but there is a cap on the total size of the messages held by a queue. Górny limit rozmiaru kolejki wynosi 5 GB.This upper limit on queue size is 5 GB.

Odbieranie komunikatów z kolejkiReceive messages from a queue

Najlepszym sposobem odbierania komunikatów z kolejki jest użycie ServiceBusRestProxy->receiveQueueMessage metody.The best way to receive messages from a queue is to use a ServiceBusRestProxy->receiveQueueMessage method. Komunikaty mogą być odbierane w dwóch różnych trybach: ReceiveAndDelete i PeekLock.Messages can be received in two different modes: ReceiveAndDelete and PeekLock. Ustawienie domyślne to PeekLock.PeekLock is the default.

W przypadku korzystania z trybu ReceiveAndDelete odbieranie jest operacją pojedynczego zrzutu. oznacza to, że gdy Service Bus odbiera żądanie odczytu komunikatu w kolejce, oznacza komunikat jako używany i zwraca go do aplikacji.When using ReceiveAndDelete mode, receive is a single-shot operation; that is, when Service Bus receives a read request for a message in a queue, it marks the message as being consumed and returns it to the application. Tryb ReceiveAndDelete jest najprostszym modelem i działa najlepiej w scenariuszach, w których aplikacja może tolerować nieprzetworzenie komunikatu w razie awarii.ReceiveAndDelete mode is the simplest model and works best for scenarios in which an application can tolerate not processing a message in the event of a failure. Aby to zrozumieć, rozważmy scenariusz, w którym konsument wystawia żądanie odbioru, a następnie ulega awarii przed jego przetworzeniem.To understand this, consider a scenario in which the consumer issues the receive request and then crashes before processing it. Ponieważ Service Bus oznaczył komunikat jako używany, a następnie aplikacja zostanie ponownie uruchomiona i rozpocznie korzystanie z komunikatów, zostanie pominięta wiadomość, która była używana przed awarią.Because Service Bus will have marked the message as being consumed, then when the application restarts and begins consuming messages again, it will have missed the message that was consumed prior to the crash.

W domyślnym trybie PeekLock otrzymywanie komunikatu staje się operacją dwuetapową, co umożliwia obsługę aplikacji, które nie mogą tolerować brakujących komunikatów.In the default PeekLock mode, receiving a message becomes a two stage operation, which makes it possible to support applications that cannot tolerate missing messages. Gdy Service Bus odbiera żądanie, znajdzie następny komunikat do użycia, zablokuje go, aby uniemożliwić innym konsumentom odbieranie go, a następnie zwraca go do aplikacji.When Service Bus receives a request, it finds the next message to be consumed, locks it to prevent other consumers from receiving it, and then returns it to the application. Gdy aplikacja zakończy przetwarzanie komunikatu (lub zapisuje ją w sposób niezawodny w przyszłości), kończy drugi etap procesu odbierania, przekazując odebrany komunikat do ServiceBusRestProxy->deleteMessage .After the application finishes processing the message (or stores it reliably for future processing), it completes the second stage of the receive process by passing the received message to ServiceBusRestProxy->deleteMessage. Gdy Service Bus widzi deleteMessage wywołanie, oznaczy komunikat jako używany i usuń go z kolejki.When Service Bus sees the deleteMessage call, it will mark the message as being consumed and remove it from the queue.

Poniższy przykład pokazuje, jak odbierać i przetwarzać komunikat przy użyciu trybu PeekLock (tryb domyślny).The following example shows how to receive and process a message using PeekLock mode (the default mode).

require_once 'vendor/autoload.php';

use WindowsAzure\Common\ServicesBuilder;
use WindowsAzure\Common\ServiceException;
use WindowsAzure\ServiceBus\Models\ReceiveMessageOptions;

// Create Service Bus REST proxy.
$serviceBusRestProxy = ServicesBuilder::getInstance()->createServiceBusService($connectionString);

try    {
    // Set the receive mode to PeekLock (default is ReceiveAndDelete).
    $options = new ReceiveMessageOptions();
    $options->setPeekLock();

    // Receive message.
    $message = $serviceBusRestProxy->receiveQueueMessage("myqueue", $options);
    echo "Body: ".$message->getBody()."<br />";
    echo "MessageID: ".$message->getMessageId()."<br />";

    /*---------------------------
        Process message here.
    ----------------------------*/

    // Delete message. Not necessary if peek lock is not set.
    echo "Message deleted.<br />";
    $serviceBusRestProxy->deleteMessage($message);
}
catch(ServiceException $e){
    // Handle exception based on error codes and messages.
    // Error codes and messages are here:
    // https://docs.microsoft.com/rest/api/storageservices/Common-REST-API-Error-Codes
    $code = $e->getCode();
    $error_message = $e->getMessage();
    echo $code.": ".$error_message."<br />";
}

Sposób obsługi awarii aplikacji i komunikatów niemożliwych do odczytaniaHow to handle application crashes and unreadable messages

Usługa Service Bus zapewnia funkcję ułatwiającą bezpieczne odzyskiwanie w razie błędów w aplikacji lub trudności z przetwarzaniem komunikatu.Service Bus provides functionality to help you gracefully recover from errors in your application or difficulties processing a message. Jeśli aplikacja odbiornika nie może przetworzyć komunikatu z jakiegoś powodu, może wywołać unlockMessage metodę dla odebranego komunikatu (zamiast deleteMessage metody).If a receiver application is unable to process the message for some reason, then it can call the unlockMessage method on the received message (instead of the deleteMessage method). Spowoduje to Service Bus odblokowanie komunikatu w kolejce i udostępnienie go do odebrania przez tę samą aplikację wykorzystującą lub przez inną aplikację, która korzysta z aplikacji.This will cause Service Bus to unlock the message within the queue and make it available to be received again, either by the same consuming application or by another consuming application.

Istnieje również limit czasu skojarzony z komunikatem zablokowanym w kolejce i jeśli aplikacja nie może przetworzyć komunikatu przed upływem limitu czasu blokady (na przykład jeśli aplikacja ulega awarii), Service Bus automatycznie odblokuje komunikat i udostępni go do ponownego odebrania.There is also a timeout associated with a message locked within the queue, and if the application fails to process the message before the lock timeout expires (for example, if the application crashes), then Service Bus will unlock the message automatically and make it available to be received again.

W przypadku awarii aplikacji po przetworzeniu komunikatu, ale przed deleteMessage wystawieniem żądania, komunikat zostanie ponownie dostarczony do aplikacji po jej ponownym uruchomieniu.In the event that the application crashes after processing the message but before the deleteMessage request is issued, then the message will be redelivered to the application when it restarts. Jest to często nazywane co najmniej jednym przetwarzaniem; oznacza to, że każdy komunikat jest przetwarzany co najmniej raz, ale w pewnych sytuacjach może zostać ponownie dostarczony ten sam komunikat.This is often called At Least Once processing; that is, each message is processed at least once but in certain situations the same message may be redelivered. Jeśli w scenariuszu nie można tolerować zduplikowanego przetwarzania, zaleca się dodanie dodatkowej logiki do aplikacji w celu obsługi dostarczania duplikatów komunikatów.If the scenario cannot tolerate duplicate processing, then adding additional logic to applications to handle duplicate message delivery is recommended. Jest to często osiągane przy użyciu getMessageId metody komunikatu, która pozostaje stała między kolejnymi próbami dostarczenia.This is often achieved using the getMessageId method of the message, which remains constant across delivery attempts.

Uwaga

Za pomocą eksploratora Service Busmożna zarządzać zasobami Service Bus.You can manage Service Bus resources with Service Bus Explorer. Eksplorator Service Bus umożliwia użytkownikom łączenie się z przestrzenią nazw Service Bus i administrowanie jednostkami obsługi komunikatów w prosty sposób.The Service Bus Explorer allows users to connect to a Service Bus namespace and administer messaging entities in an easy manner. Narzędzie zapewnia zaawansowane funkcje, takie jak funkcja importowania/eksportowania lub możliwość testowania tematów, kolejek, subskrypcji, usług przekazywania, centrów powiadomień i centrów zdarzeń.The tool provides advanced features like import/export functionality or the ability to test topic, queues, subscriptions, relay services, notification hubs and events hubs.

Następne krokiNext steps

Teraz, gdy znasz już podstawy Service Busych kolejek, zobacz sekcję kolejki, tematy i subskrypcje , aby uzyskać więcej informacji.Now that you've learned the basics of Service Bus queues, see Queues, topics, and subscriptions for more information.

Aby uzyskać więcej informacji, odwiedź stronę Centrum deweloperów języka PHP.For more information, also visit the PHP Developer Center.