API di inserimento prodotti per il marketplace commerciale
L'API di inserimento prodotti è un'API modernizzata che unifica tutte le API di invio esistenti in tutti i prodotti del marketplace commerciale. L'API consente di creare, pubblicare e gestire le risorse associate a prodotti e piani all'interno dell'account del Centro per i partner. Usa un modello dichiarativo per inviare richieste, in cui lo stato desiderato è indicato anziché specificare i singoli passaggi per raggiungere lo stato desiderato.
Questo articolo fornisce indicazioni su come iniziare a usare le API per qualsiasi tipo di offerta del marketplace commerciale. L'API di inserimento di prodotti è attualmente supportata per i tipi di offerta SaaS, MACCHINE virtuali, offerte private e contenitori ed è in anteprima. Per indicazioni specifiche per l'offerta, vedere Linee guida per le API per ogni tipo di offerta.
Importante
Azure Active Directory (Azure AD) Graph è deprecato a partire dal 30 giugno 2023. In futuro non verranno effettuati ulteriori investimenti in Azure AD Graph. Le API Graph di Azure AD non hanno alcun contratto di servizio o impegno di manutenzione oltre alle correzioni correlate alla sicurezza. Investimenti nelle nuove funzionalità e caratteristiche verranno effettuati solo in Microsoft Graph.
Azure AD Graph verrà ritirato nei passaggi incrementali in modo da avere tempo sufficiente per eseguire la migrazione delle applicazioni alle API Di Microsoft Graph. A una data successiva che verrà annunciata, si bloccherà la creazione di nuove applicazioni usando Azure AD Graph.
Per altre informazioni, vedere Importante: Ritiro di Azure AD Graph e Deprecazione del modulo PowerShell.
Introduzione
È possibile accedere all'API Inserimento prodotti usando l'API MSGraph con il nome del carico di lavoro "product-ingestion". L'URL di base è https://graph.microsoft.com/rp/product-ingestion.
Per usare l'API di inserimento prodotti, è necessario prima acquisire quanto segue:
- Un ID Microsoft Entra e assicurarsi di disporre delle autorizzazioni di amministratore globale per la directory
- Un'applicazione Microsoft Entra
- Un token di accesso Di Microsoft Entra
Passaggio 1: Completare i prerequisiti
Prima di iniziare a scrivere codice per chiamare l'API di inserimento prodotti, assicurarsi di aver completato i prerequisiti seguenti.
- L'utente (o l'organizzazione) deve disporre di una directory Microsoft Entra ed è necessario disporre dell'autorizzazione di amministratore globale per la directory. Se si usa già Microsoft 365 o altri servizi aziendali di Microsoft, si dispone già della directory Microsoft Entra. In caso contrario, è possibile creare un nuovo ID Entra Microsoft nel Centro per i partner senza costi aggiuntivi.
- È necessario associare un'applicazione Microsoft Entra all'account del Centro per i partner e ottenere l'ID tenant, l'ID client e la chiave. Sono necessari per ottenere il token di accesso Microsoft Entra che verrà usato nelle chiamate all'API di invio a Microsoft Store.
Associare un'applicazione Microsoft Entra all'account del Centro per i partner
Per usare l'API di inserimento prodotti, è necessario associare un'applicazione Microsoft Entra all'account del Centro per i partner, recuperare l'ID tenant e l'ID client per l'applicazione e generare una chiave. L'applicazione Microsoft Entra rappresenta l'app o il servizio da cui si vuole chiamare l'API di inserimento prodotti. Sono necessari l'ID tenant, l'ID client e la chiave per ottenere un token di accesso di Microsoft Entra da passare all'API.
Nota
È sufficiente eseguire questa attività una sola volta. Dopo aver ottenuto l'ID tenant, l'ID client e la chiave, è possibile riutilizzarli ogni volta che è necessario creare un nuovo token di accesso di Microsoft Entra.
- Nel Centro per i partner associare l'account del Centro per i partner dell'organizzazione alla directory Microsoft Entra dell'organizzazione.
- Nella pagina Utenti della sezione Impostazioni account del Centro per i partner aggiungere l'applicazione Microsoft Entra che rappresenta l'app o il servizio che userai per accedere agli invii per il tuo account del Centro per i partner. Assicurarsi di assegnare questa applicazione al ruolo Manager . Se l'applicazione non esiste ancora nella directory Microsoft Entra, creare una nuova applicazione Microsoft Entra nel Centro per i partner. Il Centro per i partner creerà due tipi di voci per l'applicazione, una come entità servizio e l'altra come tipo di applicazione Microsoft Entra.
- Tornare alla pagina Utenti, selezionare il nome dell'applicazione Microsoft Entra per passare alle impostazioni dell'applicazione e copiare i valori ID tenant e ID client.
- Selezionare Aggiungi nuova chiave. Nella schermata seguente copiare il valore chiave . Non sarà più possibile accedere a queste informazioni dopo aver lasciato la pagina. Per altre informazioni, vedere Gestire le chiavi per un'applicazione Microsoft Entra.
Passaggio 2: Ottenere un token di accesso di Microsoft Entra
Per chiamare uno dei metodi nell'API di inserimento di prodotti, è prima necessario ottenere un token di accesso di Microsoft Entra per passare all'intestazione Authorization di ogni metodo nell'API. Un token di accesso scade 60 minuti dopo il rilascio. Successivamente, è possibile aggiornarlo in modo da poterlo usare nelle chiamate future all'API.
Per ottenere il token di accesso, seguire le istruzioni riportate in Chiamate da servizio a servizio tramite le credenziali del client per inviare un HTTP POST all'endpoint https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token. Di seguito viene riportata una richiesta di esempio:
POST https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token HTTP/1.1
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded;
grant_type=client_credentials
&client_id=<your_client_id>
&client_secret=<your_client_secret>
&scope=https://graph.microsoft.com/.default
Per il valore tenant_id in POST URI e per i parametri client_id e client_secret, specificare l'ID tenant, l'ID client e la chiave per l'applicazione recuperati dal Centro per i partner nella sezione precedente. Per il parametro ambito, è necessario specificare https://graph.microsoft.com/.default.
Concetti
Prima di iniziare, è necessario comprendere alcuni concetti di base.
Risorse
L'API è strutturata in base ai tipi di risorse, in cui ogni tipo viene descritto usando una definizione di schema dedicata a cui fa riferimento la proprietà "$schema". Lo schema è costituito dalle proprietà di configurazione di tale risorsa. Le risorse sono fondamentali per la creazione e l'aggiornamento della configurazione di vari aspetti di un determinato prodotto. Per un elenco completo dei tipi di risorse e dei relativi schemi, vedere le informazioni di riferimento sull'API delle risorse.
ID durevole
Un ID durevole è un identificatore globale generato dal sistema usato per identificare in modo univoco qualsiasi risorsa. Ogni risorsa ha una proprietà "ID" associata, che, se combinata con il nome del tipo di risorsa, costituisce l'ID durevole di una risorsa. L'ID durevole viene usato quando si fa riferimento alle risorse per recuperare o modificare.
Formato:
\<resource-type>/\<id>
Esempio:
{
"$schema": "https://schema.mp.microsoft.com/schema/product/2022-03-01-preview3",
"id": "product/12345678-abcd-efgh-1234-12345678901", // durable ID
"identity": {
"externalID": "ds-contoso-image-resize-demo"
},
"type": "softwareAsAService", // Product types that can be specified include azureContainer, azureVirtualMachine, softwareAsAService
"alias": "Contoso Image Resizing Service"
}
ID esterno
Un ID esterno è un altro identificatore univoco che può essere usato per fare riferimento a prodotti o piani specifici. Si tratta di un modo alternativo per fare riferimento a queste risorse anziché usare l'ID durevole. L'ID esterno di un prodotto viene convertito in "offerID" e l'ID esterno di un piano viene convertito nel relativo "planID", come definito al momento della creazione nella proprietà "identity".
Esempio:
{
"$schema": "https://schema.mp.microsoft.com/schema/plan/2022-03-01-preview2",
"id": "plan/12345678-abcd-efgh-1234-12345678901/4e0bfefa-b993-4b79-a426-871c3bf236a5",
"identity": {
"externalID": "gold-annual"
},
"azureRegions": [
"azureGlobal"
],
"alias": "Gold - Annual payment",
"product": "product/12345678-abcd-efgh-1234-12345678901",
}
Metodi API
Esistono quattro API di gestione che possono essere usate per eseguire azioni diverse, ad esempio l'esecuzione di query sulle risorse esistenti, l'esecuzione di aggiornamenti della configurazione e il controllo dello stato di una richiesta.
Nota
Tutte le richieste richiedono di impostare la versione dello schema ($version parametro di query) desiderata come parte della risposta.
| Tipo di API | Descrizione | Metodo e percorso HTTP |
|---|---|---|
| Query | Recupera le risorse esistenti in base a: -Method 1: tipo di risorsa "resource-tree" -Method 2: durable-id -Method 3: parametri della stringa di query |
-Method 1: GET resource-tree/<product-durableID>-Method 2: GET <resource-durableID>-Method 3: GET <resourceType>?<query parameters> |
| Configurare l'invio | Invia richieste di creazione o aggiornamento di una o più risorse. Al termine dell'elaborazione, viene restituito un ID processo, che può essere usato per recuperare lo stato della richiesta. Questo tipo di API può essere usato per aggiornare lo stato bozza e pubblicare modifiche, sincronizzare gruppi di destinatari privati e modificare lo stato del ciclo di vita delle risorse. | POST configure |
| Configurare lo stato | Recupera lo stato di una richiesta in sospeso tramite jobID. | GET configure/<jobID>/status |
| Configurare i dettagli dello stato | Recupera un riepilogo dettagliato di una richiesta completata, incluse le risorse aggiornate, tramite l'ID processo. | GET configure/<jobID> |
| Annulla configurazione | Annulla il processo Di configurazione specificato. | POST configure/<jobID>/cancel |
un flusso di lavoro tipico
Per aggiornare una risorsa esistente, un flusso di lavoro tipico è:
- Recuperare una configurazione di risorsa esistente (tipo di API: eseguire una query tramite albero delle risorse)*
- Apportare eventuali aggiornamenti necessari e quindi inviare una richiesta di configurazione (tipo di API: Configurare l'invio)
- Controllare lo stato della richiesta (tipo di API: Configurare lo stato e Configurare i dettagli dello stato)
* Questo stesso flusso di lavoro può essere applicato durante la creazione di nuove risorse, ma invece di recuperare le risorse (passaggio 1), usare la tabella di riferimento dell'API risorsa per assicurarsi di usare lo schema corrente per il tipo di risorsa che si sta creando.
Per riepilogare, questa immagine mostra il modello di chiamata tipico usato per inviare una richiesta di configurazione, indipendentemente dal fatto che si stia creando una risorsa nuova o modificando una risorsa esistente.
Nota
Assicurarsi di esaminare eventuali prerequisiti aggiuntivi specifici del tipo di offerta che si sta gestendo facendo riferimento alla sezione Relativa al tipo di offerta .
Recuperare le configurazioni delle risorse esistenti
Prima di aggiornare le risorse esistenti, è importante recuperarle per assicurarsi di avere la configurazione più recente. Esistono diversi modi per recuperare le risorse tramite una chiamata GET. Vedere Il metodo 1, dettagliato di seguito, per recuperare tutte le risorse all'interno di un prodotto specifico in una singola chiamata API.
Metodo 1: Albero delle risorse
Schema: https://``schema.mp.microsoft.com``/schema/resource-tree/2022-03-01-preview2
GET resource-tree/<product-durableID>?$version=<schema-version>
È possibile recuperare tutte le configurazioni delle risorse all'interno di un prodotto specifico usando il tipo di risorsa "albero delle risorse" insieme all'ID durevole del prodotto.
La versione più recente dello schema disponibile può essere diversa per ogni risorsa. Quando si esegue una richiesta di albero delle risorse, la versione dello schema specificata determina quale versione viene restituita per ogni risorsa nel prodotto. La versione specificata funge da limite di versione "max" in quanto restituisce la versione più recente dello schema disponibile per tutte le risorse di versione uguale o precedente. Ad esempio, se la versione più recente dell'elenco di piani disponibile è "2022-03-01-preview3", la risposta esemplicherà questa versione se si specifica "2022-03-01-preview5" nella richiesta GET dell'albero delle risorse. Tuttavia, se si richiede "2022-03-01-preview2" come versione dell'albero delle risorse, verrà restituita la risorsa di elenco dei piani "2022-03-01-preview2", anche se la versione più recente disponibile è "2022-03-01-preview3". È consigliabile usare la versione più recente disponibile di ogni risorsa per assicurarsi di usare lo schema aggiornato con le nuove funzionalità supportate.
Nota
Se non si conosce l'ID durevole del prodotto, è possibile usare l'ID esterno del prodotto per recuperare la risorsa del prodotto eseguendo GET product?externalID=<product-externalID>&$version=<product-schema-version>. Questa richiesta sfrutta un parametro della stringa di query, descritto nel metodo 3 seguente. La risposta includerà l'ID durevole del prodotto, che è possibile usare per le richieste future.
Per impostazione predefinita, quando si esegue una chiamata GET usando l'albero delle risorse, viene restituita la versione bozza delle risorse. Tuttavia, passando il parametro di query "targetType", è possibile specificare la destinazione desiderata per recuperare i dati "preview" o "live". Nell'esempio seguente la chiamata GET restituisce la configurazione dell'ambiente di anteprima per tutte le risorse nel prodotto "12345678-abcd-efgh-1234-12345678901".
Chiamata GET di esempio:
GET https://graph.microsoft.com/rp/product-ingestion/resource-tree/product/12345678-abcd-efgh-1234-12345678901?targetType="preview"&$version=2022-03-01-preview5
Risposta campione:
{
"$schema": "https://schema.mp.microsoft.com/schema/resource-tree/2022-03-01-preview2",
"root": "product/12345678-abcd-efgh-1234-12345678901",
"target": {
"targetType": "preview"
},
"resources": [
{
"$schema": "https://schema.mp.microsoft.com/schema/product/2022-03-01-preview3",
"id": "product/12345678-abcd-efgh-1234-12345678901",
"identity": {
"externalID": "ds-contoso-image-resize-demo"
},
"type": "softwareAsAService",
"alias": "Contoso Image Resizing Service"
},
{
"$schema": "https://schema.mp.microsoft.com/schema/property/2022-03-01-preview3",
"id": "property/12345678-abcd-efgh-1234-12345678901/public/main",
"product": "product/12345678-abcd-efgh-1234-12345678901",
"kind": "azureSaaS",
"termsConditions": "false",
"categories": {
"developer-tools-saas": [
"devService"
]
}
},
{
"$schema": "https://schema.mp.microsoft.com/schema/plan/2022-03-01-preview2",
"id": "plan/12345678-abcd-efgh-1234-12345678901/4e0bfefa-b993-4b79-a426-871c3bf236a5",
"product": "product/071b135e-9faf-4ff7-b113-a3f25bb0f468",
...
},
// The response would include all existing resources within this product.
{
...
}]
}
Metodo 2: DURABLE ID
GET <resource-durableID>?$version=<schema-version>
Recuperare una risorsa specifica usando il relativo ID durevole. Dopo aver creato una risorsa, l'ID durevole rimane sempre lo stesso e può essere usato per recuperare le ultime modifiche bozza di tale risorsa chiamando il metodo GET. Ad esempio, la richiesta seguente restituirà la bozza di configurazione di questo prodotto specifico usando la versione dello schema "2022-03-01-preview3".
GET product/12345678-abcd-efgh-1234-12345678901?$version=2022-03-01-preview3
Importante
Questo metodo viene usato solo per recuperare la configurazione bozza. Per recuperare i dati in anteprima o in tempo reale, usare il metodo "albero delle risorse", come descritto in precedenza.
Per trovare l'ID durevole per le risorse, è possibile:
- Usare il metodo "resource-tree" per recuperare tutte le risorse all'interno del prodotto insieme a ognuno dei rispettivi ID durevoli o
- Recuperare i dettagli di una richiesta di configurazione della risorsa completata, che include gli ID durevoli per tutte le risorse create o aggiornate come parte della richiesta.
Tenere presente che la proprietà "ID" è l'ID durevole per la rispettiva risorsa.
Metodo 3: Parametri della stringa di query
GET <resourceType>?<query parameters>&$version=<schema-version>
Questo metodo viene usato per eseguire query su determinati tipi di risorse associati a un account specifico. Ad esempio, è possibile recuperare tutti i prodotti di un tipo di prodotto specifico con una singola chiamata GET. I parametri della stringa di query vengono usati per eseguire query sui dettagli relativi a prodotti, piani o invii.
Questa tabella mostra i parametri di query supportati per ognuno dei tipi di risorse supportati. Non tutti i tipi di risorse supportano ognuno dei parametri di query. Fare riferimento a questa tabella per l'elenco completo delle stringhe di query attualmente supportate.
| Tipo di risorsa | Parametri | Esempi di stringhe di query |
|---|---|---|
| piano | prodotto*externalID $maxpagesize continuationToken$version * |
GET plan?product=<product-durableID>&$version=<schema-version>GET plan?product=<product-durableID>&externalID=<plan-externalID>&$version=<schema-version>GET plan?product=<product-durableID>&$maxpagesize=<#>&$version=<schema-version>GET plan?product=<product-durableID>&continuationToken=<token>&$version=<schema-version> |
| product | externalID type $maxpagesize continuationToken$version * |
GET product?externalID=<product-externalID>&$version=<schema-version>GET product?type=<product-type>&$version=<schema-version>GET product?$maxpagesize=<#>&$version=<schema-version>GET product?continuationToken=<token>&$version=<schema-version> |
| invio | targetType $maxpagesize continuationToken$version * |
GET submission/<product-durableID>?targetType=<environment>&$version=<schema-version>GET submission/<product-id>?$maxpagesize=<#>&continuationToken=<token>&$version=<schema-version> |
| albero delle risorse | targetType$version* |
GET resource-tree/<product-durableID>?targetType=<environment>&$version=<schema-version> |
* I parametri di prodotto e $version sono sempre obbligatori.
Funzionalità di ognuno dei parametri di query supportati:
- product : quando si passa il parametro "product" nel contesto del tipo di risorsa "plan", restituisce tutti i piani all'interno di tale prodotto specifico.
- externalID : quando si passa il parametro "externalID" nel contesto di un prodotto o di un piano, restituisce la configurazione del rispettivo prodotto o piano. A differenza del metodo "resource-tree", questo parametro della stringa di query restituirà solo i dettagli di tale risorsa, non tutte le risorse al suo interno.
- type : quando si passa il parametro "type" nel contesto del tipo di risorsa "product", restituisce tutti i prodotti di quel tipo associati all'account. Ad esempio, specificando "type=softwareAsAService", verranno restituiti tutti i prodotti SaaS.
- targetType : restituisce i dati di un ambiente specifico nel contesto del tipo di risorsa usato. I valori "targetType" supportati sono "draft", "preview" o "live".
- $maxpagesize: specificando la dimensione massima della pagina, sotto forma di numero intero positivo, questo parametro viene usato per limitare i risultati della ricerca quando si eseguono query sui tuoi invii precedenti.
- continuationToken : questo parametro può essere usato con il parametro "$maxpagesize" per eseguire una query su un altro set di risultati disponibili nella ricerca. Il valore "continuationToken" viene fornito nella risposta della pagina precedente.
- $version: parametro obbligatorio per tutte le chiamate, specifica la versione dello schema desiderata per la risposta dalla richiesta effettuata. La versione più recente dello schema disponibile può essere diversa per ogni risorsa e la versione specificata funge da limite di versione "max". Il sistema restituisce la versione esatta dello schema, se disponibile o la versione più vicina precedente alla versione richiesta. Ciò consente di mantenere il codice funzionante anche se sono presenti modifiche più recenti dello schema, ma per usare le funzionalità più recenti, è consigliabile usare la versione più recente disponibile di ogni schema.
Esecuzione di query sui tuoi invii
È possibile recuperare gli invii di prodotti esistenti eseguendo GET submission/<product-durableID>. Per impostazione predefinita, vengono restituiti tutti gli invii attivi, incluso il riferimento bozza, ma è anche possibile eseguire query su un ambiente specifico usando il parametro di query "targetType": (GET submission/<product-durableID>?targetType=<environment>&$version=<version>).
Importante
Quando viene eseguito il push di un invio "Anteprima" in "Live", sostituisce qualsiasi invio "Live" precedente. In questo caso, i dati rappresentano ora sia gli ambienti "Anteprima" che "Live" fino a quando non viene pubblicato un nuovo invio in "Anteprima".
Richiesta di esempio:
GET https://graph.microsoft.com/rp/product-ingestion/submission/12345678-abcd-efgh-1234-12345678901?$version=2022-03-01-preview2
Risposta campione:
Questo esempio mostra una richiesta GET per gli invii attivi associati all'ID prodotto "12345678-abcd-efgh-1234-12345678901". L'invio attivo "Live" (invio/12345678-abcd-efgh-1234-12345678901/1152921515689847470) è stato pubblicato in anteprima prima e poi in tempo reale. Quando l'invio è stato inviato in tempo reale il 25 gennaio 2022, è stato rappresentato sia in anteprima che in tempo reale fino a quando non è stato creato un nuovo invio di anteprima (invio/12345678-abcd-efgh-1234-12345678901/1152921515689848683) il 4 febbraio 2022.
{
"value": [
{
"$schema": "https://schema.mp.microsoft.com/schema/submission/2022-03-01-preview2",
"id": "submission/12345678-abcd-efgh-1234-12345688901/0",
"product": "product/12345678-abcd-efgh-1234-12345678901",
"target": {
"targetType": "draft"
}
},
{
"$schema": "https://schema.mp.microsoft.com/schema/submission/2022-03-01-preview2",
"id": "submission/12345678-abcd-efgh-1234-12345678901/1152921515689847470",
"product": "product/12345678-abcd-efgh-1234-12345678901",
"target": {
"targetType": "live"
},
"status": "completed",
"result": "succeeded",
"created": "2022-01-25T07:13:06.4408032Z"
},
{
"$schema": "https://schema.mp.microsoft.com/schema/submission/2022-03-01-preview2",
"id": "submission/12345678-abcd-efgh-1234-12345678901/1152921515689848683",
"product": "product/12345678-abcd-efgh-1234-12345678901",
"target": {
"targetType": "preview"
},
"status": "completed",
"result": "succeeded",
"created": "2022-02-04T20:07:22.4220588Z"
}
]
}
Creare nuovi prodotti e risorse
È possibile creare nuove risorse, inclusi i nuovi prodotti, come parte di una singola richiesta di configurazione. Usando la tabella di riferimento dell'API risorsa, è possibile recuperare lo schema per il tipo di risorsa che si vuole creare. In questo modo si garantisce l'uso dello schema più recente e quindi la configurazione di tutte le proprietà necessarie per creare la risorsa.
Se si sta creando un nuovo prodotto, i requisiti variano in base al tipo di prodotto. Pertanto, è necessario fornire risorse diverse. È possibile fare riferimento alla documentazione del marketplace commerciale corrispondente per il rispettivo tipo di prodotto per assicurarsi di configurare i requisiti di base nella richiesta. In alternativa, è possibile effettuare una richiesta di configurazione usando solo la risorsa del prodotto. Dopo aver creato il prodotto, chiamare l'API configura dettagli stato per recuperare la risorsa del prodotto creata e trovare il relativo ID durevole per chiamare l'API query dell'albero delle risorse. La risposta restituisce le risorse supportate applicabili per il tipo di prodotto creato.
Analogamente, per creare una nuova risorsa all'interno di un prodotto esistente, è anche necessario recuperare lo schema più recente di quel tipo di risorsa specifico. Assicurarsi di fornire le risorse dipendenti come parte della richiesta di configurazione esaminando le dipendenze delle risorse.
Dopo aver costruito le risorse usando gli schemi, informazioni su come effettuare una richiesta di configurazione.
Modificare i prodotti e le risorse esistenti
È possibile inviare gli aggiornamenti usando il payload di configurazione. Questo payload è costituito da uno o più tipi di risorse e la proprietà "$schema" indica il tipo di risorsa a cui si fa riferimento.
Suggerimento
È consigliabile recuperare prima di tutto le risorse esistenti prima della pubblicazione degli aggiornamenti per assicurarsi di sfruttare la configurazione più recente.
Dopo aver modificato le risorse, informazioni su come effettuare una richiesta di configurazione.
Richieste di configurazione
È possibile modificare e pubblicare nello stesso payload. Per inviare una richiesta di configurazione, usare il metodo HTTP POST dell'API di configurazione. Il payload di configurazione è costituito da una matrice di risorse che indicano le modifiche desiderate. Tutte le modifiche influiscono solo sulla versione bozza fino a quando non si invia in modo esplicito una risorsa di invio per pubblicare le modifiche bozza. Quando si pubblica in anteprima o in tempo reale, includere la risorsa di invio e specificare l'ambiente di destinazione. Prima di inviare una richiesta, è necessario sapere come fare riferimento alle risorse e comprendere le relative dipendenze.
Schema:<https://schema.mp.microsoft.com/schema/configure/2022-03-01-preview2>
Quando si invia la richiesta di configurazione, viene restituito un oggetto configure-status con l'ID processo che è possibile usare per tenere traccia dello stato di avanzamento e dei risultati della richiesta.
Schema: <https://``schema.mp.microsoft.com``/schema/configure-status/2022-03-01-preview2>
Riferimenti alle risorse e dipendenze
Riferimenti
Per fare riferimento a una risorsa esistente in una richiesta di configurazione, specificare il tipo "$schema" della risorsa insieme all'ID durevole della risorsa. Nel caso di prodotti e piani, è anche possibile fare riferimento a queste risorse tramite il relativo ID esterno.
L'ID durevole è disponibile nella proprietà "ID", ad esempio se si tratta della risorsa del prodotto a cui si vuole fare riferimento in un'altra risorsa:
{
"$schema": "https://schema.mp.microsoft.com/schema/product/2022-03-01-preview3",
"id": "product/12345678-abcd-efgh-1234-12345678901",
"identity": {
"externalID": "ds-contoso-image-resize-demo"
},
"type": "softwareAsAService",
"alias": "Contoso Image Resizing Service"
}
L'ID durevole sarebbe "product/071b135e-9faf-4ff7-b113-a3f25bb0f468".
L'ID durevole può quindi essere usato nell'esempio di risorsa di elenco riportato di seguito impostandolo nella proprietà dello schema della risorsa "product" come illustrato di seguito:
{
"$schema": "https://schema.mp.microsoft.com/schema/listing/2022-03-01-preview5",
"product": "product/071b135e-9faf-4ff7-b113-a3f25bb0f468", // product durable ID
...
}
L'ID esterno delle risorse del prodotto e del piano è definito all'interno della proprietà "identity".
{
"$schema": "https://schema.mp.microsoft.com/schema/plan/2022-03-01-preview2",
"alias": "Gold - Annual payment",
"identity": {"externalID": "gold-annual"},
"product": "product/071b135e-9faf-4ff7-b113-a3f25bb0f468",
...
}
L'ID esterno del piano "gold-annual" può quindi essere fatto riferimento ad altre risorse successive nel formato seguente:
{
"$schema": "https://schema.mp.microsoft.com/schema/plan-listing/2022-03-01-preview5",
"product": "product/071b135e-9faf-4ff7-b113-a3f25bb0f468"}
"plan": {"externalID": "gold-annual"}
...
}
Richiesta di esempio:
In questo esempio viene usato il payload di configurazione per creare un nuovo prodotto SaaS con un ID esterno "ds-contoso-image-resize-demo". Al momento della creazione di questo prodotto, è possibile fare riferimento a questo prodotto in un secondo momento usando l'ID durevole o l'ID esterno.
POST https://graph.microsoft.com/rp/product-ingestion/configure?$version=2022-03-01-preview2
{
"$schema": "https://schema.mp.microsoft.com/schema/configure/2022-03-01-preview2"
"resources": [
{
"$schema": "https://schema.mp.microsoft.com/schema/product/2022-03-01-preview3",
"identity": {
"externalID": "ds-contoso-image-resize-demo"
},
"type": "softwareAsAService",
"alias": " Contoso Image Resizing Service"
}
]
}
Risposta campione:
{
"$schema": "https://schema.mp.microsoft.com/schema/configure-status/2022-03-01-preview2",
"jobID": "071b135e-9faf-4ff7-b113-a3f25bb0f468",
"jobStatus": "running",
"jobResult": "pending",
"jobStart": "2022-08-18T16:35:56.5917185Z",
"jobEnd": "0001-01-01T00:00:00",
"errors": []
}
È quindi possibile usare l'ID processo tramite l'API Configura stato per controllare lo stato della richiesta.
Dipendenze
Alcune risorse hanno dipendenze dalla creazione di un'altra risorsa come prerequisito. In questa circostanza viene usata la proprietà "resourceName" nello stesso payload per indicare la dipendenza della risorsa prodotto nella risorsa del piano durante la creazione di entrambe le richieste.
"resourceName" viene usato solo per identificare ogni risorsa come parte della richiesta di configurazione eseguita. Il valore non farà parte dei dati delle risorse, non viene archiviato né esposto ai clienti. Inoltre, se sono presenti errori nell'ambito della richiesta di configurazione, verrà usato "resourceName" per chiamare la risorsa a cui appartiene l'errore.
Richiesta di esempio:
In questo esempio, il prodotto deve essere creato prima del piano e pertanto viene utilizzata la proprietà "resourceName". Il prodotto creato, "myNewProduct", sarà il valore usato per "resourceName" e a cui viene fatto riferimento all'interno della risorsa del piano dipendente.
POST https://graph.microsoft.com/rp/product-ingestion/configure?$version=2022-03-01-preview2
{
"$schema": "https://schema.mp.microsoft.com/schema/configure/2022-03-01-preview2"
"resources": [
{
"$schema": "https://schema.mp.microsoft.com/schema/product/2022-03-01-preview3",
"resourceName": "myNewProduct",
"alias": "Contoso Image Resizing Service",
...
},
{
"$schema": "https://schema.mp.microsoft.com/schema/plan/2022-03-01-preview2",
"alias": " Gold - Annual payment",
"product": {"resourceName": "myNewProduct"}
...
},
}]
}
Risorsa di invio
Se si pubblica in "anteprima" o "live", includere la risorsa di invio nella richiesta, che contiene:
- La proprietà "product", che indica il prodotto che viene aggiornato come riferimento tramite l'ID durevole o l'ID esterno
- Proprietà "targetType", che indica l'ambiente di destinazione
Quando si pubblica in modo specifico, l'"ID" dell'invio di anteprima che si sta cercando di pubblicare:
{
"$schema": "https://schema.mp.microsoft.com/schema/submission/2022-03-01-preview2",
"id": "submission/12345678-abcd-efgh-1234-12345678901/11521167929065",
"product": "product/12345678-abcd-efgh-1234-12345678901",
"target": { "targetType": "live" }
}
Nota
Se non si include la risorsa di invio, le modifiche verranno apportate solo allo stato bozza.
Pubblicazione in anteprima
I tipi di prodotti commerciali supportano un ambiente di anteprima e ogni aggiornamento deve essere pubblicato in anteprima prima di passare in tempo reale. Non è possibile pubblicare direttamente in tempo reale.
Importante
L'eccezione è quando si apportano modifiche al gruppo di destinatari privato dei piani. Quando si sincronizzano gli aggiornamenti al gruppo di destinatari privato in modo specifico, queste modifiche verranno propagate in anteprima e in tempo reale contemporaneamente.
Esistono due modi per pubblicare le risorse nell'ambiente di anteprima. Se è necessario apportare modifiche all'invio in anteprima, eseguire un'altra richiesta GET, apportare le modifiche necessarie ed eseguire di nuovo il push delle modifiche. Non è necessario prima passare in tempo reale con le modifiche iniziali.
Metodo 1: Pubblicare tutte le risorse bozza
Se si vuole pubblicare ogni modifica bozza apportata, è possibile inviare una richiesta di configurazione con una risorsa di invio che imposta l'ambiente di anteprima come "targetType". Come illustrato nell'esempio seguente, non è necessario fornire in modo esplicito ogni risorsa che richiede un aggiornamento perché questo metodo pubblica tutte le modifiche nell'ambiente di destinazione, che in questo caso è in anteprima. È sufficiente fornire l'endpoint DELL'API e la risorsa di invio.
Richiesta di esempio:
POST https://graph.microsoft.com/rp/product-ingestion/configure?$version=2022-03-01-preview2
{
"$schema": "https://schema.mp.microsoft.com/schema/configure/2022-03-01-preview2"
"resources": [
{
// Below is the submission resource to publish to preview
"$schema": "https://schema.mp.microsoft.com/schema/submission/2022-03-01-preview2",
"product": "product/12345678-abcd-efgh-1234-12345678901", // This is the product durable ID
"target": { "targetType": "preview" }
}
]
}
Metodo 2: Pubblicare risorse bozza specifiche (note anche come pubblicazione modulare)
In alternativa, se non si è pronti a pubblicare tutte le bozze di modifiche tra varie risorse, è sufficiente fornire le risorse da pubblicare insieme alla risorsa di invio per attivare una pubblicazione modulare. È anche possibile usare questo approccio per apportare modifiche alle risorse e pubblicarle contemporaneamente anziché come parte di un aggiornamento in blocco, come avviee tramite il metodo 1. Per una pubblicazione modulare, tutte le risorse sono necessarie ad eccezione dei dettagli a livello di prodotto (ad esempio, presentazione, disponibilità, pacchetti, rivenditore) in base al tipo di prodotto.
Richiesta di esempio:
In questo esempio, le risorse nel prodotto vengono fornite in modo esplicito come parte della pubblicazione modulare seguita dalla risorsa di invio.
POST https://graph.microsoft.com/rp/product-ingestion/configure?$version=2022-03-01-preview2
{
"$schema": "https://schema.mp.microsoft.com/schema/configure/2022-03-01-preview2"
"resources": [
{
"$schema": "https://schema.mp.microsoft.com/schema/product/2022-03-01-preview2",
"id": "product/12345678-abcd-efgh-1234-12345678901",
...
},
{
"$schema": "https://schema.mp.microsoft.com/schema/plan/2022-03-01-preview2",
...
},
// additional resources
{
...
},
// Below is the submission resource to publish to preview
{
"$schema": "https://schema.mp.microsoft.com/schema/submission/2022-03-01-preview2",
"product": "product/12345678-abcd-efgh-1234-12345678901", // This is the product durable ID
"target": { "targetType": "preview" }
}
]
}
Pubblicazione in tempo reale
Dopo aver testato e verificato le modifiche nell'anteprima, è possibile eseguire il push delle modifiche in tempo reale inviando una richiesta di configurazione con l'"ID" dell'invio di anteprima e il valore "targetType" impostato su "live". Per trovare l'"ID" dell'invio di anteprima da incorporare all'interno della richiesta di configurazione, vedere Esecuzione di query sui tuoi invii.
Importante
A differenza della pubblicazione in anteprima, non è possibile eseguire una pubblicazione modulare durante la pubblicazione in tempo reale. È quindi importante assicurarsi di aver verificato l'invio dell'anteprima prima di passare in tempo reale con le modifiche.
Richiesta di esempio:
POST https://graph.microsoft.com/rp/product-ingestion/configure?$version=2022-03-01-preview2
{
"$schema": "https://schema.mp.microsoft.com/schema/configure/2022-03-01-preview2"
"resources": [
// Below is the submission resource, including the preview submission id, to publish to live.
{
"$schema": "https://schema.mp.microsoft.com/schema/submission/2022-03-01-preview2",
"id": "submission/12345678-abcd-efgh-1234-12345678901/11521167929065",
"product": "product/12345678-abcd-efgh-1234-12345678901", // This is the product durable ID
"target": { "targetType": "live" }
}
]
}
Controllare lo stato di una richiesta
Indipendentemente dalle risorse incluse nella richiesta di configurazione o dalle modifiche apportate, si otterrà un oggetto configure-status nella risposta poco dopo l'invio di una richiesta dopo l'elaborazione corretta. "jobID" è importante perché può essere usato in un secondo momento per controllare lo stato della richiesta.
Schema: <https://``schema.mp.microsoft.com``/schema/configure-status/2022-03-01-preview2>
Risposta di esempio a una richiesta inviata:
{
"$schema": "https://schema.mp.microsoft.com/schema/configure-status/2022-03-01-preview2",
"jobID": "d4261631-c583-4949-a612-5150882632e9",
"jobStatus": "notStarted",
"jobResult": "pending",
"jobStart": "2022-03-01T13:32:43.123456Z",
"jobEnd": "0001-01-01T00:00:00",
"errors": []
}
Stato di una richiesta in sospeso
È possibile recuperare lo stato fino al termine del processo usando la chiamata seguente e immettendo il "jobID" della richiesta. L'oggetto potrebbe anche contenere un elenco di errori se si sono verificati problemi con la richiesta.
GET https://graph.microsoft.com/rp/product-ingestion/configure/<jobID>/status?$version=2022-03-01-preview2
Tenere presente che il tempo necessario per il completamento può variare a seconda della complessità della richiesta,
Riepilogo di una richiesta completata
Una volta completato un processo di richiesta di configurazione, correttamente o con un errore, è possibile ottenere l'elenco delle risorse create o aggiornate usando il "jobID".
Nota
Se si effettua questa chiamata prima del completamento del processo, l'operazione avrà esito negativo. Inoltre restituirà solo le risorse completate correttamente o nel caso di un annullamento solo quelle completate prima dell'annullamento.
Schema: <https://``schema.mp.microsoft.com``/schema/configure-detail/2022-03-01-preview2>
GET https://graph.microsoft.com/rp/product-ingestion/configure/<jobID>?$version=2022-03-01-preview2
Richiesta di esempio:
Nell'esempio seguente viene usata una richiesta GET per recuperare i dettagli di riepilogo della richiesta di configurazione usata nell'esempio precedente che ha creato un nuovo prodotto SaaS. La risposta è l'oggetto configure-detail con la matrice di risorse contenente la risorsa prodotto creata insieme al relativo ID durevole.
GET https://graph.microsoft.com/rp/product-ingestion/configure/071b135e-9faf-4ff7-b113-a3f25bb0f468?$version=2022-03-01-preview2
Risposta campione:
{
"$schema": "https://schema.mp.microsoft.com/schema/configure-detail/2022-03-01-preview2",
"resources": [
{
"$schema": "https://schema.mp.microsoft.com/schema/product/2022-03-01-preview2",
"id": "product/12345678-abcd-efgh-1234-12345678901",
"identity": {
"externalID": "ds-contoso-image-resize-demo "
},
"type": "softwareAsAService",
"alias": "Contoso Image Resizing Service"
}
]
}
Annullare una richiesta di configurazione
Prima del completamento di un processo, è possibile tentare di annullarlo, se necessario. Per le richieste a esecuzione prolungata, ad esempio la pubblicazione in "anteprima" o "live", la richiesta di annullamento potrebbe essere rifiutata se il processo è abbastanza lungo durante l'elaborazione completa.
Per annullare un processo, effettuare una chiamata POST all'endpoint di annullamento e specificare l'ID processo della richiesta da annullare.
POST https://graph.microsoft.com/rp/product-ingestion/configure<jobID>/cancel?$version=2022-03-01-preview2
Richiesta di esempio:
POST <https://graph.microsoft.com/rp/product-ingestion/configure/d4261631-c583-4949-a612-5150882632e9/cancel?$version=2022-03-01-preview2>
Risposta di esempio di una richiesta di annullamento riuscita:
{
"$schema": "https://schema.mp.microsoft.com/schema/configure-status/2022-03-01-preview2",
"jobID": "d4261631-c583-4949-a612-5150882632e9",
"jobStatus": "completed",
"jobResult": "cancelled",
"jobStart": "2022-03-01-T13:32:43.123456Z",
"jobEnd": "2022-03-01T17:34:21.5225132Z",
"errors": []
}
Risposta di esempio nel caso in cui l'annullamento non sia consentito: HTTP Status code: 400
Contenuto:
{
"error": {
"code": "badRequest",
"message": "Cannot cancel job, job has already completed.",
"details": []
}
}
Importante
Tenere presente che l'annullamento si applica solo alle risorse che non sono ancora state elaborate. Alcune risorse potrebbero aver già completato l'elaborazione e rifletteranno gli aggiornamenti di configurazione più recenti, nonostante l'annullamento della richiesta.
È possibile recuperare il riepilogo della richiesta di configurazione dopo l'annullamento per verificare quali risorse (se presenti) sono già state elaborate prima dell'annullamento.
Sincronizza destinatari privati
Per un prodotto live, gli aggiornamenti ai destinatari privati nella bozza, nell'anteprima e negli ambienti live possono essere eseguiti contemporaneamente senza richiedere una pubblicazione. È possibile sincronizzare il gruppo di destinatari privato usando la risorsa "price-and-availability-update-private-audiences" specificando i gruppi di destinatari da aggiungere o rimuovere da un piano specifico. Verrà sincronizzata la bozza, l'anteprima e gli ambienti live in modo che abbiano gli stessi valori del gruppo di destinatari privati. Non è necessario fornire la risorsa di invio durante la sincronizzazione del gruppo di destinatari privato.
Per modificare i destinatari della bozza, usare la risorsa "price-and-availability-plan" e la proprietà "privateAudiences". Sarà necessario eseguire il normale flusso di pubblicazione per impostare i valori in anteprima e in tempo reale.
Importante
I tipi di destinatari supportati sono "subscription", "ea", "msdn" e "tenant", ma il supporto per questi tipi varia in base al tipo di prodotto. Se il prodotto supporta più tipi di identificatore per configurare il gruppo di destinatari privato (ad esempio, ID tenant e ID sottoscrizione), è necessario eseguire una pubblicazione completa se si specifica un nuovo tipo di identificatore per la prima volta. In questo caso non è possibile sincronizzare il gruppo di destinatari privato.
Richiesta di esempio per sincronizzare la configurazione del gruppo di destinatari privato:
POST https://graph.microsoft.com/rp/product-ingestion/configure?$version=2022-03-01-preview2
{
"$schema": "https://schema.mp.microsoft.com/schema/configure/2022-03-01-preview2"
"resources": [
{
"$schema": "https://schema.mp.microsoft.com/schema/price-and-availability-update-private-audiences/2022-03-01-preview2",
"product": "product/12345678-abcd-efgh-1234-12345678901", // product durable ID
"plan": "plan/12345678-abcd-efgh-1234-12345678901/7e70b11f-809e-4c45-ae2f-1fb3ceaca33b", //plan durable ID
"privateAudiences":
{
"add ":
[
{
"type": "tenant",
"id": "4c2bdcdc-f10e-468d-8a2a-0832e089215b",
"label": "test 1"
}
],
"remove ":
[
{
"type": "subscription",
"id": "412c45bf-c99a-4e96-b683-77b0aa2dd09e",
"label": "test 2"
}
]
}
}
]
}
Configurazione della gestione dei lead
Connettere il sistema CRM (Customer Relationship Management) al prodotto del marketplace commerciale in modo da poter ricevere le informazioni di contatto dei clienti quando un cliente esprime interesse o distribuisce il prodotto. È possibile modificare questa connessione in qualsiasi momento durante o dopo la creazione del prodotto. Per altre informazioni, vedere Ottenere i lead dei clienti.
Richiesta di esempio per configurare la gestione dei lead:
POST https://graph.microsoft.com/rp/product-ingestion/configure?$version=2022-03-01-preview2
{
"$schema": "https://schema.mp.microsoft.com/schema/configure/2022-03-01-preview2"
"resources": [
{
"$schema": "https://schema.mp.microsoft.com/schema/customer-leads/2022-03-01-preview3",
"id": "customer-leads/a0c6484f-b4fb-4129-ac6b-35f2b5628089",
"product": "product/a0c6484f-b4fb-4129-ac6b-35f2b5628089",
"leadDestination": "httpsEndpoint",
"httpsEndpointLeadConfiguration": {
"httpsEndpointUrl": "https://www.your-crm.com/triggers/invoke"
}
}
]
}
Stati del ciclo di vita delle risorse
Esistono diverse azioni che è possibile eseguire per eseguire il mapping allo stato del ciclo di vita di una risorsa. Non tutte le risorse hanno uno stato del ciclo di vita e non tutti gli stati del ciclo di vita sono supportati da tutte le risorse. Per verificare se una risorsa ha uno stato del ciclo di vita e quali valori sono supportati, è possibile controllare lo schema della risorsa per l'esistenza della proprietà "lifecycleState". Di seguito sono descritti in dettaglio vari stati del ciclo di vita supportati.
Eliminati
È possibile eliminare risorse specifiche aggiornando la proprietà "lifecycleState" a "deleted". È possibile eliminare solo le risorse bozza che non sono state pubblicate in precedenza. Non è possibile annullare questa azione.
Richiesta di esempio:
Nell'esempio seguente viene eliminato il piano di bozza "basic".
POST https://graph.microsoft.com/rp/product-ingestion/configure?$version=2022-03-01-preview2
{
"$schema": "https://schema.mp.microsoft.com/schema/configure/2022-03-01-preview2"
"resources": [
{
"$schema": "https://schema.mp.microsoft.com/schema/plan/2022-03-01-preview2",
"id": "plan/9f8af57f-ab07-461b-8404-50e10e5e80fb/7e70b11f-809e-4c45-ae2f-1fb3ceaca33b",
"product": "product/9f8af57f-ab07-461b-8404-50e10e5e80fb",
"identity": { "externalID": "basic" },
"alias": "basic plan"
"lifecycleState": "deleted"
}
]
}
Deprecato
La deprecazione rimuove la risorsa dal marketplace commerciale. Per deprecare, impostare la proprietà "lifecycleState" su "deprecata" nelle risorse che lo supportano. Esistono vari livelli di deprecazione. Tutti i tipi di prodotto supportano la deprecazione dell'intero prodotto e dei singoli piani al suo interno. Per ripristinare in un secondo momento una risorsa deprecata, fare riferimento allo stato del ciclo di vita "generalmenteAvailable".
Richiesta di esempio di deprecazione di un prodotto:
Nell'esempio seguente, l'invio live del prodotto è impostato su deprecato. Dopo l'applicazione di questa modifica, viene pubblicata automaticamente in tempo reale per rendere effettiva la modifica.
POST https://graph.microsoft.com/rp/product-ingestion/configure?$version=2022-03-01-preview2
{
"$schema": "https://schema.mp.microsoft.com/schema/configure/2022-03-01-preview2"
"resources": [
{
"$schema": "https://schema.mp.microsoft.com/schema/submission/2022-03-01-preview2 ",
"id": "submission/9f8af57f-ab07-461b-8404-50e10e5e80fb/1152921515689848683",
"product": "product/9f8af57f-ab07-461b-8404-50e10e5e80fb",
"target": {
"targetType": "live"
},
"lifecycleState": "deprecated"
}
]
}
Quando i piani sono deprecati, la proprietà "lifecycleState" deve essere modificata in "deprecata" e le modifiche devono quindi essere pubblicate in "anteprima" e quindi "live" per rendere effettiva la deprecazione. Questa operazione è diversa da una deprecazione a livello di prodotto in cui la deprecazione verrà configurata automaticamente nell'ambiente attivo.
Richiesta di esempio di deprecazione di un piano:
Nell'esempio seguente un piano all'interno di un prodotto SaaS è impostato su deprecato. Tenere presente che per applicare questa modifica, è possibile pubblicare in un secondo momento usando la risorsa di invio.
POST https://graph.microsoft.com/rp/product-ingestion/configure?$version=2022-03-01-preview2
{
"$schema": "https://schema.mp.microsoft.com/schema/configure/2022-03-01-preview2"
"resources": [
{
"$schema": "https://schema.mp.microsoft.com/schema/plan/2022-03-01-preview2 ",
"id": "plan/9f8af57f-ab07-461b-8404-50e10e5e80fb/7e70b11f-809e-4c45-ae2f-1fb3ceaca33b",
"product": "product/9f8af57f-ab07-461b-8404-50e10e5e80fb",
"identity": { "externalID": "basic" },
"alias": "basic plan"
"lifecycleState": "deprecated"
}
]
}
Esistono altre forme di deprecazione che variano a seconda del tipo di prodotto. Altre informazioni sulla deprecazione di SaaS, macchine virtuali e contenitori.
Generalmente disponibile
generallyAvailable è lo stato predefinito del ciclo di vita per tutte le risorse. Dopo aver deprecato una risorsa, è possibile ripristinarla modificando la proprietà "lifecycleState" su "generalmenteAvailable". Per ripristinare un prodotto deprecato, è necessario pubblicare il prodotto in anteprima e quindi in tempo reale. È possibile trovare esempi per SaaS, macchine virtuali e contenitori nei rispettivi articoli.
Richiesta di esempio di ripristino del piano:
Nell'esempio seguente un piano deve essere ripristinato. Per applicare questa modifica, in un secondo momento è necessario pubblicare tutto il modo in cui vivere usando la risorsa di invio.
POST https://graph.microsoft.com/rp/product-ingestion/configure?$version=2022-03-01-preview2
{
"$schema": "https://schema.mp.microsoft.com/schema/configure/2022-03-01-preview2"
"resources": [
{
"$schema": "https://schema.mp.microsoft.com/schema/plan/2022-03-01-preview2",
"id": "plan/9f8af57f-ab07-461b-8404-50e10e5e80fb/7e70b11f-809e-4c45-ae2f-1fb3ceaca33b",
"product": "product/9f8af57f-ab07-461b-8404-50e10e5e80fb",
"identity": { "externalID": "basic" },
"alias": "basic plan"
"lifecycleState": "generallyAvailable"
}
]
}
Informazioni di riferimento sulle API delle risorse
Le versioni dello schema seguenti sono applicabili solo per l'anteprima e cambieranno quando l'API diventa disponibile a livello generale.
Nota
È possibile visualizzare le risorse disponibili esistenti e le relative versioni qui: resources-index
| Tipo di risorsa | Descrizione | Schema |
|---|---|---|
| commercial-marketplace-setup | Descrive la configurazione transazionabile dei prodotti nel marketplace commerciale. | https://schema.mp.microsoft.com/schema/commercial-marketplace-setup/2022-03-01-preview2 |
| clienti potenziali | Consente di connettersi a un sistema CRM per ricevere lead dei clienti. | https://schema.mp.microsoft.com/schema/customer-leads/2022-03-01-preview3 |
| elencazione | Sono incluse le descrizioni del prodotto, che verranno visualizzate nelle vetrine del marketplace commerciale Microsoft. | https://schema.mp.microsoft.com/schema/listing/2022-03-01-preview5 |
| listato-asset | Screenshot e asset di marketing collegati alla risorsa di presentazione. | https://schema.mp.microsoft.com/schema/listing-asset/2022-03-01-preview5 |
| list-trailer | Asset video collegati alla risorsa di presentazione. | https://schema.mp.microsoft.com/schema/listing-trailer/2022-03-01-preview5 |
| microsoft365-integration | Abilitazione e selezione del tipo di Microsoft 365. | https://schema.mp.microsoft.com/schema/microsoft365-integration/2022-03-01-preview2 |
| piano | Per creare piani, a cui si farà riferimento dalle risorse a livello di piano configurate, ad esempio l'elenco di piani. | https://schema.mp.microsoft.com/schema/plan/2022-03-01-preview2 |
| plan-listing | Definire il nome e la descrizione del piano come si vuole che vengano visualizzati nel marketplace commerciale. | https://schema.mp.microsoft.com/schema/plan-listing/2022-03-01-preview5 |
| price-and-availability-custom-meter | Definire i contatori personalizzati condivisi tra i piani. | https://schema.mp.microsoft.com/schema/price-and-availability-custom-meter/2022-03-01-preview3 |
| price-and-availability-offer | Definire un gruppo di destinatari limitato che può esaminare il prodotto prima di pubblicarlo in tempo reale. | https://schema.mp.microsoft.com/schema/price-and-availability-offer/2022-03-01-preview3 |
| piano di prezzo e disponibilità | Configurare i mercati in cui è disponibile questo piano, il modello di monetizzazione desiderato, il prezzo e le condizioni di fatturazione. | https://schema.mp.microsoft.com/schema/price-and-availability-plan/2022-03-01-preview4 |
| price-and-availability-update-private-audiences | Gli aggiornamenti ai destinatari privati nella bozza, nell'anteprima e negli ambienti live possono essere eseguiti contemporaneamente senza richiedere una pubblicazione. | https://schema.mp.microsoft.com/schema/price-and-availability-update-private-audiences/2022-03-01-preview3 |
| private-and-availability-private-offer-plan | Usato per configurare i dettagli assoluti dei prezzi di un prodotto/piano usato all'interno di un'offerta privata | https://schema.mp.microsoft.com/schema/price-and-availability-private-offer-plan/2022-07-01 |
| offerta privata | Definisce il nome e il tipo di offerta privata, con i termini e i dettagli dell'offerta, insieme ai prodotti/piani inclusi e ai relativi prezzi | https://schema.mp.microsoft.com/schema/private-offer/2022-07-01 |
| product | Si tratta della risorsa principale, definisce il nome e il tipo del prodotto, tutte le risorse fanno riferimento a questo. | https://schema.mp.microsoft.com/schema/product/2022-03-01-preview3 |
| property | Definire le categorie e i settori applicabili all'offerta, alla versione dell'app e ai contratti legali. | https://schema.mp.microsoft.com/schema/property/2022-03-01-preview5 |
| Rivenditore | Configurare i partner nel programma Cloud Solution Providers (CSP) a cui si vuole rendere disponibile il prodotto. | https://schema.mp.microsoft.com/schema/reseller/2022-03-01-preview2 |
| albero delle risorse | Descrive il prodotto un elenco di risorse per il prodotto nello stato corrente per l'ambiente di destinazione specificato. | https://schema.mp.microsoft.com/schema/resource-tree/2022-03-01-preview2 |
| software-as-a-service-technical-configuration | Dettagli tecnici che consentono al marketplace commerciale Microsoft di connettersi alla soluzione. | https://schema.mp.microsoft.com/schema/software-as-a-service-technical-configuration/2022-03-01-preview3 |
| invio | Può essere usato per attivare azioni diverse sul prodotto e indicare lo stato di pubblicazione degli ambienti indifferenti del prodotto (bozza, anteprima e live). | https://schema.mp.microsoft.com/schema/submission/2022-03-01-preview2 |
| virtual-machine-plan-technical-configuration | Dettagli tecnici che descrivono la macchina virtuale e la posizione dell'immagine. | https://schema.mp.microsoft.com/schema/virtual-machine-plan-technical-configuration/2022-03-01-preview3 |
| container-plan-technical-configuration | Dettagli tecnici che descrivono le proprietà dell'immagine del contenitore. | https://schema.mp.microsoft.com/schema/container-plan-technical-configuration/2022-03-01-preview3 |
Indicazioni sulle API per tipo di prodotto
L'API di inserimento prodotti verrà resa disponibile per altri tipi di prodotto in futuro. Man mano che sono supportati più tipi di prodotto, verranno rese disponibili altre indicazioni specifiche per ogni tipo di prodotto.
| Tipo di prodotto | Risorse specifiche del tipo di prodotto |
|---|---|
| Offerte private | Creare e gestire offerte private tramite l'API di inserimento di prodotti |
| SaaS | Creare e gestire offerte SaaS tramite l'API di inserimento di prodotti |
| Macchine virtuali | Creare e gestire offerte di macchine virtuali tramite l'API di inserimento di prodotti |
| Contenitori | Creare e gestire offerte di contenitori tramite l'API di inserimento di prodotti |
Versioni e aggiornamenti delle API
| Aggiornamento | Cosa è cambiato? |
|---|---|
| 11-2023 | Tutti gli endpoint dello schema sono stati aggiornati da product-ingestion.azureedge.net a schema.mp.microsoft.com |
| 12-2022 | È ora disponibile una nuova versione dello schema 2022-03-01-preview3 dell'API di inserimento PC per i clienti potenziali che accetta clientID e clientSecret durante la configurazione dei lead dei clienti e interrompe l'acquisizione del serverID e dei campi di posta elettronica di contatto. Passare alla nuova versione e specificare clientID e clientSecret per continuare a configurare il connettore Marketo per le offerte del marketplace. Nuovo URL dello schema: https://``schema.mp.microsoft.com``/schema/customer-leads/2022-03-01-preview3 |
| 09-2022 | Il supporto dell'anteprima dei contenitori viene rilasciato come versione 2022-03-01-preview4 |
| 08-2022 | Il supporto dell'anteprima del software come servizio viene rilasciato come versione 2022-03-01-preview3 |
| 08-2022 | Versione pubblica dell'offerta privata come versione 2022-07-01 |
| 05-2022 | Il supporto dell'anteprima della macchina virtuale viene rilasciato come versione 2022-03-01-preview2 |