Paradigm för programmatisk åtkomst inom kommersiell marknadsplats

Artikel
03/09/2025

Det här diagrammet visar API-anropsmönstret som används för att skapa en ny rapportmall, schemalägga den anpassade rapporten och hämta feldata.

bild 1: Flöde på hög nivå för API-anropsmönstret

Den här listan innehåller mer information om bild 1.

Klientprogrammet kan definiera det anpassade rapportschemat/mallen genom att anropa Create Report Query API. Alternativt kan du använda en rapportmall (QueryId) från lista över systemfrågor.
När det lyckas returnerar API:et Skapa rapportmall QueryId.
Klientprogrammet anropar sedan Skapa rapport-API med hjälp av QueryID tillsammans med rapportens startdatum, Upprepa intervall, Upprepning och en valfri återanrops-URI.
När Skapa rapport-API:et lyckas returnerarReportID.
Klientprogrammet meddelas vid återanrops-URI:n så snart rapportdata är redo för nedladdning.
Klientprogrammet använder sedan Hämta rapportkörningar-API:et för att fråga om rapportens status med Report ID och datumintervallet.
När rapporten har slutförts returneras nedladdningslänken och programmet kan initiera nedladdningen av data.

Specifikation för rapportfrågespråk

Vi tillhandahåller systemfrågor du kan använda för att skapa rapporter, men du kan också skapa egna frågor baserat på dina affärsbehov. Mer information om anpassade frågor finns i Anpassad frågespecifikation.

Skapa rapportfråge-API

Det här API:et hjälper dig att skapa anpassade frågor som definierar den datauppsättning från vilken kolumner och mått måste exporteras. API:et ger flexibiliteten att skapa en ny rapporteringsmall baserat på dina affärsbehov.

Du kan också använda de systemfrågor vi tillhandahåller. När anpassade rapportmallar inte behövs kan du anropa Skapa rapport-API:et direkt med hjälp av QueryIds av de systemfrågor som vi tillhandahåller.

I följande exempel visas hur du skapar en anpassad fråga för att få Normaliserad användning och Beräknade ekonomiska avgifter för BETALDA SKU:er från datasetet ISVUsage för den senaste månaden.

Begärandesyntax

Metod	Begäran URI
POST	`https://api.partnercenter.microsoft.com/insights/v1.1/cmp/ScheduledQueries`

Begärandehuvud

Rubrik	Typ	Beskrivning
Tillstånd	sträng	Krävs. Microsoft Entra-åtkomsttoken. Formatet är `Bearer <token>`.
Innehållstyp	`string`	`application/JSON`

Sökvägsparameter

Ingen

Frågeparameter

Ingen

Exempel på nyttolastbegäran

{
    "Name": "ISVUsageQuery",
    "Description": "Normalized Usage and Estimated Financial Charges for PAID SKUs",
    "Query": "SELECT UsageDate, NormalizedUsage, EstimatedExtendedChargePC FROM ISVUsage WHERE SKUBillingType = 'Paid' ORDER BY UsageDate DESC TIMESPAN LAST_MONTH"
}

ordlista

Den här tabellen innehåller viktiga definitioner av element i begärandenyttolasten.

Parameter	Krävs	Beskrivning	Tillåtna värden
`Name`	Ja	Användarvänligt namn på frågan	sträng
`Description`	Nej	Beskrivning av den skapade frågan	sträng
`Query`	Ja	Frågesträng baserat på affärsbehov	sträng

Anteckning

Exempel på anpassade frågor finns i exempelfrågor.

Exempelsvar

Svarsnyttolasten är strukturerad på följande sätt:

Svarskoder: 200, 400, 401, 403, 500

Exempel på svarspayload:

{
  "value": [
        {
            "queryId": "78be43f2-e35f-491a-8cd5-78fe14194f9c",
            "name": " ISVUsageQuery",
            "description": "Normalized Usage and Estimated Financial Charges for PAID SKUs",
            "query": " SELECT UsageDate, NormalizedUsage, EstimatedExtendedChargePC FROM ISVUsage WHERE SKUBillingType = 'Paid' ORDER BY UsageDate DESC TIMESPAN LAST_MONTH",
            "type": "userDefined",
            "user": "142344300",
            "createdTime": "2024-01-06T05:38:34Z"
        }
    ],
    "totalCount": 1,
    "message": "Query created successfully",
    "statusCode": 200
}

ordlista

Den här tabellen innehåller viktiga definitioner av element i svaret.

Parameter	Beskrivning
`QueryId`	Universellt unik identifierare (UUID) för den skapade frågan
`Name`	Namn som angavs i nyttolasten för begäran när frågan skapades
`Description`	Beskrivning som anges i nyttolasten för begäran när frågan skapas
`Query`	Anpassad rapportfråga som tillhandahålls i nyttolasten för begäran när frågan skapas
`Type`	Ange till `userDefined` för manuellt skapade frågor
`User`	Användar-ID som används för att skapa frågan
`CreatedTime`	UTC-tid när frågan skapades. Format: åååå-MM-ddTHH:mm:ssZ
`TotalCount`	Antal poster i matrisen Värde
`StatusCode`	Resultatkod Möjliga värden är 200, 400, 401, 403, 500
`message`	Statusmeddelande från körningen av API:et

Skapa rapport-API

När du framgångsrikt skapar en anpassad rapportmall och tar emot QueryID som en del av svaret på Skapa rapportförfrågan kan detta API anropas för att schemalägga en förfrågan att köras regelbundet. Du kan ange en frekvens och ett schema för att rapporten ska levereras. För systemfrågor som vi tillhandahåller kan du även anropa Create Report API med QueryId.

Begärandesyntax

Metod	URI för förfrågan
Post	`https://api.partnercenter.microsoft.com/insights/v1.1/cmp/ScheduledReport`

Begärandehuvud

Rubrik	Typ	Beskrivning
Tillstånd	sträng	Krävs. Microsoft Entra-åtkomsttoken. Formatet är `Bearer <token>`.
Innehållstyp	sträng	`application/JSON`

Sökvägsparameter

Ingen

Frågeparameter

Ingen

Exempel på nyttolastbegäran

{
  "ReportName": "ISVUsageReport",
  "Description": "Normalized Usage and Estimated Financial Charges for PAID SKUs",
  "QueryId": "78be43f2-e35f-491a-8cd5-78fe14194f9c ",
  "StartTime": "2021-01-06T19:00:00Z ",
  "executeNow": false,
  "RecurrenceInterval": 48,
  "RecurrenceCount": 20,
  "Format": "csv",
  "CallbackUrl": "https://<SampleCallbackUrl>"
  "callbackMethod": "GET",
}

Ordlista

Den här tabellen innehåller viktiga definitioner av element i begärandenyttolasten.

Parameter	Krävs	Beskrivning	Tillåtna värden
`ReportName`	Ja	Användarvänligt namn som tilldelats rapporten	Sträng
`Description`	Nej	Beskrivning av den skapade rapporten	Sträng
`QueryId`	Ja	Fråge-ID som måste användas för rapportgenerering	Sträng
`StartTime`	Ja	UTC-tidsstämpel där rapportgenereringen börjar. Formatet ska vara åååå-MM-ddTHH:mm:ssZ	Sträng
`ExecuteNow`	Nej	Den här parametern ska användas för att skapa en rapport som bara körs en gång. `StartTime`, `RecurrenceInterval`, `RecurrenceCount`och `EndTime` ignoreras om detta är inställt på `true`	Boolesk
`QueryStartTime`	Nej	Du kan också ange starttiden för frågan som extraherar data. Den här parametern gäller endast för en enskild körningsrapport som har `ExecuteNow` inställd på `true`. Formatet ska vara åååå-MM-ddTHH:mm:ssZ	Tidsstämpel som sträng
`QueryEndTime`	Nej	Du kan också ange sluttiden för frågan som extraherar data. Den här parametern gäller endast för en körningsrapport för engångsbruk som har `ExecuteNow` inställd på `true`. Formatet ska vara åååå-MM-ddTHH:mm:ssZ	Tidsstämpel som sträng
`RecurrenceInterval`	Ja	Frekvens i timmar då rapporten ska genereras. Minimivärdet är 1 och maxvärdet är 17520	Heltal
`RecurrenceCount`	Ja	Antal rapporter som ska genereras. Gränsen är beroende av upprepningsintervall	Heltal
`Format`	Nej	Filformat för den exporterade filen. Standardformatet är CSV	CSV/TSV
`CallbackUrl`	Nej	Offentligt tillgänglig URL som kan konfigureras som återanropsmål	Sträng
`CallbackMethod`	Nej	Get/Post-metod som kan konfigureras med callback-URL	GET/POST
`EndTime`	Ja	UTC-tidsstämpel där rapportgenereringen avslutas. Formatet ska vara åååå-MM-ddTHH:mm:ssZ	Sträng

Not

När du skapar rapporten är antingen EndTime eller en kombination av RecurrenceInterval och RecurrenceCount obligatorisk.

Exempelsvar

Svarsnyttolasten är strukturerad på följande sätt:

Svarskod: 200, 400, 401, 403, 404, 500

Svarsnyttolast:

{
  "Value": [
    {
            "reportId": "72fa95ab-35f5-4d44-a1ee-503abbc88003",
            "reportName": "ISVUsageReport",
            "description": "Normalized Usage and Estimated Financial Charges for PAID SKUs",
            "queryId": "78be43f2-e35f-491a-8cd5-78fe14194f9c",
            "query": "SELECT UsageDate, NormalizedUsage, EstimatedExtendedChargePC FROM ISVUsage WHERE SKUBillingType = 'Paid' ORDER BY UsageDate DESC TIMESPAN LAST_MONTH",
            "user": "142344300",
            "createdTime": "2024-01-06T05:46:00Z",
            "modifiedTime": null,
            "startTime": "2024-01-06T19:00:00Z",
            "reportStatus": "Active",
            "recurrenceInterval": 48,
            "recurrenceCount": 20,
            "callbackUrl": "https://<SampleCallbackUrl>",
            "callbackMethod": "GET",
            "format": "csv"
    }
  ],
  "TotalCount": 1,
  "Message": "Report created successfully",
  "StatusCode": 200
}

ordlista

Den här tabellen innehåller viktiga definitioner av element i svaret.

Parameter	Beskrivning
`ReportId`	Universellt unik identifierare (UUID) för den rapport som du skapade
`ReportName`	Namn som angavs i nyttolasten för begäran när rapporten skapades
`Description`	Beskrivning som anges i nyttolasten för begäran när rapporten skapas
`QueryId`	Fråge-ID som anges i nyttolasten för begäran när rapporten skapas
`Query`	Frågetext som ska köras för den här rapporten
`User`	Användar-ID som används för att skapa rapporten
`CreatedTime`	UTC Tid då rapporten skapades i det här formatet: åååå-MM-ddTHH:mm:ssZ
`ModifiedTime`	UTC Tid då rapporten senast ändrades i det här formatet: åååå-MM-ddTHH:mm:ssZ
`ExecuteNow`	ExecuteNow-parametern som anges i nyttolasten för begäran när rapporten skapas
`queryStartTime`	Frågestarttid som anges i nyttolasten för begäran när rapporten skapas. Detta gäller endast om `ExecuteNow` är inställt på "True"
`queryEndTime`	Frågesluttid som anges i nyttolasten för begäran när rapporten skapas. Detta gäller endast om `ExecuteNow` är inställt på "True"
`StartTime`	Starttid angiven i begärans innehåll vid rapportskapande
`ReportStatus`	Status för rapportkörningen. Möjliga värden är Pausade, Aktivaoch Inaktiva.
`RecurrenceInterval`	Upprepningsintervall som anges i nyttolasten för begäran när rapporten skapas
`RecurrenceCount`	Återstående antal upprepningar för rapporten
`CallbackUrl`	Motringnings-URL som anges i nyttolasten för begäran när rapporten skapas
`CallbackMethod`	Motringningsmetod som tillhandahålls i nyttolasten för begäran när rapporten skapas
`Format`	Format för rapportfilerna som angavs i nyttolasten för begäran när rapporten skapades
`EndTime`	Sluttid som anges i begärans nyttolast när rapporten skapas. Detta gäller endast om `ExecuteNow` är inställt på "True"
`TotalRecurrenceCount`	`RecurrenceCount` som anges i nyttolasten för begäran när rapporten skapas
`nextExecutionStartTime`	UTC-tidsstämpel när nästa rapportkörning startar
`TotalCount`	Antal poster i värdearrayen
`StatusCode`	Resultatkod. Möjliga värden är 200, 400, 401, 403, 500
`message`	Statusmeddelande från körningen av API:et

Hämta rapportkörnings-API

Du kan använda den här metoden för att fråga om statusen för en rapportexekvering med hjälp av ReportId som tagits emot från Create Report API. Metoden returnerar länken för rapportnedladdning om rapporten är redo för nedladdning. Annars returnerar metoden statusen. Du kan också använda det här API:et för att hämta alla körningar som har inträffat för en viss rapport.

Viktig

Det här API:t har standardfrågeparametrar för executionStatus=Completed och getLatestExecution=true. Därför, om API:et anropas före den första lyckade körningen av rapporten, kommer det att returnera 404. Väntande utföranden kan erhållas genom att ställa in executionStatus=Pending.

Begärandesyntax

Metod	Begär URI
Få	`https://api.partnercenter.microsoft.com/insights/v1.1/cmp/ScheduledReport/execution/{reportId}?executionId={executionId}&executionStatus={executionStatus}&getLatestExecution={getLatestExecution}`

Begärandehuvud

Rubrik	Typ	Beskrivning
Tillstånd	sträng	Krävs. Microsoft Entra-åtkomsttoken. Formatet är `Bearer <token>`.
Innehållstyp	sträng	`application/json`

Sökvägsparameter

Ingen

Frågeparameter

Parameternamn	Krävs	Typ	Beskrivning
`reportId`	Ja	sträng	Filtrera för att hämta körningsinformation för endast rapporter med `reportId` som anges i det här argumentet.
`executionId`	Nej	sträng	Filtrera för att få information om endast rapporter med `executionId` som anges i det här argumentet. Flera `executionIds` kan anges genom att avgränsa dem med semikolonet ";".
`executionStatus`	Nej	sträng/enum	Filtrera för att få information om endast rapporter med `executionStatus` som anges i det här argumentet. Giltiga värden är: `Pending`, `Running`, `Paused`och `Completed` Standardvärdet är `Completed`.
`getLatestExecution`	Nej	boolesk	API:et returnerar information om den senaste rapportkörningen. Som standard är den här parametern inställd på `true`. Om du väljer att skicka värdet för den här parametern som `false`returnerar API:et de senaste 90 dagarnas körningsinstanser.

Begär nyttolast

Ingen

Exempelsvar

Svarsnyttolasten är strukturerad på följande sätt:

Svarskoder: 200, 400, 401, 403, 404, 500

Exempel på svarspayload:

{
    "value": [
        {
            "executionId": "a0bd78ad-1a05-40fa-8847-8968b718d00f",
            "reportId": "72fa95ab-35f5-4d44-a1ee-503abbc88003",
            "recurrenceInterval": 4,
            "recurrenceCount": 10,
            "callbackUrl": null,
            "format": "csv",
            "executionStatus": "Completed",
            "reportAccessSecureLink": "https://<path to report for download>",
            "reportExpiryTime": null,
            "reportGeneratedTime": "2021-01-13T14:40:46Z"
        }
    ],
    "totalCount": 1,
    "message": null,
    "statusCode": 200
}

När rapportkörningen är klar visas körningsstatusen Completed. Du kan ladda ned rapporten genom att välja URL:en i reportAccessSecureLink.

ordlista

Viktiga definitioner av element i svaret.

Parameter	Beskrivning
`ExecutionId`	Universellt unik identifiering (UUID) för körningsinstansen
`ReportId`	Rapport-ID som är kopplat till körningsinstansen
`RecurrenceInterval`	Upprepningsintervall som anges när rapporten skapas
`RecurrenceCount`	Antal återkommande som angavs när rapporten skapades
`CallbackUrl`	Återanrops-URL som är associerad med körningsinstansen
`CallbackMethod`	Motringningsmetod som tillhandahålls i nyttolasten för begäran när rapporten skapas
`Format`	Format för den genererade filen i slutet av körningen
`ExecutionStatus`	Status för rapportkörningsinstansen. Giltiga värden är: `Pending`, `Running`, `Paused`och `Completed`
`ReportLocation`	Plats där rapporten laddas ned.
`ReportAccessSecureLink`	Länk genom vilken rapporten kan nås på ett säkert sätt
`ReportExpiryTime`	UTC Tid efter vilken rapportlänken upphör att gälla i det här formatet: åååå-MM-ddTHH:mm:ssZ
`ReportGeneratedTime`	UTC-tid då rapporten genererades i det här formatet: åååå-MM-ddTHH:mm:ssZ
`EndTime`	Sluttid anges i begärans nyttolast när rapporten skapas. Detta gäller endast om `ExecuteNow` är inställt på "True"
`TotalRecurrenceCount`	`RecurrenceCount` anges i begärans nyttolast när rapporten skapas
`nextExecutionStartTime`	UTC-tidsstämpel när nästa rapportutförande startar
`TotalCount`	Antal datauppsättningar i matrisen Värde
`StatusCode`	Resultatkod Möjliga värden är 200, 400, 401, 403, 404 och 500
`message`	Statusmeddelande från körningen av API:et

Du kan prova API:erna via Swagger API-URL:en.

Gör ditt första API-anrop för Marketplace Insights-rapporter

Dela via

Paradigm för programmatisk åtkomst inom kommersiell marknadsplats

Specifikation för rapportfrågespråk

Skapa rapportfråge-API

Skapa rapport-API

Hämta rapportkörnings-API

Feedback

Ytterligare resurser

Dela via

Paradigm för programmatisk åtkomst inom kommersiell marknadsplats

Specifikation för rapportfrågespråk

Skapa rapportfråge-API

Skapa rapport-API

Hämta rapportkörnings-API

Relaterat innehåll

Feedback

Ytterligare resurser