Microsoft Advertising

Microsoft Advertising connects as accounts and raw requests. Tempio holds the sign-in, lists the ad accounts it reaches, keeps each connected account's name, currency, time zone and status current, and carries raw requests to Microsoft Advertising's own API. It reads no campaigns or daily numbers from Microsoft Advertising.

Connecting

Connect on the Microsoft Advertising card opens Microsoft's sign-in. It asks you to choose a Microsoft account first, even when the browser is already signed in to one, so a workspace is not connected under whichever login happened to be open.

The consent screen names the app "Tempio Ads" and asks for two permissions:

The sign-in uses PKCE: the code Microsoft hands back is only redeemable together with a secret Tempio kept on its side of the flow.

When you come back, the picker lists every account the login can reach. Tick the accounts Tempio may use and press Connect selected; each becomes one connection on the card.

Customers and accounts

Microsoft Advertising groups accounts under customers, and a login holds a role on one or more customers. Tempio reads the signed-in user, then the customers that user holds a role in, then the accounts under each customer. Every account in the picker belongs to one customer, and the connection records that customer's id beside the account id. An account reachable under two customers is listed once, under the first.

An account is listed but cannot be ticked when Tempio has no IANA time zone or no currency for it. The reason is printed under the account id.

Time zones

Microsoft names an account's time zone with its own list of values, most of them a group of cities that share one offset, such as CanberraMelbourneSydney or EasternTimeUSCanada. Tempio stores an IANA zone on every account, so each Microsoft value maps to one IANA zone with the same offset and daylight rule: CanberraMelbourneSydney is Australia/Sydney, EasternTimeUSCanada is America/New_York.

A value that is not in Tempio's map is never guessed. The picker shows the account with the sentence "Microsoft reports this account's time zone as {value}, which has no IANA mapping in Tempio, so the account cannot be connected." If a connected account later reports a value outside the map, the next account check fails with the same sentence on the card, and the account keeps the currency and time zone Tempio last stored for it.

What Tempio reads

The connected account itself, on the connection's sync schedule: its id, name, currency, time zone and status.

On a sandbox deployment every account is marked as a test account.

The developer token and the headers Tempio sends

Tempio sends an app-level developer token on every Microsoft Advertising call. It is Tempio's own, held in Tempio's configuration, so a workspace does not need one.

Every call Tempio sends carries these headers, set by Tempio:

A raw request has no header parameter, so none of these can be supplied, replaced or left out by the caller. A request body is sent as written, and may name a customer or an account where the operation takes one there.

Raw requests on Microsoft Advertising

Raw platform requests covers the switch, who can turn it on, and the audit record. On Microsoft Advertising the path starts with the service it is for, and the service decides the host:

A path under none of these prefixes is refused before anything is sent. The request body is sent as JSON.

Why reads are POSTs

Tempio sends Microsoft Advertising's read operations as POSTs with their filters in a JSON body, so the method cannot say whether a request reads or changes. Tempio decides by the operation instead. A POST or GET whose last path segment starts with Get, Query or Search is a read. The same path sent as DELETE or PUT is a change, and so is every path the rule does not match.

A read, end to end

The paths in these two examples follow Microsoft's REST reference. They show the shape of a request, and are not a guarantee that Microsoft serves that endpoint.

An agent or a person with a read key asks for the account's search campaigns:

{
  "entity": "platform_request",
  "action": "get",
  "params": {
    "connectionId": "…",
    "method": "POST",
    "path": "/CampaignManagement/v13/Campaigns/QueryByAccountId",
    "body": { "AccountId": 50001, "CampaignType": "Search" },
    "description": "List the search campaigns on the Goat Club account."
  }
}

Tempio checks the connection, the workspace switch and the connection's kill switch, classifies the request as a read, and sends POST https://campaign.api.bingads.microsoft.com/CampaignManagement/v13/Campaigns/QueryByAccountId with the four headers above and the body as written. Microsoft's answer comes back in the tool result, and the audit log records the method, host, path, status and response size.

A change, end to end

Pausing a campaign is a change, so it is drafted with a draft key:

{
  "entity": "platform_request",
  "action": "mutate",
  "params": {
    "connectionId": "…",
    "method": "PUT",
    "path": "/CampaignManagement/v13/Campaigns",
    "body": {
      "AccountId": 50001,
      "Campaigns": [{ "Id": 734001, "Status": "Paused" }]
    },
    "description": "Pause the Brand campaign while the landing page is down."
  }
}

Nothing is sent yet. The request becomes a change request on the drafts page, with your description, the method and the path. No approval rule clears a raw change, so it waits for a person with approve access to the connection. Once approved, Tempio checks the switches and the kill switch again, sends the request once, and stores Microsoft's response on the draft. The draft carries a warning that Tempio did not read the change back, because it does not model the endpoint, and the connection's account check runs again.

Throttling

When Microsoft Advertising answers that Tempio is calling too often, the request fails as rate limited and names the wait Microsoft gives, or a minute when it gives none.

What is not read

Campaigns, ad groups, ads, keywords, audiences and daily numbers. Nothing from Microsoft Advertising enters Tempio's reports or the dashboard, and there are no modelled drafts such as a budget change for a Microsoft account; a change is a raw request. A raw answer is Microsoft's own: money is in Microsoft's units rather than minor units, and every ratio is Microsoft's.

Reconnecting

Tempio renews the access token in the background when it has twenty minutes or less left. When a renewal comes back with a new refresh token, Tempio stores it in place of the old one.

When Microsoft refuses a renewal, because access was removed, the password or a sign-in policy changed, or the connection went unused too long, the connection shows that it needs reconnecting. Reconnect runs the sign-in again and keeps every row Tempio holds.

Tempio sends Microsoft no revoke request when a connection is disconnected. To end Tempio's access on Microsoft's side as well, remove the app named "Tempio Ads" from the apps your Microsoft account has consented to.