|
| 1 | +--- |
| 2 | +title: Onboard as a Event Grid Partner |
| 3 | +description: Onboard as an Azure Event Grid Partner Topic Type. Understand the resource model and publishing flow for Partner Topics. |
| 4 | +services: event-grid |
| 5 | +author: banisadr |
| 6 | + |
| 7 | +ms.service: event-grid |
| 8 | +ms.date: 05/18/2020 |
| 9 | +ms.author: babanisa |
| 10 | +--- |
| 11 | + |
| 12 | +# Become and Event Grid partner |
| 13 | + |
| 14 | +This article describes how to privately use the Event Grid partner resources as well as how to become a publicly available Partner Topic Type. |
| 15 | + |
| 16 | +You do not need special permission to begin using the Event Grid resource types associated with publishing events as an Event Grid partner. In fact, you can use them today both to publish events privately to your own Azure Subscriptions, as well as to test out the resource model if you are considering becoming a partner. |
| 17 | + |
| 18 | +## Becoming an Event Grid partner |
| 19 | + |
| 20 | +If you are interested in becoming a public Event Grid partner, please begin by filling out [this form ](https://aka.ms/gridpartnerform), and then contacting the Event Grid team at [[email protected]]([email protected]). |
| 21 | + |
| 22 | +## How partner topics work |
| 23 | +Partner Topics take the existing architecture that Event Grid already uses in to publish events from Azure resoruces such as Storage and IoT Hub, and makes those tools publicly available for anyone to use. Using these tools is by default private to your Azure Subscription only. In order to make your events publicly available, please fill out the above form and [contact the Event Grid team ]([email protected]). |
| 24 | + |
| 25 | +Partner topics allow you to publish events to Azure Event Grid for multitenant consumption. |
| 26 | + |
| 27 | +### Onboarding and event publishing overview |
| 28 | + |
| 29 | +#### Partner flow |
| 30 | + |
| 31 | +1. Create an Azure tenant if you don't already have one. |
| 32 | +1. Using CLI create a new Event Grid `partnerRegistration`. This includes information such as display name, description, setup URI etc. |
| 33 | + |
| 34 | +1. Create one or more `partnerNamespaces` in each region you want to publish events. As part of this, Event Grid service will provision a publishing endpoint (e.g. https://contoso.westus-1.eventgrid.azure.net/api/events) and access keys. |
| 35 | + |
| 36 | +1. Provide a way for customers to register in your system that they would like a partner topic. |
| 37 | +1. Contact the Event Grid team to let us know you would like your Partner Topic Type to become public. This will kickoff a review process. |
| 38 | + |
| 39 | +#### Customer flow |
| 40 | + |
| 41 | +1. Your customer will visit the Azure Portal to note the Azure Subscription ID and Resource Group they would like the Partner Topic created in. |
| 42 | +1. The customer will request a Partner Topic via your system. In response you will create an Event Tunnel your Partner Namespace. |
| 43 | +1. Event Grid will create a **Pending** Partner Topic in the customer's Azure Subscription and Resoruce Group. |
| 44 | + |
| 45 | +1. The customer activates the Partner Topic via the Azure Portal. Events may now flow from your service to the customer's Azure Subscription. |
| 46 | + |
| 47 | + |
| 48 | +## Resource Model |
| 49 | + |
| 50 | +Below is the resource model for Partner Topics. |
| 51 | + |
| 52 | +### Partner Registrations |
| 53 | +* Resource: `partnerRegistrations` |
| 54 | +* Used by: Partners |
| 55 | +* Description: Captures the global metadata of the SaaS partner (e.g. name, display name, description, setup URI). |
| 56 | + |
| 57 | + Creating/updating a partner registration is a self-serve operation for the partners. This enables partners to build and test the complete end to end flow. |
| 58 | + |
| 59 | + Only Microsoft approved partnerRegistrations are discoverable by customers. |
| 60 | +* Scope: Created in partner's Azure Subscription. Metadata visible to customers once public. |
| 61 | + |
| 62 | +### Event Types |
| 63 | +* Resource: `partnerRegistrations/eventTypes` |
| 64 | +* Used by: Partners |
| 65 | +* Description: Captures metadata about event types supported by a partner registration. |
| 66 | +* Scope: Discoverable by customers once made public. Lives in a partner’s subscription as a child resource of Partner Registration. |
| 67 | + |
| 68 | + |
| 69 | +### Partner Namespaces |
| 70 | +* Resource: partnerNamespaces |
| 71 | +* Used by: Partners |
| 72 | +* Description: Provides a regional resource for publishing customer events to. Each Partner Namespace has a publishing endpoint and auth keys. The namespace is also how the partner requests a Partner Topic for a given customer as well as lists active customers. |
| 73 | +* Scope: Lives in partner’s subscription. |
| 74 | + |
| 75 | +### Event Tunnels |
| 76 | +* Resource: `partnerNamespaces/eventTunnels` |
| 77 | +* Used by: Partners |
| 78 | +* Description: The Event Tunnels are a mirror of the customer's Partner Topic. By creating an Event Tunnel and specifying the customer's Azure Subscription and resource Group in the metadata, you are signaling to Event Grid to create a Partner Topic on behalf of the customer. Event Grid will issue an ARM call to create a corresponding partnerTopic in the customer’s subscription. The partner topic will be created in a "pending" state. There’s a 1-1 link between each eventTunnel and a partnerTopic. |
| 79 | +* Scope: Lives in partner’s subscription. |
| 80 | + |
| 81 | +### Partner Topics |
| 82 | +* Resource: `partnerTopics` |
| 83 | +* Used by: Customers |
| 84 | +* Description: Partner Topics are similar to Custom Topic and System topic in Event Grid. Each Partner Topic is associated with a specific “source” (e.g. “Contoso:myaccount”) and a specific partner topic type (e.g. “Contoso”). Customers create Event Subscriptions on the Partner Topic to route events to various event handlers. |
| 85 | + |
| 86 | + Note that customers cannot directly create this resource. The only way to create this is be through a partner operation creating an Event Tunnel. |
| 87 | +* Scope: Lives in customer’s subscription. |
| 88 | + |
| 89 | +### Partner Topic Types |
| 90 | +* Resource: `partnerTopicTypes` |
| 91 | +* Used by: Customers |
| 92 | +* Description: This is a tenant wide resource type to enable customers to discover the list of approved partner topic types . The URL will look as follows: https://management.azure.com/providers/Microsoft.EventGrid/partnerTopicTypes) |
| 93 | +* Scope: Global |
| 94 | + |
| 95 | +## Publishing Events to Event Grid |
| 96 | +When a you create a partnerNamespace in an Azure region, you will get a regional endpoint and corresponding auth keys. Publish batches of events to this endpoint for all customer Event Tunnels in that namespace. Based on the “source” field in the event, Azure Event Grid will map each event with the corresponding partner topic(s). |
| 97 | + |
| 98 | +### Event Schema: CloudEvents v1.0 |
| 99 | +Publish events to Azure Event Grid using the CloudEvents 1.0 schema. Event Grid supports both structured mode and batched mode. CloudEvents 1.0 is the only supported event schema for Partner Namespaces. |
| 100 | + |
| 101 | +### Example Flow |
| 102 | + |
| 103 | +1. The publishing service does a HTTP POST to https://contoso.westus2-1.eventgrid.azure.net/api/events?api-version=2018-01-01. |
| 104 | +2. In the request, include a header value named aeg-sas-key that contains a key for authentication. This is the key provisioned during the creation of the partnerNamespace. For example, a valid header value is aeg-sas-key: VXbGWce53249Mt8wuotr0GPmyJ/nDT4hgdEj9DpBeRr38arnnm5OFg==. |
| 105 | +3. Set the Content-Type header to “application/cloudevents-batch+json; charset=UTF-8”. |
| 106 | +4. Perform a HTTP POST to the above publish URL with a batch of events corresponding to that region. For example: |
| 107 | + |
| 108 | +``` json |
| 109 | +[ |
| 110 | +{ |
| 111 | + "specversion" : "1.0-rc1", |
| 112 | + "type" : "com.contoso.ticketcreated", |
| 113 | + "source" : " com.contoso.account1", |
| 114 | + "subject" : "tickets/123", |
| 115 | + "id" : "A234-1234-1234", |
| 116 | + "time" : "2019-04-05T17:31:00Z", |
| 117 | + "comexampleextension1" : "value", |
| 118 | + "comexampleothervalue" : 5, |
| 119 | + "datacontenttype" : "application/json", |
| 120 | + "data" : { |
| 121 | + object-unique-to-each-publisher |
| 122 | + } |
| 123 | +}, |
| 124 | +{ |
| 125 | + "specversion" : "1.0-rc1", |
| 126 | + "type" : "com.contoso.ticketclosed", |
| 127 | + "source" : "https://contoso.com/account2", |
| 128 | + "subject" : "tickets/456", |
| 129 | + "id" : "A234-1234-1234", |
| 130 | + "time" : "2019-04-05T17:31:00Z", |
| 131 | + "comexampleextension1" : "value", |
| 132 | + "comexampleothervalue" : 5, |
| 133 | + "datacontenttype" : "application/json", |
| 134 | + "data" : { |
| 135 | + object-unique-to-each-publisher |
| 136 | + } |
| 137 | +} |
| 138 | +] |
| 139 | +``` |
| 140 | + |
| 141 | +After posting to the partnerNamespace endpoint, you will receive a response. The response is a standard HTTP response code. Some common responses are: |
| 142 | +|Result | Response | |
| 143 | +|-------|----------| |
| 144 | +| Success | 200 OK | |
| 145 | +| Event data has incorrect format | 400 Bad Request | |
| 146 | +| Invalid access key | 401 Unauthorized | |
| 147 | +| Incorrect endpoint | 404 Not Found | |
| 148 | +| Array or event exceeds size limits | 413 Payload Too Large | |
| 149 | + |
| 150 | +## Reference |
| 151 | + |
| 152 | + * [Swagger](https://github.com/ahamad-MS/azure-rest-api-specs/blob/master/specification/eventgrid/resource-manager/Microsoft.EventGrid/preview/2020-04-01-preview/EventGrid.json) |
| 153 | + * [ARM Template](https://docs.microsoft.com/en-gb/azure/templates/microsoft.eventgrid/allversions) |
| 154 | + * [ARM Temaplate schema](https://github.com/Azure/azure-resource-manager-schemas/blob/master/schemas/2020-04-01-preview/Microsoft.EventGrid.json) |
| 155 | + * [REST APIs](https://docs.microsoft.com/en-us/rest/api/eventgrid/partnernamespaces) |
| 156 | + * [CLI Extension](https://docs.microsoft.com/en-us/cli/azure/ext/eventgrid/?view=azure-cli-latest) |
| 157 | + |
| 158 | +### SDKs |
| 159 | + * [.Net](https://www.nuget.org/packages/Microsoft.Azure.Management.EventGrid/5.3.1-preview) |
| 160 | + * [Python](https://pypi.org/project/azure-mgmt-eventgrid/3.0.0rc6/) |
| 161 | + * [Java](https://search.maven.org/artifact/com.microsoft.azure.eventgrid.v2020_04_01_preview/azure-mgmt-eventgrid/1.0.0-beta-3/jar) |
| 162 | + * [Ruby](https://rubygems.org/gems/azure_mgmt_event_grid/versions/0.19.0) |
| 163 | + * [JS](https://www.npmjs.com/package/@azure/arm-eventgrid/v/7.0.0) |
| 164 | + * [Go](https://github.com/Azure/azure-sdk-for-go) |
| 165 | + |
| 166 | + |
| 167 | +## Next Steps |
| 168 | +- [Partner Topics overview](partner-topics-overview.md) |
| 169 | +- [Partner Topics onboarding form](https://aka.ms/gridpartnerform) |
| 170 | +- [Auth0 Partner Topic](auth0-overview.md) |
| 171 | +- [How to use the Auth0 Partner Topic](auth0-how-to.md) |
0 commit comments