Programmatisch toegangsparadigma voor commerciële marketplace

Artikel
06/14/2024

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

Wijze	Aanvraag-URI
POSTEN	`https://api.partnercenter.microsoft.com/insights/v1.1/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	Gebruiksvriendelijke naam van de query	tekenreeks
`Description`	Nee	Beschrijving van de gemaakte query	tekenreeks
`Query`	Ja	Queryreeks op basis van bedrijfsbehoefte	tekenreeks

Notitie

Zie voorbeeldquery's voor aangepaste queryvoorbeelden.

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": "2024-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 gemaakte query
`Name`	Naam opgegeven in de nettolading van de aanvraag tijdens het maken van de query
`Description`	Beschrijving die is opgegeven in de nettolading van de aanvraag tijdens het maken van de query
`Query`	Aangepaste rapportquery die is opgegeven in de nettolading van de aanvraag tijdens het maken van query's
`Type`	Ingesteld op `userDefined` voor handmatig gemaakte query's
`User`	Gebruikers-id die wordt gebruikt om de query te maken
`CreatedTime`	UTC-tijd waarop de query is gemaakt. Indeling: jjjj-MM-ddTHH:mm:ssZ
`TotalCount`	Aantal records in de matrix Waarde
`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

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

Aanvraagheader

Koptekst	Type	Description
Autorisatie	tekenreeks	Vereist. Het Microsoft Entra-toegangstoken. De indeling is `Bearer <token>`.
Inhoudstype	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 ",
  "executeNow": false,
  "RecurrenceInterval": 48,
  "RecurrenceCount": 20,
  "Format": "csv",
  "CallbackUrl": "https://<SampleCallbackUrl>"
  "callbackMethod": "GET",
}

Woordenlijst

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

Parameter	Vereist	Beschrijving	Toegestane waarden
`ReportName`	Ja	Gebruiksvriendelijke naam die is toegewezen aan het rapport	String
`Description`	Nee	Beschrijving van het gemaakte rapport	String
`QueryId`	Ja	Query-id die moet worden gebruikt voor het genereren van rapporten	String
`StartTime`	Ja	UTC-tijdstempel waarop het genereren van het rapport begint. De notatie moet jjjj-MM-ddTHH:mm:ssZ zijn	String
`ExecuteNow`	Nee	Deze parameter moet worden gebruikt om een rapport te maken dat slechts eenmaal wordt uitgevoerd. `StartTimeRecurrenceCount`, `RecurrenceInterval`en `EndTime` worden genegeerd als dit is ingesteld op`true`	Booleaans
`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
`RecurrenceInterval`	Ja	Frequentie in uren waarop het rapport moet worden gegenereerd. De minimumwaarde is 1 en de maximumwaarde is 17520	Geheel getal
`RecurrenceCount`	Ja	Het aantal rapporten dat moet worden gegenereerd. Limiet is afhankelijk van het interval voor terugkeerpatroon	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	String
`CallbackMethod`	Nee	Get/Post-methode die kan worden geconfigureerd met callback-URL	GET/POST
`EndTime`	Ja	UTC-tijdstempel waarop het genereren van het rapport wordt beëindigd. De notatie moet jjjj-MM-ddTHH:mm:ssZ zijn	String

Notitie

Tijdens het maken van het rapport, EndTime ofwel een combinatie van RecurrenceInterval en RecurrenceCount is verplicht.

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

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 opgegeven in de nettolading van de aanvraag tijdens het maken van het rapport
`Description`	Beschrijving die is opgegeven in de nettolading van de aanvraag tijdens het maken van het rapport
`QueryId`	Query-id die is opgegeven in de nettolading van de aanvraag tijdens het maken van het rapport
`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
`ExecuteNow`	ExecuteNow-parameter die is opgegeven in de nettolading van de aanvraag tijdens het maken van het rapport
`queryStartTime`	De begintijd van de query die is opgegeven in de nettolading van de aanvraag tijdens het maken van het rapport. Dit is alleen van toepassing als `ExecuteNow` deze is ingesteld op 'Waar'
`queryEndTime`	De eindtijd van de query die is opgegeven in de nettolading van de aanvraag tijdens het maken van het rapport. Dit is alleen van toepassing als `ExecuteNow` deze is ingesteld op 'Waar'
`StartTime`	Begintijd opgegeven in de nettolading van de aanvraag tijdens het maken van het rapport
`ReportStatus`	Status van de uitvoering van het rapport. De mogelijke waarden zijn onderbroken, actief en inactief.
`RecurrenceInterval`	Herhalingsinterval opgegeven in de nettolading van de aanvraag tijdens het maken van het rapport
`RecurrenceCount`	Resterend aantal terugkeerpatronen voor het rapport
`CallbackUrl`	Callback-URL die is opgegeven in de nettolading van de aanvraag tijdens het maken van het rapport
`CallbackMethod`	Callback-methode die is opgegeven in de nettolading van de aanvraag tijdens het maken van het rapport
`Format`	Indeling van de rapportbestanden die zijn opgegeven in de nettolading van de aanvraag tijdens het maken van het rapport
`EndTime`	Eindtijd die is opgegeven in de nettolading van de aanvraag tijdens het maken van het rapport. Dit is alleen van toepassing als `ExecuteNow` deze is ingesteld op 'Waar'
`TotalRecurrenceCount`	`RecurrenceCount` opgegeven in de nettolading van de aanvraag tijdens het maken van het rapport
`nextExecutionStartTime`	UTC-tijdstempel wanneer de volgende rapportuitvoering wordt gestart
`TotalCount`	Aantal records in de matrix Waarde
`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

Wijze	Aanvraag-URI
Ophalen	`https://api.partnercenter.microsoft.com/insights/v1.1/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>`.
Inhoudstype	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.
`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`.
`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
`CallbackMethod`	Callback-methode die is opgegeven in de nettolading van de aanvraag tijdens het maken van het rapport
`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`
`ReportLocation`	Locatie waar het rapport wordt gedownload.
`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
`EndTime`	Eindtijd die is opgegeven in de nettolading van de aanvraag tijdens het maken van het rapport. Dit is alleen van toepassing als `ExecuteNow` deze is ingesteld op 'Waar'
`TotalRecurrenceCount`	`RecurrenceCount` opgegeven in de nettolading van de aanvraag tijdens het maken van het rapport
`nextExecutionStartTime`	UTC-tijdstempel wanneer de volgende rapportuitvoering wordt gestart
`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

U kunt de API's uitproberen via de URL van de Swagger-API.

Uw eerste API-aanroep maken voor Marketplace Insights-rapporten

Delen via

Programmatisch toegangsparadigma voor commerciële marketplace

Specificatie van rapportquerytaal

Rapportquery-API maken

Rapport-API maken

API voor rapportuitvoeringen ophalen

Feedback

Aanvullende resources

Delen via

Programmatisch toegangsparadigma voor commerciële marketplace

Specificatie van rapportquerytaal

Rapportquery-API maken

Rapport-API maken

API voor rapportuitvoeringen ophalen

Gerelateerde inhoud

Feedback

Aanvullende resources