Gestire le righe di recapito

  • Articolo

Utilizza questi metodi nell'API delle promozioni di Microsoft Store per creare una o più linee di consegna per acquistare inventario e pubblicare i tuoi annunci per una campagna pubblicitaria promozionale. Per ciascuna linea di consegna, puoi impostare il targeting, impostare il prezzo dell'offerta e decidere quanto vuoi spendere impostando un budget e collegandoti alle creatività che desideri utilizzare.

Per ulteriori informazioni sulla relazione tra linee di consegna e campagne pubblicitarie, oggetti creativi e profili di targeting, vedere Esegui campagne pubblicitarie utilizzando i servizi di Microsoft Store.

NotaPrima di poter creare correttamente linee di consegna per campagne pubblicitarie utilizzando questa API,devi prima creare una campagna pubblicitaria a pagamento utilizzando la paginaAd campaignsnel Centro Partner, e devi aggiungere almeno uno strumento di pagamento in questa pagina. Dopo aver eseguito questa operazione, sarai in grado di creare correttamente linee di consegna fatturabili per campagne pubblicitarie utilizzando questa API. Le campagne pubblicitarie create utilizzando l'API fattureranno automaticamente lo strumento di pagamento predefinito scelto nella pagina di Ad campaignsnel Partner Center.

Prerequisiti

Per usare questi metodi, è prima di tutto necessario eseguire queste operazioni:

  • Se non è già stato fatto, completare tutti i prerequisiti per l'API Promozioni di Microsoft Store.

    Nota

    Come parte dei prerequisiti, assicurati dicreare almeno una campagna pubblicitaria a pagamento nel Centro partner e di aggiungere almeno uno strumento di pagamento per la campagna pubblicitaria nel Centro per i partner. Le linee di consegna create utilizzando questa API fattureranno automaticamente lo strumento di pagamento predefinito scelto nella pagina di Ad campaignsnel Partner Center.

  • Ottenere un token di accesso di Azure AD da usare nell'intestazione della richiesta per questi metodi. Dopo aver ottenuto un token di accesso, questo sarà disponibile per 60 minuti prima della scadenza. Dopo la scadenza del token, è possibile ottenerne uno nuovo.

Richiesta

Questi metodi hanno gli URI seguenti.

Tipo di metodo URI della richiesta Descrizione
POST https://manage.devcenter.microsoft.com/v1.0/my/promotion/line Crea una nuova linea di consegna.
PUT https://manage.devcenter.microsoft.com/v1.0/my/promotion/line/{lineId} Modifica la linea di consegna specificata da lineId.
GET https://manage.devcenter.microsoft.com/v1.0/my/promotion/line/{lineId} Ottieni la linea di consegna specificata da lineId.
Intestazione Type Descrizione
Autorizzazione stringa Obbligatorio. Token di accesso di Azure AD nel formato Token di<connessione>.
ID tracciabilità GUID (Facoltativo). ID che tiene traccia del flusso di chiamata.

Corpo della richiesta

I metodi POST e PUT richiedono un corpo della richiesta JSON con i campi obbligatori di un oggetto linea di consegna ed eventuali campi aggiuntivi che desideri impostare o modificare.

Esempi di richiesta

L'esempio seguente dimostra come chiamare il metodo POST per creare una linea di consegna.

POST https://manage.devcenter.microsoft.com/v1.0/my/promotion/line HTTP/1.1
Authorization: Bearer <your access token>

{
    "name": "Contoso App Campaign - Paid Line",
    "configuredStatus": "Active",
    "startDateTime": "2017-01-19T12:09:34Z",
    "endDateTime": "2017-01-31T23:59:59Z",
    "bidAmount": 0.4,
    "dailyBudget": 20,
    "targetProfileId": {
        "id": 310021746
    },
    "creatives": [
        {
            "id": 106851
        }
    ],
    "campaignId": 31043481,
    "minMinutesPerImp ": 1
}

L'esempio seguente dimostra come chiamare il metodo GET per recuperare una linea di consegna.

GET https://manage.devcenter.microsoft.com/v1.0/my/promotion/line/31019990  HTTP/1.1
Authorization: Bearer <your access token>

Response

Questi metodi restituiscono un corpo della risposta JSON con un oggettolinea di consegna che contiene informazioni sulla linea di consegna creata, aggiornata o recuperata. Nell'esempio seguente viene illustrato un corpo della risposta per questi metodi.

{
    "Data": {
        "id": 31043476,
        "name": "Contoso App Campaign - Paid Line",
        "configuredStatus": "Active",
        "effectiveStatus": "Active",
        "effectiveStatusReasons": [
            "{\"ValidationStatusReasons\":null}"
        ],
        "startDateTime": "2017-01-19T12:09:34Z",
        "endDateTime": "2017-01-31T23:59:59Z",
        "createdDateTime": "2017-01-17T10:28:34Z",
        "bidType": "CPM",
        "bidAmount": 0.4,
        "dailyBudget": 20,
        "targetProfileId": {
            "id": 310021746
        },
        "creatives": [
            {
                "id": 106126
            }
        ],
        "campaignId": 31043481,
        "minMinutesPerImp ": 1,
        "pacingType ": "SpendEvenly",
        "currencyId ": 732
    }
}

Oggetto linea di consegna.

I corpi di richiesta e risposta per questi metodi contengono i campi seguenti. Questa tabella mostra quali campi sono di sola lettura (ovvero non possono essere modificati nel metodo PUT) e quali campi sono obbligatori nel corpo della richiesta per i metodi POST o PUT.

Campo Tipo Descrizione Sola lettura Default Obbligatori per POST/PUT
id integer L'ID della linea di consegna. Sì No
name string Il nome della linea di consegna. No POST
configuredStatus string Uno dei seguenti valori che specifica lo stato della linea di consegna specificata dallo sviluppatore:
  • Attive
  • Non attiva
 No POST
effectiveStatus string ìUno dei seguenti valori che specifica lo stato effettivo della linea di consegna in base alla convalida del sistema:
  • Attive
  • Non attiva
  • in lavorazione
  • Non riuscito
 Sì No
effectiveStatusReasons array Uno o più dei seguenti valori che specificano il motivo dello stato effettivo della linea di consegna:
  • AdCreativesInactive
  • ValidationFailed
 Sì No
startDatetime string La data di inizio e l'orario per la linea di consegna, nel formato ISO 8601. Questo valore non può essere modificato se è già nel passato. No POST, PUT
endDatetime string La data di fine e l'orario per la linea di consegna, nel formato ISO 8601. Questo valore non può essere modificato se è già nel passato. No POST, PUT
createdDatetime string La data e l'ora di creazione della riga di consegna, nel formato ISO 8601. Sì No
bidType string Un valore che specifica il tipo di offerta della riga di consegna. Attualmente, l'unico valore supportato è CPM. No CPM No
bidAmount decimal L'importo dell'offerta da utilizzare per fare offerte per qualsiasi richiesta di annuncio. No Il valore CPM medio basato sui mercati target (questo valore viene rivisto periodicamente). No
dailyBudget decimal Il budget giornaliero per la riga di consegna. È necessario impostare dailyBudget olifetimeBudget. No POST, PUT (se lifetimeBudget non è impostato)
lifetimeBudget decimal Il budget totale per la linea di consegna È necessario impostare lifetimeBudget o dailyBudget. No POST, PUT (se dailyBudget non è impostato)
targetingProfileId oggetto Su un oggetto che identifica il profilo di targeting che descrive gli utenti, le aree geografiche e i tipi di inventario che desideri scegliere come target per questa riga di consegna. Questo oggetto di campo consiste singolo in un id o che specifica l'ID e il profilo di targeting. No No
oggetti creativi array Uno o più oggetti che rappresenta gli oggetti creativi associate alla linea di consegna.. Ogni oggetto in questo campo consiste singolo id o che specifica l'ID di un oggetto creativo. No No
campaignId integer L'ID della campagna pubblicitaria principale. No No
minMinutesPerImp integer Specifica l'intervallo di tempo minimo (in minuti) tra due impression mostrate allo stesso utente da questa riga di consegna. No 4000 No
pacingType string Uno dei seguenti valori che specificano il tipo di pacing:
  • SpendEvenly
  • SpendAsFastAsPossible
 No SpendEvenly No
currencyId integer L'ID della valuta della campagna. Sì La valuta dell'account sviluppatore (non è necessario specificare questo campo nelle chiamate POST o PUT) No