Programmeringsparadigm för kommersiell marknadsplats

Artikel
06/14/2024

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å i API-anropsmönstret

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

Klientprogrammet kan definiera det anpassade rapportschemat/mallen genom att anropa API:et Skapa rapportfråga. Alternativt kan du använda en rapportmall (QueryId) från listan över systemfrågor.
När det lyckas returnerar API:et QueryIdSkapa rapportmall .
Klientprogrammet anropar sedan API:et QueryID Skapa rapport med hjälp av startdatumet för rapporten, Upprepa intervall, Upprepning och en valfri återanrops-URI.
Vid lyckat resultat returnerar API:et ReportIDSkapa rapport .
Klientprogrammet meddelas vid återanrops-URI:n så snart rapportdata är redo för nedladdning.
Klientprogrammet använder sedan API:et Hämta rapportkörningar för att fråga efter rapportens status med datumintervallet Report ID och .
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 som 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 som vi tillhandahåller. När anpassade rapportmallar inte behövs kan du anropa API:et Skapa rapport direkt med hjälp av QueryIds för de systemfrågor som vi tillhandahåller.

I följande exempel visas hur du skapar en anpassad fråga för att hämta normaliserad användning och uppskattade ekonomiska avgifter för BETALDA SKU:er från ISVUsage-datauppsättningen för den senaste månaden.

Syntax för begäran

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

Begärandehuvud

Header	Typ	Beskrivning
Auktorisering	sträng	Obligatoriskt. Microsoft Entra-åtkomsttoken. Formatet är `Bearer <token>`.
Innehållstyp	`string`	`application/JSON`

Sökvägsparameter

Ingen

Frågeparameter

Ingen

Exempel på begärandenyttolast

{
    "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	Obligatoriskt	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

Kommentar

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å svarsnyttolast:

{
  "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	Description
`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 skapar en anpassad rapportmall och tar emot QueryID som en del av svaret på Skapa rapportfråga kan det här API:et anropas för att schemalägga en fråga som ska köras med jämna mellanrum. 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 API:et Skapa rapport med QueryId.

Syntax för begäran

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

Begärandehuvud

Header	Typ	Beskrivning
Auktorisering	sträng	Obligatoriskt. Microsoft Entra-åtkomsttoken. Formatet är `Bearer <token>`.
Innehållstyp	sträng	`application/JSON`

Sökvägsparameter

Ingen

Frågeparameter

Ingen

Exempel på begärandenyttolast

{
  "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	Obligatoriskt	Beskrivning	Tillåtna värden
`ReportName`	Ja	Användarvänligt namn som tilldelats rapporten	String
`Description`	Nej	Beskrivning av den skapade rapporten	String
`QueryId`	Ja	Fråge-ID som måste användas för rapportgenerering	String
`StartTime`	Ja	UTC-tidsstämpel där rapportgenereringen börjar. Formatet ska vara åååå-MM-ddTHH:mm:ssZ	String
`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`	Booleskt
`QueryStartTime`	Nej	Du kan också ange starttiden för frågan som extraherar data. Den här parametern gäller endast för en gångs körningsrapport som har `ExecuteNow` angetts till `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 gångs körningsrapport som har `ExecuteNow` angetts till `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	Integer
`RecurrenceCount`	Ja	Antal rapporter som ska genereras. Gränsen är beroende av upprepningsintervall	Integer
`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	String
`CallbackMethod`	Nej	Get/Post-metod som kan konfigureras med motringnings-URL	GET/POST
`EndTime`	Ja	UTC-tidsstämpel där rapportgenereringen avslutas. Formatet ska vara åååå-MM-ddTHH:mm:ssZ	String

Kommentar

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	Description
`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 som anges i nyttolasten för begäran när rapporten skapas
`ReportStatus`	Status för rapportkörningen. Möjliga värden är Pausade, Aktiva och 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 nyttolasten för begäran 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 matrisen Värde
`StatusCode`	Resultatkod. Möjliga värden är 200, 400, 401, 403, 500
`message`	Statusmeddelande från körningen av API:et

Hämta API för rapportkörningar

Du kan använda den här metoden för att fråga efter status för en rapportkörning med hjälp av mottaget ReportId från API:et Skapa rapport. 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.

Viktigt!

Det här API:et har standardfrågeparametrar inställda för executionStatus=Completed och getLatestExecution=true. Därför returneras 404 genom att anropa API:et före den första lyckade körningen av rapporten. Väntande körningar kan hämtas genom att ange executionStatus=Pending.

Syntax för begäran

Metod	URI för förfrågan
Hämta	`https://api.partnercenter.microsoft.com/insights/v1.1/cmp/ScheduledReport/execution/{reportId}?executionId={executionId}&executionStatus={executionStatus}&getLatestExecution={getLatestExecution}`

Begärandehuvud

Header	Typ	Beskrivning
Auktorisering	sträng	Obligatoriskt. Microsoft Entra-åtkomsttoken. Formatet är `Bearer <token>`.
Innehållstyp	sträng	`application/json`

Sökvägsparameter

Ingen

Frågeparameter

Parameternamn	Obligatoriskt	Type	Beskrivning
`reportId`	Ja	sträng	Filtrera för att hämta körningsinformation för endast rapporter med `reportId` angivet i det här argumentet.
`executionId`	Nej	sträng	Filtrera för att få information om endast rapporter med `executionId` angivet i det här argumentet. Flera `executionIds` kan anges genom att avgränsa dem med semikolonet ";".
`executionStatus`	Nej	sträng/uppräkning	Filtrera för att få information om endast rapporter med `executionStatus` angivet i det här argumentet. Giltiga värden är: `Pending`, `Running`, `Paused`och `Completed` Standardvärdet är `Completed`.
`getLatestExecution`	Nej	boolean	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å svarsnyttolast:

{
    "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	Description
`ExecutionId`	Universellt unik identifierare (UUID) för körningsinstansen
`ReportId`	Rapport-ID som är associerat med 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 som anges i nyttolasten för begäran 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 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

Programmeringsparadigm för kommersiell marknadsplats

Specifikation för rapportfrågespråk

Skapa rapportfråge-API

Skapa rapport-API

Hämta API för rapportkörningar

Feedback

Ytterligare resurser

Dela via

Programmeringsparadigm för kommersiell marknadsplats

Specifikation för rapportfrågespråk

Skapa rapportfråge-API

Skapa rapport-API

Hämta API för rapportkörningar

Relaterat innehåll

Feedback

Ytterligare resurser