Programmatisch toegangsparadigma voor commerciële marketplace

Artikel
10/20/2023

In dit diagram ziet u het API-aanroeppatroon dat wordt gebruikt om een nieuwe rapportsjabloon te maken, het aangepaste rapport te plannen en foutgegevens op te halen.

Afbeelding 1: Stroom op hoog niveau van het API-aanroeppatroon

Deze lijst bevat meer informatie over afbeelding 1.

De clienttoepassing kan het aangepaste rapportschema/de sjabloon definiëren door de API Rapportquery maken aan te roepen. U kunt ook een rapportsjabloon (QueryId) gebruiken in de lijst met systeemquery's.
Bij succes retourneert de API Rapportsjabloon maken de QueryId.
De clienttoepassing roept vervolgens de Rapport-API maken aan met behulp van de QueryID begindatum van het rapport, herhalingsinterval, terugkeerpatroon en een optionele callback-URI.
Bij succes retourneert de RAPPORT-API maken de ReportID.
De clienttoepassing wordt op de callback-URI op de hoogte gesteld zodra de rapportgegevens gereed zijn voor download.
De clienttoepassing gebruikt vervolgens de API Rapportuitvoeringen ophalen om een query uit te voeren op de status van het rapport met het Report ID datumbereik.
Bij succes wordt de downloadkoppeling voor het rapport geretourneerd en kan de toepassing het downloaden van de gegevens initiëren.

Specificatie van rapportquerytaal

Hoewel we systeemquery's bieden die u kunt gebruiken om rapporten te maken, kunt u ook uw eigen query's maken op basis van uw bedrijfsbehoeften. Zie Aangepaste queryspecificatie voor meer informatie over aangepaste query's.

Rapportquery-API maken

Deze API helpt bij het maken van aangepaste query's waarmee de gegevensset wordt gedefinieerd waaruit kolommen en metrische gegevens moeten worden geëxporteerd. De API biedt de flexibiliteit om een nieuwe rapportagesjabloon te maken op basis van uw bedrijfsbehoeften.

U kunt ook de systeemquery's gebruiken die we bieden. Wanneer aangepaste rapportsjablonen niet nodig zijn, kunt u de Rapport-API maken rechtstreeks aanroepen met behulp van de QueryIds van de systeemquery's die we bieden.

In het volgende voorbeeld ziet u hoe u een aangepaste query maakt om genormaliseerd gebruik en geschatte financiële kosten voor BETAALDE SKU's op te halen uit de gegevensset ISVUsage voor de afgelopen maand.

Aanvraagsyntaxis

Methode	Aanvraag-URI
POSTEN	`https://api.partnercenter.microsoft.com/insights/v1/cmp/ScheduledQueries`

Aanvraagheader

Koptekst	Type	Description
Autorisatie	tekenreeks	Vereist. Het Microsoft Entra-toegangstoken. De indeling is `Bearer <token>`.
Inhoudstype	`string`	`application/JSON`

Padparameter

Geen

Queryparameter

Geen

Voorbeeld van nettolading aanvragen

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

Woordenlijst

Deze tabel bevat de belangrijkste definities van elementen in de nettolading van de aanvraag.

Parameter	Vereist	Beschrijving	Toegestane waarden
`Name`	Ja	Beschrijvende naam van de query	tekenreeks
`Description`	Nee	Beschrijving van wat de query retourneert	tekenreeks
`Query`	Ja	Rapportquerytekenreeks	Gegevenstype: tekenreeks Aangepaste query op basis van bedrijfsbehoefte

Notitie

Zie Voorbeelden van voorbeeldquery's voor aangepaste query's.

Voorbeeldrespons

De nettolading van het antwoord is als volgt gestructureerd:

Antwoordcodes: 200, 400, 401, 403, 500

Voorbeeld van nettolading van antwoord:

{
  "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": "2021-01-06T05:38:34Z"
        }
    ],
    "totalCount": 1,
    "message": "Query created successfully",
    "statusCode": 200
}

Woordenlijst

Deze tabel bevat de belangrijkste definities van elementen in het antwoord.

Parameter	Description
`QueryId`	Universally Unique Identifier (UUID) van de query die u hebt gemaakt
`Name`	Beschrijvende naam gegeven aan de query in de nettolading van de aanvraag
`Description`	Beschrijving gegeven tijdens het maken van de query
`Query`	Rapportquery is doorgegeven als invoer tijdens het maken van de query
`Type`	Ingesteld op `userDefined`
`User`	Gebruikers-id die wordt gebruikt om de query te maken
`CreatedTime`	UTC-tijd dat de query is gemaakt in deze indeling: jjjj-MM-ddTHH:mm:ssZ
`TotalCount`	Aantal gegevenssets in de waardematrix
`StatusCode`	Resultaatcode De mogelijke waarden zijn 200, 400, 401, 403, 500
`message`	Statusbericht van de uitvoering van de API

Rapport-API maken

Bij het maken van een aangepaste rapportsjabloon en het ontvangen van het antwoord als onderdeel van het QueryID antwoord Rapportquery maken, kan deze API worden aangeroepen om een query te plannen die regelmatig moet worden uitgevoerd. U kunt een frequentie en planning instellen voor het rapport dat moet worden geleverd. Voor systeemquery's die we bieden, kan de Rapport-API ook worden aangeroepen met QueryId.

Aanvraagsyntaxis

Methode	Aanvraag-URI
POSTEN	`https://api.partnercenter.microsoft.com/insights/v1/cmp/ScheduledReport`

Aanvraagheader

Koptekst	Type	Description
Autorisatie	tekenreeks	Vereist. Het Microsoft Entra-toegangstoken. De indeling is `Bearer <token>`.
Type inhoud	tekenreeks	`application/JSON`

Padparameter

Geen

Queryparameter

Geen

Voorbeeld van nettolading aanvragen

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

Woordenlijst

Deze tabel bevat de belangrijkste definities van elementen in de nettolading van de aanvraag.

Parameter	Vereist	Beschrijving	Toegestane waarden
`ReportName`	Ja	Naam toegewezen aan het rapport	tekenreeks
`Description`	Nee	Beschrijving van het gemaakte rapport	tekenreeks
`QueryId`	Ja	Rapportquery-id	tekenreeks
`StartTime`	Ja	UTC-tijdstempel waarop het genereren van het rapport begint. De notatie moet zijn: jjjj-MM-ddTHH:mm:ssZ	tekenreeks
`RecurrenceInterval`	Ja	Frequentie in uren waarop het rapport moet worden gegenereerd. De minimumwaarde is 4 en de maximumwaarde is 2160.	geheel getal
`RecurrenceCount`	Nee	Het aantal rapporten dat moet worden gegenereerd.	geheel getal
`Format`	Nee	Bestandsindeling van het geëxporteerde bestand. Standaardindeling is . CSV.	CSV/TSV
`CallbackUrl`	Nee	Openbaar toegankelijke URL die optioneel kan worden geconfigureerd als de callback-bestemming.	Tekenreeks (http-URL)
`ExecuteNow`	Nee	Deze parameter moet worden gebruikt om een rapport te maken dat slechts eenmaal wordt uitgevoerd. `StartTime`, `RecurrenceInterval`en `RecurrenceCount` worden genegeerd als dit is ingesteld op `true`. Het rapport wordt onmiddellijk op asynchrone wijze uitgevoerd.	waar/onwaar
`QueryStartTime`	Nee	Hiermee geeft u desgewenst de begintijd op voor de query waarmee de gegevens worden geëxtraheerd. Deze parameter is slechts van toepassing voor eenmalig uitvoeringsrapport dat is `ExecuteNow` ingesteld op `true`. De notatie moet jjjj-MM-ddTHH:mm:ssZ zijn	Tijdstempel als tekenreeks
`QueryEndTime`	Nee	Hiermee geeft u desgewenst de eindtijd op voor de query waarmee de gegevens worden geëxtraheerd. Deze parameter is slechts van toepassing voor eenmalig uitvoeringsrapport dat is `ExecuteNow` ingesteld op `true`. De notatie moet jjjj-MM-ddTHH:mm:ssZ zijn	Tijdstempel als tekenreeks

Voorbeeldrespons

De nettolading van het antwoord is als volgt gestructureerd:

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

Nettolading van antwoord:

{
  "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": "2021-01-06T05:46:00Z",
            "modifiedTime": null,
            "startTime": "2021-01-06T19:00:00Z",
            "reportStatus": "Active",
            "recurrenceInterval": 48,
            "recurrenceCount": 20,
            "callbackUrl": "https://<SampleCallbackUrl>",
            "format": "csv"    
    }
  ],
  "TotalCount": 1,
  "Message": "Report created successfully",
  "StatusCode": 200
}

Woordenlijst

Deze tabel bevat de belangrijkste definities van elementen in het antwoord.

Parameter	Description
`ReportId`	Universally Unique Identifier (UUID) van het rapport dat u hebt gemaakt
`ReportName`	Naam gegeven aan het rapport in de nettolading van de aanvraag
`Description`	Beschrijving gegeven tijdens het maken van het rapport
`QueryId`	De query-id is doorgegeven op het moment dat u het rapport hebt gemaakt
`Query`	Querytekst die wordt uitgevoerd voor dit rapport
`User`	Gebruikers-id die wordt gebruikt om het rapport te maken
`CreatedTime`	UTC-tijd waarop het rapport is gemaakt in deze indeling: jjjj-MM-ddTHH:mm:ssZ
`ModifiedTime`	UTC-tijd waarop het rapport voor het laatst is gewijzigd in deze indeling: jjjj-MM-ddTHH:mm:ssZ
`StartTime`	UTC-tijd dat de uitvoering van het rapport begint in deze indeling: jjjj-MM-ddTHH:mm:ssZ
`ReportStatus`	Status van de uitvoering van het rapport. De mogelijke waarden zijn onderbroken, actief en inactief.
`RecurrenceInterval`	Herhalingsinterval dat is opgegeven tijdens het maken van het rapport
`RecurrenceCount`	Aantal terugkeerpatronen dat is opgegeven tijdens het maken van het rapport
`CallbackUrl`	Callback-URL die is opgegeven in de aanvraag
`Format`	Indeling van de rapportbestanden. De mogelijke waarden zijn CSV of TSV.
`TotalCount`	Aantal gegevenssets in de waardematrix
`StatusCode`	Resultaatcode De mogelijke waarden zijn 200, 400, 401, 403, 500
`message`	Statusbericht van de uitvoering van de API

API voor rapportuitvoeringen ophalen

U kunt deze methode gebruiken om een query uit te voeren op de status van een rapportuitvoering met behulp van de ReportId ontvangen van de Rapport-API maken. De methode retourneert de downloadkoppeling voor rapporten als het rapport gereed is voor downloaden. Anders retourneert de methode de status. U kunt deze API ook gebruiken om alle uitvoeringen op te halen die zijn uitgevoerd voor een bepaald rapport.

Belangrijk

Deze API heeft standaardqueryparameters ingesteld voor executionStatus=Completed en getLatestExecution=true. Daarom retourneert het aanroepen van de API voordat de eerste geslaagde uitvoering van het rapport 404 retourneert. Uitvoeringen die in behandeling zijn, kunnen worden verkregen door de instelling in te stellen executionStatus=Pending.

Aanvraagsyntaxis

Methode	Aanvraag-URI
Ophalen	`https://api.partnercenter.microsoft.com/insights/v1/cmp/ScheduledReport/execution/{reportId}?executionId={executionId}&executionStatus={executionStatus}&getLatestExecution={getLatestExecution}`

Aanvraagheader

Koptekst	Type	Description
Autorisatie	tekenreeks	Vereist. Het Microsoft Entra-toegangstoken. De indeling is `Bearer <token>`.
Content type	tekenreeks	`application/json`

Padparameter

Geen

Queryparameter

Parameternaam	Vereist	Type	Description
`reportId`	Ja	tekenreeks	Filter om uitvoeringsdetails op te halen van alleen rapporten die `reportId` in dit argument zijn opgegeven. Meerdere `reportIds` kunnen worden opgegeven door ze te scheiden met een puntkomma ';'.
`executionId`	Nee	tekenreeks	Filter om alleen details op te halen van rapporten die `executionId` in dit argument zijn opgegeven. Meerdere `executionIds` kunnen worden opgegeven door ze te scheiden met een puntkomma ';'.
`executionStatus`	Nee	tekenreeks/opsomming	Filter om alleen details op te halen van rapporten die `executionStatus` in dit argument zijn opgegeven. Geldige waarden zijn: `Pending`, `Running`, `Paused`en `Completed` De standaardwaarde is `Completed`. U kunt meerdere statussen opgeven door ze te scheiden met een puntkomma ';'.
`getLatestExecution`	Nee	boolean	De API retourneert details van de meest recente rapportuitvoering. Deze parameter is standaard ingesteld op `true`. Als u ervoor kiest om de waarde van deze parameter door te geven als `false`, retourneert de API de laatste 90 dagen uitvoeringsexemplaren.

Nettolading aanvragen

Geen

Voorbeeldrespons

De nettolading van het antwoord is als volgt gestructureerd:

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

Voorbeeld van nettolading van antwoord:

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

Zodra de uitvoering van het rapport is voltooid, wordt de uitvoeringsstatus Completed weergegeven. U kunt het rapport downloaden door de URL in de reportAccessSecureLinkurl te selecteren.

Woordenlijst

Sleuteldefinities van elementen in het antwoord.

Parameter	Description
`ExecutionId`	Universally Unique Identifier (UUID) van het uitvoeringsexemplaren
`ReportId`	Rapport-id die is gekoppeld aan het uitvoeringsexemplaar
`RecurrenceInterval`	Herhalingsinterval dat is opgegeven tijdens het maken van het rapport
`RecurrenceCount`	Aantal terugkeerpatronen dat is opgegeven tijdens het maken van het rapport
`CallbackUrl`	Callback-URL die is gekoppeld aan het uitvoeringsexemplaar
`Format`	Indeling van het gegenereerde bestand aan het einde van de uitvoering
`ExecutionStatus`	Status van het uitvoeringsexemplaren van het rapport. Geldige waarden zijn: `Pending`, `Running`, `Paused`en `Completed`
`ReportAccessSecureLink`	Een koppeling maken waarmee het rapport veilig kan worden geopend
`ReportExpiryTime`	UTC-tijd waarna de rapportkoppeling in deze indeling verloopt: jjjj-MM-ddTHH:mm:ssZ
`ReportGeneratedTime`	UTC-tijd waarop het rapport is gegenereerd in deze indeling: jjjj-MM-ddTHH:mm:ssZ
`TotalCount`	Aantal gegevenssets in de waardematrix
`StatusCode`	Resultaatcode De mogelijke waarden zijn 200, 400, 401, 403, 404 en 500
`message`	Statusbericht van de uitvoering van de API

Volgende stappen

U kunt de API's uitproberen via de URL van de Swagger-API
Aan de slag met programmatische toegang tot analysegegevens

Programmatisch toegangsparadigma voor commerciële marketplace

Specificatie van rapportquerytaal

Rapportquery-API maken

Rapport-API maken

API voor rapportuitvoeringen ophalen

Volgende stappen

Aanvullende resources

Aanvullende resources