Programmatisch toegangsparadigma - Apps en Games-API

Artikel
06/14/2024

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.

Aanvraagsyntaxis

Wijze	Aanvraag-URI
POSTEN	`https://manage.devcenter.microsoft.com/consumer/insights/v1.1/ScheduledQueries`

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

{
    "Name": "PurchaseQuery",
    "Description": "Fetch Purchase related dataset",
    "Query": "SELECT TitleId, ProductId, XboxProductId, ProductTypeName, TitleName, CatalogId, SandboxId, SkuId, SkuTypeName, SkuDisplayName, AvailabilityId, RegionName, CountryName, Market, PaymentType, StoreClientName, StoreClientCategory, ParentProductName, ParentProductId, XboxParentProductId, AcquisitionType, PurchaseTaxType, LocalCurrencyCode, SupportedPlatform, Age, Gender, OsVersion, DeviceType, PurchasePriceUSDAmount, PurchaseTaxUSDAmount, PurchasePriceLocalAmount, PurchaseTaxLocalAmount FROM Acquisitions WHERE ProductId IN ('all') TIMESPAN LAST_30_DAYS AGGREGATED Daily"
}

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 bedrijfsbehoeften	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": " PurchaseQuery ",
            "description": " Fetch Purchase related dataset",
            "query": "SELECT TitleId, ProductId, XboxProductId, ProductTypeName, TitleName, CatalogId, SandboxId, SkuId, SkuTypeName, SkuDisplayName, AvailabilityId, RegionName, CountryName, Market, PaymentType, StoreClientName, StoreClientCategory, ParentProductName, ParentProductId, XboxParentProductId, AcquisitionType, PurchaseTaxType, LocalCurrencyCode, SupportedPlatform, Age, Gender, OsVersion, DeviceType, PurchasePriceUSDAmount, PurchaseTaxUSDAmount, PurchasePriceLocalAmount, PurchaseTaxLocalAmount FROM Acquisitions WHERE ProductId IN ('all') TIMESPAN LAST_30_DAYS AGGREGATED Daily",
            "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://manage.devcenter.microsoft.com/consumer/insights/v1.1/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

{ 
    "Name": "PurchaseQuery", 
    "Description": "Fetch Purchase related dataset", 
    "Query": "SELECT TitleId, ProductId, XboxProductId, ProductTypeName, TitleName, CatalogId, SandboxId, SkuId, SkuTypeName, SkuDisplayName, AvailabilityId, RegionName, CountryName, Market, PaymentType, StoreClientName, StoreClientCategory, ParentProductName, ParentProductId, XboxParentProductId, AcquisitionType, PurchaseTaxType, LocalCurrencyCode, SupportedPlatform, Age, Gender, OsVersion, DeviceType, PurchasePriceUSDAmount, PurchaseTaxUSDAmount, PurchasePriceLocalAmount, PurchaseTaxLocalAmount FROM Acquisitions WHERE ProductId IN ('all') TIMESPAN LAST_30_DAYS AGGREGATED Daily" 
}

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. `StartTime`, `RecurrenceInterval`, `RecurrenceCount`en `EndTime` worden genegeerd wanneer deze 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 één keer 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": " PurchaseQuery ", 
            "description": " Fetch Purchase related dataset" 
            "queryId": "78be43f2-e35f-491a-8cd5-78fe14194f9c", 
            "query": "SELECT TitleId, ProductId, XboxProductId, ProductTypeName, TitleName, CatalogId, SandboxId, SkuId, SkuTypeName, SkuDisplayName, AvailabilityId, RegionName, CountryName, Market, PaymentType, StoreClientName, StoreClientCategory, ParentProductName, ParentProductId, XboxParentProductId, AcquisitionType, PurchaseTaxType, LocalCurrencyCode, SupportedPlatform, Age, Gender, OsVersion, DeviceType, PurchasePriceUSDAmount, PurchaseTaxUSDAmount, PurchasePriceLocalAmount, PurchaseTaxLocalAmount FROM Acquisitions WHERE ProductId IN ('all') TIMESPAN LAST_30_DAYS AGGREGATED Daily", 
            "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
Beschrijving	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 `True`
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 `True`
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
Notatie	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 `True`
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
bericht	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://manage.devcenter.microsoft.com/consumer/insights/v1.1/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.
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 `CompletedFailed`. 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 weergegeven als Completed. 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 `FailedCompleted`
`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 `True`
`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

Delen via

Programmatisch toegangsparadigma - Apps en Games-API

Specificatie van rapportquerytaal

Rapportquery-API maken

Aanvraagsyntaxis

Aanvraagheader

Padparameter

Queryparameter

Voorbeeld van nettolading aanvragen

Woordenlijst

Voorbeeldrespons

Woordenlijst

Rapport-API maken

Aanvraagsyntaxis

Aanvraagheader

Padparameter

Queryparameter

Voorbeeld van nettolading aanvragen

Woordenlijst

Voorbeeldrespons

Nettolading van antwoord

Woordenlijst

API voor rapportuitvoeringen ophalen

Aanvraagsyntaxis

Aanvraagheader

Padparameter

Queryparameter

Nettolading aanvragen

Voorbeeldrespons

Voorbeeld van nettolading van antwoord

Woordenlijst

Feedback

Aanvullende resources