Panoramica API per l'invio di offerte private

Articolo
06/14/2024

Le offerte private consentono agli editori e ai clienti di effettuare transazioni di uno o più prodotti in Azure Marketplace creando prezzi con limiti di tempo con termini personalizzati. Le API di invio di offerte private consentono agli editori di creare e gestire a livello di codice offerte private per i clienti e/o i partner CSP. Questa API usa l'ID Microsoft Entra per autenticare le chiamate dall'app o dal servizio.

Esistono tre tipi principali di offerte private disponibili nel Centro per i partner e supportate dall'API di invio dell'offerta privata:

ISV per l'offerta privata del cliente: è stata anche chiamato Offerta privata del cliente nel Centro per i partner. Si tratta di una trattativa personalizzata tra un ISV e un cliente specifico con termini e prezzi personalizzati per un prodotto specifico in Azure Marketplace. Altre informazioni sull'ISV per l'offerta privata del cliente.
Offerta privata da ISV a partner CSP: è stata anche chiamata offerta privata per i partner CSP nel Centro per i partner. Questo tipo di offerta privata consente all'ISV di specificare il margine associato al tempo per creare un prezzo all'ingrosso per il partner CSP. Altre informazioni sull'offerta privata da ISV a partner CSP.
Offerta privata multiparty : una trattativa personalizzata configurata in modo collaborativo da un ISV e da un partner di vendita preferito di un cliente specifico con termini e prezzi personalizzati per prodotti specifici in Azure Marketplace. L'ISV definisce il prezzo all'ingrosso scontato reso disponibile al partner, il partner di vendita può quindi aggiungere markup al prezzo all'ingrosso per arrivare al prezzo finale del cliente e presenta l'offerta al cliente per l'accettazione e l'acquisto. L'accettazione e l'acquisto di MPO seguono lo stesso flusso dell'ISV per le offerte private dei clienti. Altre informazioni sull'offerta privata multiparty.

Terminologia

Origine MPO: MPO è una collaborazione tra ISV e partner di vendita nello stesso accordo personalizzato per un cliente specifico, la parte che crea prima di tutto il MPO è designata l'"originatore" dell'offerta, in genere l'ISV dei prodotti inclusi nell'MPO. Può essere presente un solo originatore per qualsiasi MPO specificato.
Venditore MPO: il partner di vendita che prepara l'offerta con il prezzo finale del cliente e presenta l'offerta al cliente è il venditore dell'MPO. Ci può essere un solo venditore per qualsiasi MPO specificato.
Prodotto : una singola unità che rappresenta un'offerta in Azure Marketplace. Esiste un prodotto per pagina di presentazione.
Plan : una singola versione di un particolare prodotto. Possono essere presenti più piani per un determinato prodotto che rappresentano vari livelli di prezzi o termini.
Processo : un'attività creata durante l'esecuzione di una richiesta in questa API. Quando si usa questa API per gestire offerte private e offerte private multiparty, viene creato un processo per completare la richiesta. Una volta completato il processo, è possibile ottenere altre informazioni sull'offerta privata pertinente (multiparty).

Scenari supportati

Prepararsi all'uso di questa API

Prima di scrivere codice per chiamare l'API delle offerte private, assicurarsi di aver completato i prerequisiti seguenti. Gli stessi prerequisiti si applicano a tutti i partner di pubblicazione.

Passaggio 1: Completare i prerequisiti per l'uso dell'API di inserimento di prodotti Microsoft (una tantum)

L'utente o l'organizzazione devono disporre di una directory Microsoft Entra e un'autorizzazione di amministratore globale. Se si usa già Microsoft 365 o altri servizi aziendali di Microsoft, si dispone già della directory Microsoft Entra. In caso contrario, è possibile creare gratuitamente un nuovo ID Microsoft Entra nel Centro per i partner.

È necessario associare un'applicazione Microsoft Entra ID all'account del Centro per i partner e ottenere l'ID tenant, l'ID client e la chiave. Questi valori sono necessari per ottenere il token di accesso Microsoft Entra che verrà usato nelle chiamate all'API delle offerte private.

Passaggio 2: Ottenere un token di accesso Microsoft Entra (ogni volta)

Prima di chiamare uno dei metodi nell'API di invio a Microsoft Store, è necessario un token di accesso di Microsoft Entra per passare all'intestazione di autorizzazione di ogni metodo nell'API. Sono disponibili 60 minuti per l'uso di un token prima della scadenza. Dopo la scadenza, è possibile aggiornare un token in modo da poter continuare a usarlo in altre chiamate all'API.

Per ottenere il token di accesso, vedere Chiamate da servizio a servizio tramite credenziali client per inviare un HTTP POST all'endpoint https://login.microsoftonline.com/<tenant_id>/oauth2/token . Ecco una richiesta di esempio:

POST https://login.microsoftonline.com/<tenant_id>/oauth2/token HTTP/1.1
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded; charset=utf-8
grant_type=client_credentials
&client_id=<your_client_id>
&client_secret=<your_client_secret>
&resource=https://graph.microsoft.com/

Per il valore tenant_id nell'URI POST e nei parametri client_id e client_secret, specificare l'ID tenant, l'ID client e la chiave per l'applicazione recuperata dal Centro per i partner nella sezione precedente. Per il parametro della risorsa, è necessario specificare https://graph.microsoft.com/.

Trovare ID prodotto, piano e offerta privata

ID	Dove trovarli
client_id	Vedere Associare un'applicazione Microsoft Entra all'account del Centro per i partner.
tenant_id	Vedere Associare un'applicazione Microsoft Entra all'account del Centro per i partner.
client_secret	Vedere Associare un'applicazione Microsoft Entra all'account del Centro per i partner.
productId	Vedere Recuperare i prodotti in questo articolo.
planId	Vedere Recuperare i piani per un prodotto specifico in questo articolo.
privateofferId	Vedere Recuperare offerte private in questo articolo.

Recuperare i prodotti

Un'offerta privata si basa su un prodotto esistente nell'account del Centro per i partner. Per visualizzare un elenco di prodotti associati all'account del Centro per i partner, usare questa chiamata API:

GET https://graph.microsoft.com/rp/product-ingestion/product?$version=2022-07-01

La risposta viene visualizzata nel formato di esempio seguente:

{
  "value": [
    {
      "$schema": "https://schema.mp.microsoft.com/schema/product/2022-07-01",
      "id": "string",
      "identity": {
        "externalId": "string"
      },
      "type": "enum",
      "alias": "string"
    }
  ],
  "@nextLink": "opaque_uri"
}

Recuperare piani per un prodotto specifico

Per i prodotti che contengono più piani, è possibile creare un'offerta privata in base a un piano specifico. In tal caso, è necessario l'ID del piano. Ottenere un elenco dei piani (ad esempio varianti o SKU) per il prodotto usando la chiamata API seguente:

GET https://graph.microsoft.com/rp/product-ingestion/plan?product=<product-id>&$version=2022-07-01

La risposta viene visualizzata nel formato di esempio seguente:

{
  "value": [
    {
      "$schema": "https://schema.mp.microsoft.com/schema/plan/2022-07-01",
      "product": "string",
      "id": "string",
      "identity": {
        "externalId": "string"
      },
      "alias": "string"
    }
  ]
}

Recuperare le offerte private

Per visualizzare un elenco di tutte le offerte private, incluse le offerte private multiparty, associate all'account, usare la chiamata API seguente:

GET https://graph.microsoft.com/rp/product-ingestion/private-offer/query?$version=2023-07-15

Come usare l'API

L'API dell'offerta privata consente di creare e gestire offerte private associate a prodotti e piani all'interno dell'account del Centro per i partner. Ecco un riepilogo del modello di chiamata tipico quando si usa questa API.

Passaggio 1: Effettuare la richiesta

Quando si effettua una chiamata API per creare, eliminare, ritirare o aggiornare un'offerta privata, viene creato un nuovo processo per completare l'attività richiesta. La risposta dell'API contiene un id processo associato al processo.

Passaggio 2: Eseguire il polling dello stato del processo

Usando jobId dalla risposta api iniziale, eseguire il polling per ottenere lo stato del processo. Lo stato del processo sarà In esecuzione o Completato. Una volta completato il processo, il risultato sarà Riuscito o Non riuscito. Per evitare problemi di prestazioni, non eseguire il polling di un processo più di una volta al minuto.

jobStatus	Descrizione
NotStarted	Il processo non è ancora stato avviato; questa è parte della risposta nella richiesta iniziale.
In esecuzione	Il processo è ancora in esecuzione.
Completato	Il processo è stato completato. Per altri dettagli, vedere jobResult .
jobResult	Descrizione
In sospeso	Il processo non è ancora stato completato.
Completato	Il processo è stato completato correttamente. Questo processo restituisce anche un URI di risorsa che fa riferimento all'offerta privata correlata al processo. Usare questo resourceURI per ottenere i dettagli completi di un'offerta privata.
Non riuscito	Il processo non è riuscito. Vengono restituiti anche eventuali errori rilevanti per determinare la causa dell'errore.

Per altre informazioni, vedere Eseguire una query sullo stato di un processo esistente.

Passaggio 3: Ottenere informazioni dai processi completati

Un processo con esito positivo restituisce un oggetto resourceUri che fa riferimento all'offerta privata pertinente. Usare questo URI di risorsa per ottenere altri dettagli sull'offerta privata in futuro, ad esempio privateofferId.

Un processo non riuscito contiene errori che forniscono informazioni dettagliate sul motivo per cui il processo non è riuscito e su come risolvere il problema.

Per altre informazioni, vedere Ottenere i dettagli di un'offerta privata esistente.

In che modo isv e partner di vendita devono usare in modo collaborativo l'API per un'offerta privata multiparty

Sia l'ISV che il partner di vendita possono usare le stesse API per la creazione e la gestione di un determinato MPO. Tuttavia, le risorse in un MPO che possono influire sull'API dipendono dal fatto che il chiamante dell'API sia l'ISV (originatore) o il partner di vendita (venditore) dell'MPO. Lo stesso flusso di pubblicazione dei partner ISV/selling e le regole di business che regolano il Centro per i partner vengono rispecchiati nell'API. Ecco una panoramica:

Operazione API	ISV (Originator)	Partner di vendita (venditore)
Creazione	Il gruppo di destinatari previsto è il partner di vendita(venditore) quando viene pubblicata la chiamata API, il cliente finale non visualizzerà l'offerta privata finché il partner di vendita non invia Risorse modificabili: Date di validità Beneficiario previsto (cliente) Vendita partner per collaborare all'offerta, limitato a 1 per offerta privata Contatti ISV aggiuntivi per ricevere una notifica dello stato dell'offerta privata Condizioni e termini personalizzati ISV Prodotti/piani inclusi nell'offerta privata Durata del contratto per ogni prodotto/piano Quantità incluse per ogni prodotto (se applicabile) Attributi del piano nonpricing (se applicabile) Prezzo all'ingrosso scontato disponibile per il partner di vendita sui prodotti/piano inclusi Note di vendita ISV	Il gruppo di destinatari previsto è il cliente finale quando viene pubblicata la chiamata API Risorse modificabili: Vendita di termini e condizioni personalizzati per i partner Preparato da Rettifica cliente (percentuale di markup) sopra il prezzo all'ingrosso ISV per ogni prodotto/piano incluso nell'offerta privata, ciò determina il prezzo finale del cliente finale Ulteriori contatti dei partner di vendita per ricevere una notifica dello stato dell'offerta privata Vendita di note di vendita dei partner
Elimina	Supportato per le offerte private in stato bozza	Non supportate
Ritirare	Supportato per le offerte private pubblicate dall'ISV ma non ancora pubblicate dal partner di vendita o se ritirate dal partner di vendita	Supportato per le offerte private pubblicate e disponibili per i clienti finali ma non ancora accettate

Operazione API

ISV (Originator)

Partner di vendita (venditore)

Creazione

Il gruppo di destinatari previsto è il partner di vendita(venditore) quando viene pubblicata la chiamata API, il cliente finale non visualizzerà l'offerta privata finché il partner di vendita non invia

Risorse modificabili:

Date di validità
Beneficiario previsto (cliente)
Vendita partner per collaborare all'offerta, limitato a 1 per offerta privata
Contatti ISV aggiuntivi per ricevere una notifica dello stato dell'offerta privata
Condizioni e termini personalizzati ISV
Prodotti/piani inclusi nell'offerta privata
Durata del contratto per ogni prodotto/piano
Quantità incluse per ogni prodotto (se applicabile)
Attributi del piano nonpricing (se applicabile)
Prezzo all'ingrosso scontato disponibile per il partner di vendita sui prodotti/piano inclusi
Note di vendita ISV

Il gruppo di destinatari previsto è il cliente finale quando viene pubblicata la chiamata API