Condividi tramite


Panoramica API per l'invio di offerte private

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 ( MPO): una trattativa personalizzata configurata in modo collaborativo da un ISV e da un partner di canale 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 del canale può quindi aggiungere markup sopra il 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 canale sulla stessa trattativa personalizzata per un cliente specifico, la parte che prima crea il MPO è designata come "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 del canale 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.

Diagramma di flusso che mostra i passaggi delle offerte private multiparty.

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.

Modalità di uso collaborativo dell'API per l'offerta privata multiparty da parte del partner ISV e del canale

Sia l'ISV che il partner del canale 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 del canale (venditore) dell'MPO. Lo stesso flusso di pubblicazione dei partner ISV/canale e le regole di business che regolano il Centro per i partner vengono rispecchiate nell'API. Ecco una panoramica:

Operazione API ISV (Originator) Partner canale (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 fino a quando il partner del canale non invia
Risorse modificabili:
  • Date di validità
  • Beneficiario previsto (cliente)
  • Partner del canale 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 del canale sui prodotti/piani inclusi
  • Note di vendita ISV
  • Il gruppo di destinatari previsto è il cliente finale quando viene pubblicata la chiamata API
Risorse modificabili:
  • Condizioni e termini personalizzati del partner del canale
  • 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
  • Contatti aggiuntivi dei partner del canale per ricevere una notifica dello stato dell'offerta privata
  • Note di vendita per i partner del canale
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 del canale o se ritirate dal partner del canale
  • Supportato per le offerte private pubblicate e disponibili per i clienti finali ma non ancora accettate