Programmatisch toegangsparadigma voor commerciële marketplace

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.

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

Specificatie van rapportquery-taal

Hoewel we systeemquery's bieden die u kunt gebruiken om rapporten te maken, kunt u ook uw eigen query's maken afhankelijk van de behoeften van uw bedrijf. Zie Aangepaste queryspecificatievoor 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 wij leveren. Wanneer aangepaste rapportsjablonen niet nodig zijn, kunt u de rapport-creëren API rechtstreeks aanroepen met behulp van de QueryIds van de systeemquery's die wij beschikbaar stellen.

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 ISVUsage gegevensset voor de afgelopen maand.

Syntax van verzoeken

verzoekheader

padparameter

Geen

query-parameter

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.

voorbeeldantwoord

De payload van de respons is als volgt gestructureerd:

Antwoordcodes: 200, 400, 401, 403, 500

Voorbeeld van antwoord-payload:

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

Rapport-API maken

Bij het succesvol maken van een aangepaste rapportsjabloon en het ontvangen van QueryID als onderdeel van het Maak Rapport Query antwoord, kan deze API worden aangeroepen om een query in te plannen die op regelmatige intervallen moet worden uitgevoerd. U kunt een frequentie en planning instellen voor het rapport dat moet worden geleverd. Voor de systeemquery's die we aanbieden, kan de API voor het maken van rapporten ook worden aangeroepen met QueryId.

Verzoeksyntaxis

verzoekheader

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.

voorbeeldantwoord

De reactiepayload 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.

API voor rapportuitvoeringen ophalen

U kunt deze methode gebruiken om de status van een rapport op te vragen met behulp van de ReportId die is ontvangen van de API voor rapport maken . De methode retourneert de downloadkoppeling voor rapporten als het rapport gereed is voor downloaden. In het andere geval geeft de methode de status terug. U kunt deze API ook gebruiken om alle uitvoeringen op te halen die zijn uitgevoerd voor een bepaald rapport.

aanvraagsyntaxis

verzoekkoptekst

padparameter

Geen

Queryparameter

nettolading aanvragen

Geen

voorbeeldantwoord

De responselading is als volgt gestructureerd:

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

Voorbeeld van antwoordpayload:

{
    "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 reportAccessSecureLinkte selecteren.

woordenlijst

Sleuteldefinities van elementen in het antwoord.

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

Verwante inhoud

• Uw eerste API-aanroep maken voor Marketplace Insights-rapporten