Używanie schematu CloudEvents 1.0 z Event Grid

Oprócz domyślnego schematuzdarzeń program Azure Event Grid natywnie obsługuje zdarzenia w implementacji JSON usługi CloudEvents w wersji 1.0 i powiązaniu protokołu HTTP. CloudEvents to otwarta specyfikacja opisująca dane zdarzeń.

Rozwiązanie CloudEvents upraszcza współdziałanie, zapewniając wspólny schemat zdarzeń do publikowania i obsługi zdarzeń w chmurze. Ten schemat umożliwia stosowanie jednolitych narzędzi, standardowych sposobów routingu i obsługi zdarzeń oraz uniwersalnych sposobów deserializacji zewnętrznego schematu zdarzeń. Wspólny schemat umożliwia łatwiejszą integrację pracy między platformami.

CloudEvents jest budowaną przez kilku współpracowników,w tym firmę Microsoft, za pośrednictwem platformy Cloud Native Computing Foundation. Jest ona obecnie dostępna w wersji 1.0.

W tym artykule opisano sposób używania schematu CloudEvents z Event Grid.

Schemat CloudEvent

Oto przykład zdarzenia Azure Blob Storage w formacie CloudEvents:

{
    "specversion": "1.0",
    "type": "Microsoft.Storage.BlobCreated",  
    "source": "/subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.Storage/storageAccounts/{storage-account}",
    "id": "9aeb0fdf-c01e-0131-0922-9eb54906e209",
    "time": "2019-11-18T15:13:39.4589254Z",
    "subject": "blobServices/default/containers/{storage-container}/blobs/{new-file}",
    "dataschema": "#",
    "data": {
        "api": "PutBlockList",
        "clientRequestId": "4c5dd7fb-2c48-4a27-bb30-5361b5de920a",
        "requestId": "9aeb0fdf-c01e-0131-0922-9eb549000000",
        "eTag": "0x8D76C39E4407333",
        "contentType": "image/png",
        "contentLength": 30699,
        "blobType": "BlockBlob",
        "url": "https://gridtesting.blob.core.windows.net/testcontainer/{new-file}",
        "sequencer": "000000000000000000000000000099240000000000c41c18",
        "storageDiagnostics": {
            "batchId": "681fe319-3006-00a8-0022-9e7cde000000"
        }
    }
}

Aby uzyskać szczegółowy opis dostępnych pól, ich typów i definicji, zobacz CloudEvents v1.0.

Wartości nagłówków zdarzeń dostarczanych w schemacie CloudEvents i Event Grid są takie same z wyjątkiem content-type . W przypadku schematu CloudEvents ta wartość nagłówka to "content-type":"application/cloudevents+json; charset=utf-8" . W przypadku Event Grid wartość nagłówka to "content-type":"application/json; charset=utf-8" .

Konfigurowanie Event Grid dla rozwiązania CloudEvents

Możesz użyć Event Grid zarówno dla danych wejściowych, jak i wyjściowych zdarzeń w schemacie CloudEvents. W poniższej tabeli opisano możliwe przekształcenia:

Event Grid zasobów Schemat wejściowy Schemat dostarczania
Tematy systemowe Schemat usługi Event Grid Event Grid schematu lub schematu CloudEvents
Tematy/domeny niestandardowe Schemat usługi Event Grid Event Grid schematu lub schematu CloudEvents
Tematy/domeny niestandardowe Schemat CloudEvents Schemat CloudEvents
Tematy/domeny niestandardowe Schemat niestandardowy Schemat niestandardowy, Event Grid lub schemat CloudEvents
Tematy partnerów Schemat CloudEvents Schemat CloudEvents

W przypadku wszystkich schematów zdarzeń Event Grid weryfikacji podczas publikowania w Event Grid tematu oraz podczas tworzenia subskrypcji zdarzeń.

Aby uzyskać więcej informacji, zobacz Event Grid zabezpieczeń i uwierzytelniania.

Schemat wejściowy

Schemat wejściowy dla tematu niestandardowego ustawia się podczas tworzenia tematu niestandardowego.

W przypadku interfejsu wiersza polecenia platformy Azure użyj:

az eventgrid topic create \
  --name <topic_name> \
  -l westcentralus \
  -g gridResourceGroup \
  --input-schema cloudeventschemav1_0

W przypadku programu PowerShell użyj polecenia:

New-AzEventGridTopic `
  -ResourceGroupName gridResourceGroup `
  -Location westcentralus `
  -Name <topic_name> `
  -InputSchema CloudEventSchemaV1_0

Schemat wyjściowy

Schemat wyjściowy jest ustawiany podczas tworzenia subskrypcji zdarzeń.

W przypadku interfejsu wiersza polecenia platformy Azure użyj:

topicID=$(az eventgrid topic show --name <topic-name> -g gridResourceGroup --query id --output tsv)

az eventgrid event-subscription create \
  --name <event_subscription_name> \
  --source-resource-id $topicID \
  --endpoint <endpoint_URL> \
  --event-delivery-schema cloudeventschemav1_0

W przypadku programu PowerShell użyj polecenia:

$topicid = (Get-AzEventGridTopic -ResourceGroupName gridResourceGroup -Name <topic-name>).Id

New-AzEventGridSubscription `
  -ResourceId $topicid `
  -EventSubscriptionName <event_subscription_name> `
  -Endpoint <endpoint_URL> `
  -DeliverySchema CloudEventSchemaV1_0

Obecnie nie można użyć wyzwalacza Event Grid aplikacji Azure Functions, gdy zdarzenie zostanie dostarczone w schemacie CloudEvents. Użyj wyzwalacza HTTP. Aby uzyskać przykłady implementacji wyzwalacza HTTP, który odbiera zdarzenia w schemacie CloudEvents, zobacz Using CloudEvents with Azure Functions(Używanie zdarzeń CloudEvents z Azure Functions ).

Walidacja punktu końcowego przy użyciu rozwiązania CloudEvents w wersji 1.0

Jeśli znasz już te Event Grid, możesz mieć świadomość, że proces weryfikacji punktu końcowego ma na celu zapobieganie nadużyciom. Rozwiązanie CloudEvents w wersji 1.0 implementuje własną semantykę ochrony przed nadużyciami przy użyciu metody HTTP OPTIONS. Aby dowiedzieć się więcej na ten temat, zobacz HTTP 1.1 Web Hooks for event delivery - Version 1.0 (Web Hooks for event delivery — wersja 1.0). W przypadku użycia schematu CloudEvents dla danych wyjściowych usługa Event Grid używa ochrony przed nadużyciami w usłudze CloudEvents w wersji 1.0 w miejsce mechanizmu Event Grid zdarzeń weryfikacji.

Używanie z Azure Functions

Powiązanie Azure Functions Event Grid nie obsługuje natywnie usługi CloudEvents, dlatego funkcje wyzwalane przez protokół HTTP są używane do odczytywania komunikatów CloudEvents. Jeśli do odczytywania aplikacji CloudEvents używasz wyzwalacza HTTP, musisz napisać kod dla tego, co wyzwalacz Event Grid automatycznie:

  • Wysyła odpowiedź weryfikacji na żądanie weryfikacji subskrypcji
  • Wywołuje funkcję raz na element tablicy zdarzeń zawartej w treści żądania

Aby uzyskać informacje o adresie URL do wywołania funkcji lokalnie lub na platformie Azure, zobacz dokumentację referencyjną powiązania wyzwalacza HTTP.

Poniższy przykładowy kod języka C# dla wyzwalacza HTTP symuluje Event Grid działania wyzwalacza. Użyj tego przykładu dla zdarzeń dostarczanych w schemacie CloudEvents.

[FunctionName("HttpTrigger")]
public static async Task<HttpResponseMessage> Run([HttpTrigger(AuthorizationLevel.Anonymous, "post", "options", Route = null)]HttpRequestMessage req, ILogger log)
{
    log.LogInformation("C# HTTP trigger function processed a request.");
    if (req.Method == HttpMethod.Options)
    {
        // If the request is for subscription validation, send back the validation code
        
        var response = req.CreateResponse(HttpStatusCode.OK);
        response.Headers.Add("Webhook-Allowed-Origin", "eventgrid.azure.net");

        return response;
    }

    var requestmessage = await req.Content.ReadAsStringAsync();
    var message = JToken.Parse(requestmessage);

    // The request isn't for subscription validation, so it's for an event.
    // CloudEvents schema delivers one event at a time.
    log.LogInformation($"Source: {message["source"]}");
    log.LogInformation($"Time: {message["eventTime"]}");
    log.LogInformation($"Event data: {message["data"].ToString()}");

    return req.CreateResponse(HttpStatusCode.OK);
}

Poniższy przykładowy kod JavaScript dla wyzwalacza HTTP symuluje Event Grid działania wyzwalacza. Użyj tego przykładu dla zdarzeń dostarczanych w schemacie CloudEvents.

module.exports = function (context, req) {
    context.log('JavaScript HTTP trigger function processed a request.');
    
    if (req.method == "OPTIONS") {
        // If the request is for subscription validation, send back the validation code
        
        context.log('Validate request received');
        context.res = {
            status: 200,
            headers: {
                'Webhook-Allowed-Origin': 'eventgrid.azure.net',
            },
         };
    }
    else
    {
        var message = req.body;
        
        // The request isn't for subscription validation, so it's for an event.
        // CloudEvents schema delivers one event at a time.
        var event = JSON.parse(message);
        context.log('Source: ' + event.source);
        context.log('Time: ' + event.eventTime);
        context.log('Data: ' + JSON.stringify(event.data));
    }
 
    context.done();
};

Następne kroki