Delen via


Create or Overwrite an Installation

 

Updated: March 11, 2016

Creates or overwrites an installation.

Request

Method

Request URI

HTTP version

PUT

https://{namespace}.servicebus.windows.net/{NotificationHub}/installations/{id}?api-version=2015-01

HTTP/1.1

Request Headers

The following table describes required and optional request headers.

Request Header

Description

Content-Type

application/json

Authorization

Token generated as specified in Shared Access Signature Authentication with Service Bus, or Service Bus authentication and authorization with Microsoft Azure Active Directory Access Control (also known as Access Control Service or ACS).

x-ms-version

2015-01

Request Body

The following table describes the properties of the JSON request body for installations:

Name

Type

Required

Read-Only

Description

installationId

String

Yes

No

Globally unique identifier string

lastActiveOn

String

No

Yes

This is the date when the installation was made inactivate by the PNS.

expirationTime

String

No

Yes

This is a string containing the date and time in W3C DTF, YYYY-MM-DDThh:mmTZD (e.g. 1997-07-16T19:20+01:00)) in which the registration will expire. The value can be set at the hub level on create or update, and will default to never expire (9999-12-31T23:59:59).

lastUpdate

String

Ignored when updating. Returned when reading.

Yes

Date in W3C format of last update to this installation.

platform

String

Yes

No

Can be {apns, wns, mpns, adm, gcm}.

pushChannel

String

Yes

No

The PNS handle for this installation (in case of WNS the ChannelUri of the ApplicationTile).

expiredPushChannel

Boolean

Ignored when updating. Returned when reading.

Yes

This is true if the PNS expired the channel.

tags

Array of strings

No

No

An array of tags. Tags are strings as defined in hub specs.

templates

JSON object

No

No

A JSON object representing a dictionary of templateNames to template description.

templates.{name}

String

No

No

JSON object representing a template.

templates.{name}.body

String

Yes, if template present

No

Template for the body of notification payload.

templates.{name}.headers

JSON object

No. Can be present only if platform is wns or mpns.

No

JSON object where each property is a header name and value is a template expression.

templates.{name}.expiry

String

No. Can be present only if platform is apns

No

Template expression evaluating in W3D date format.

templates.{name}.tags

Array of strings

No

No

Array of tags for this template.

secondaryTiles

JSON object

No. Can be present only if platform is wns.

No

JSON object containing a dictionary of tileId and secondaryTiles objects.

secondaryTile.{tileId}

JSON object

No

No

JSON object with push properties for secondary tiles.

secondaryTile.{tileId}.pushChannel

String

Yes, if tileId is present

No

ChannelUri for secondary tile.

secondaryTile.{tileId}.tags

Array of strings

No

No

Tags for native notifications to secondary tile.

secondaryTile.{tileId}.templates

JSON object

No

No

Same as templates property but for each secondary tile.

  • In JSON, the order of elements is not important.

  • Template body has to be JSON for APNS, GCM, ADM.

  • Template body must be XML for WNS and MPNS (except when raw).

  • Templates for WNS must include X-WNS-Type header.

  • Templates for MPNS must have compatible headers as mentioned in Sending push notifications for Windows Phone 8.

Some JSON examples follow.

Example to register with APNS:

{ 
    "installationId": "12234", 
    "tags": ["foo", "bar"], 
    "platform": "apns", 
    "pushChannel": "ABCDEF-123456-…" 
}  

Note

The Tags element is optional.

Example to register natively with WNS including a template and no tags:

{ 
    "installationId": "12234", 
    "platform": "wns", 
    "pushChannel": "https://db3...", 
    "templates": { 
        "myTemplate" : { 
            body : '<toast><visual lang="en-US"><binding template="ToastTest01"><text id="1">$myTextProp1</text></binding></visual></tile>',
            headers: { "X-WNS-Type": "wns/toast" }, 
            "tags": ["foo", "bar"] 
            } 

        } 
}  

A skeleton listing of many possible elements

{ 
    installationId: "", 
    expirationTime: "", 
    tags: ["foo", "bar"],
    lastUpdate: “”, 
    user: "", 
    advertisingId: "", 
    appId: "" 
    platform: "", 
    pushChannel: "", 

    templates: { 
        "templateName1" : { 
            body: "", 
            headers: { "X-WNS-Type": "wns/tile" }, 
            expiration: "",
            tags: ["foo", "bar"] 
            } 
        } 

    secondaryTiles: { 
        "tileId1": { 
            pushChannel: "", 
            tags: ["foo", "bar"], 

            templates: { 
                "otherTemplate": { 
                    bodyTemplate: "", 
                    headers: { ... }, 
                    tags: ["foo"] 
                    } 
                } 
            } 
        }
}  

Response

The response includes an HTTP status code and a set of response headers.

Response Codes

Code

Description

200

The installation was created successfully.

400

The installation could not be created/overwritten because the request was malformed.

401

Authorization failure. The access key was incorrect.

403

Too many installations in this namespace - Installations not created .

403

Request rejected because API call rate is too high.

For information about status codes, see Status and Error Codes.

Response Headers

Response Header

Description

Content-type

application/json

Content-Location

The location of the installation in the format:

https://{namespace}.servicebus.windows.net/{NotificationHub}/installations/<installationId>

Response Body

None.

See Also

Read Installation
Update Installation by Installation ID
Delete Installation