Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
Dieses Diagramm zeigt das API-Aufrufmuster, das zum Erstellen einer neuen Berichtsvorlage, zum Planen des benutzerdefinierten Berichts und zum Abrufen von Fehlerdaten verwendet wird.
Abbildung 1: Ablauf des API-Aufrufmusters auf hoher Ebene
Diese Liste enthält weitere Details zu Abbildung 1.
- Die Clientanwendung kann das benutzerdefinierte Berichtsschema/die benutzerdefinierte Berichtsvorlage definieren, indem sie die API zum Erstellen einer Berichtsabfrage aufruft. Alternativ können Sie eine Berichtsvorlage (
QueryId
) aus der Liste der Systemabfragen verwenden. - Bei Erfolg gibt die API zum Erstellen von Berichtsvorlagen die
QueryId
. - Die Clientanwendung ruft dann die API zum Erstellen eines Berichts zusammen
QueryID
mit dem Startdatum des Berichts, dem Wiederholungsintervall, der Wiederholung und einem optionalen Rückruf-URI auf. - Bei Erfolg gibt die API zum Erstellen eines Berichts die
ReportID
. - Die Clientanwendung wird über den Rückruf-URI benachrichtigt, sobald die Berichtsdaten zum Download bereit sind.
- Die Clientanwendung verwendet dann die API zum Abrufen von Berichtsausführungen , um den Status des Berichts mit dem
Report ID
Datumsbereich und abzufragen. - Bei Erfolg wird der Link zum Herunterladen des Berichts zurückgegeben, und die Anwendung kann den Download der Daten initiieren.
Spezifikation der Abfragesprache für Berichte
Wir bieten zwar Systemabfragen , mit denen Sie Berichte erstellen können, aber Sie können auch Ihre eigenen Abfragen erstellen, die auf Ihren Geschäftsanforderungen basieren. Weitere Informationen zu benutzerdefinierten Abfragen finden Sie unter Spezifikation benutzerdefinierter Abfragen.
Erstellen einer Berichtsabfrage-API
Mit dieser API können Sie benutzerdefinierte Abfragen erstellen, die das Dataset definieren, aus dem Spalten und Metriken exportiert werden müssen. Die API bietet die Flexibilität, eine neue Berichtsvorlage basierend auf Ihren Geschäftsanforderungen zu erstellen.
Sie können auch die von uns bereitgestellten Systemabfragen verwenden. Wenn benutzerdefinierte Berichtsvorlagen nicht benötigt werden, können Sie die API zum Erstellen von Berichten direkt aufrufen, indem Sie die QueryIds der von uns bereitgestellten Systemabfragen verwenden.
Das folgende Beispiel zeigt, wie Sie eine benutzerdefinierte Abfrage erstellen, um die normalisierte Nutzung und die geschätzten finanziellen Gebühren für PAID-SKUs aus dem ISVUsage-Dataset für den letzten Monat abzurufen.
Syntax der Anforderung
Methode | Anforderungs-URI |
---|---|
SENDEN | https://api.partnercenter.microsoft.com/insights/v1.1/cmp/ScheduledQueries |
Anforderungsheader
Kopfzeile | Typ | BESCHREIBUNG |
---|---|---|
Autorisierung | Schnur | Erforderlich. Das Microsoft Entra Zugriffstoken. Das Format ist Bearer <token> . |
Inhaltstyp | string |
application/JSON |
Pfadparameter
Nichts
Abfrageparameter
Nichts
Beispiel für eine Anforderungsnutzlast
{
"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"
}
Glossar
Diese Tabelle enthält die wichtigsten Definitionen der Elemente in der Anforderungsnutzlast.
Parameter | Erforderlich | BESCHREIBUNG | Zulässige Werte |
---|---|---|---|
Name |
Ja | Benutzerfreundlicher Name der Abfrage | Schnur |
Description |
Nein | Beschreibung der erstellten Abfrage | Schnur |
Query |
Ja | Abfragezeichenfolge basierend auf der Geschäftsanforderung | Schnur |
Hinweis
Beispiele für benutzerdefinierte Abfragen finden Sie unter Beispielabfragen.
Beispiel für eine Antwort
Die Antwortnutzlast ist wie folgt strukturiert:
Antwort-Codes: 200, 400, 401, 403, 500
Beispiel für Antwortnutzdaten:
{
"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
}
Glossar
Diese Tabelle enthält die wichtigsten Definitionen der Elemente in der Antwort.
Parameter | BESCHREIBUNG |
---|---|
QueryId |
Universally Unique Identifier (UUID) der erstellten Abfrage |
Name |
Name, der während der Abfrageerstellung in der Anforderungsnutzlast angegeben wird |
Description |
Beschreibung, die in der Anforderungsnutzlast während der Abfrageerstellung bereitgestellt wird |
Query |
Benutzerdefinierte Berichtsabfrage, die während der Abfrageerstellung in der Anforderungsnutzlast bereitgestellt wird |
Type |
Für manuell erstellte Abfragen auf userDefined festlegen |
User |
Benutzer-ID, die zum Erstellen der Abfrage verwendet wird |
CreatedTime |
UTC Zeitpunkt, zu dem die Abfrage erstellt wurde. Format: yyyy-MM-ddTHH:mm:ssZ |
TotalCount |
Anzahl der Datensätze im Value-Array |
StatusCode |
Ergebniscode Die möglichen Werte sind 200, 400, 401, 403, 500 |
message |
Statusmeldung aus der Ausführung der API |
Erstellen einer Berichts-API
Wenn Sie erfolgreich eine benutzerdefinierte Berichtsvorlage erstellt haben und die QueryID
Antwort als Teil der Antwort zum Erstellen einer Berichtsabfrage erhalten, kann diese API aufgerufen werden, um die Ausführung einer Abfrage in regelmäßigen Abständen zu planen. Sie können eine Häufigkeit und einen Zeitplan für die Übermittlung des Berichts festlegen. Für Systemabfragen, die wir bereitstellen, kann die Create Report API auch mit QueryId aufgerufen werden.
Syntax der Anforderung
Methode | Anforderungs-URI |
---|---|
SENDEN | https://api.partnercenter.microsoft.com/insights/v1.1/cmp/ScheduledReport |
Anforderungsheader
Kopfzeile | Typ | BESCHREIBUNG |
---|---|---|
Autorisierung | Schnur | Erforderlich. Das Microsoft Entra Zugriffstoken. Das Format ist Bearer <token> . |
Inhaltstyp | Schnur | application/JSON |
Pfadparameter
Nichts
Abfrageparameter
Nichts
Beispiel für eine Anforderungsnutzlast
{
"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",
}
Glossar
Diese Tabelle enthält die wichtigsten Definitionen der Elemente in der Anforderungsnutzlast.
Parameter | Erforderlich | BESCHREIBUNG | Zulässige Werte |
---|---|---|---|
ReportName |
Ja | Benutzerfreundlicher Name, der dem Bericht zugewiesen wird | Schnur |
Description |
Nein | Beschreibung des erstellten Berichts | Schnur |
QueryId |
Ja | Abfrage-ID, die für die Berichterstellung verwendet werden muss | Schnur |
StartTime |
Ja | UTC Zeitstempel, bei dem die Berichterstellung beginnt. Das Format sollte yyyy-MM-ddTHH:mm:ssZ sein. | Schnur |
ExecuteNow |
Nein | Dieser Parameter sollte verwendet werden, um einen Bericht zu erstellen, der nur einmal ausgeführt wird.
StartTime , RecurrenceInterval , RecurrenceCount und EndTime werden ignoriert, wenn dies auf true |
Boolescher Typ (Boolean) |
QueryStartTime |
Nein | Gibt optional die Startzeit für die Abfrage an, die die Daten extrahiert. Dieser Parameter gilt nur für einen Bericht zur einmaligen Ausführung, der auf true festgelegt istExecuteNow . Das Format sollte yyyy-MM-ddTHH:mm:ssZ sein. |
Zeitstempel als String |
QueryEndTime |
Nein | Gibt optional die Endzeit für die Abfrage an, die die Daten extrahiert. Dieser Parameter gilt nur für einen Bericht zur einmaligen Ausführung, der auf true festgelegt istExecuteNow . Das Format sollte yyyy-MM-ddTHH:mm:ssZ sein. |
Zeitstempel als String |
RecurrenceInterval |
Ja | Häufigkeit in Stunden, mit der der Bericht erstellt werden soll. Der Minimalwert ist 1 und der Maximalwert ist 17520 | Ganze Zahl |
RecurrenceCount |
Ja | Anzahl der zu generierenden Berichte. Der Grenzwert hängt vom Wiederholungsintervall ab | Ganze Zahl |
Format |
Nein | Dateiformat der exportierten Datei. Das Standardformat ist CSV | CSV/TSV |
CallbackUrl |
Nein | Öffentlich zugängliche URL, die optional als Callback-Ziel konfiguriert werden kann | Schnur |
CallbackMethod |
Nein | Get/Post-Methode, die mit der Callback-URL konfiguriert werden kann | ABRUFEN/POSTEN |
EndTime |
Ja | UTC-Zeitstempel, bei dem die Berichterstellung endet. Das Format sollte yyyy-MM-ddTHH:mm:ssZ sein. | Schnur |
Hinweis
Bei der Erstellung des Berichts ist eine Kombination EndTime
aus RecurrenceInterval
und RecurrenceCount
obligatorisch.
Beispiel für eine Antwort
Die Antwortnutzlast ist wie folgt strukturiert:
Antwortcode: 200, 400, 401, 403, 404, 500
Nutzlast der Antwort:
{
"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
}
Glossar
Diese Tabelle enthält die wichtigsten Definitionen der Elemente in der Antwort.
Parameter | BESCHREIBUNG |
---|---|
ReportId |
UUID (Universally Unique Identifier) des von Ihnen erstellten Berichts |
ReportName |
Name, der während der Berichtserstellung in der Anforderungsnutzlast angegeben wird |
Description |
Beschreibung, die während der Berichtserstellung in der Anforderungsnutzlast bereitgestellt wird |
QueryId |
Abfrage-ID, die während der Berichtserstellung in der Anforderungsnutzlast bereitgestellt wird |
Query |
Abfragetext, der für diesen Bericht ausgeführt wird |
User |
Benutzer-ID zum Erstellen des Berichts |
CreatedTime |
UTC Uhrzeit, zu der der Bericht in diesem Format erstellt wurde: yyyy-MM-ddTHH:mm:ssZ |
ModifiedTime |
UTC Zeitpunkt, zu dem der Bericht zuletzt in diesem Format geändert wurde: yyyy-MM-ddTHH:mm:ssZ |
ExecuteNow |
ExecuteNow-Parameter, der während der Berichtserstellung in der Anforderungsnutzlast bereitgestellt wird |
queryStartTime |
Startzeit der Abfrage, die während der Berichtserstellung in der Anforderungsnutzlast angegeben wird. Dies gilt nur, wenn ExecuteNow es auf "True" festgelegt ist |
queryEndTime |
Endzeit der Abfrage, die während der Berichtserstellung in der Anforderungsnutzlast angegeben wird. Dies gilt nur, wenn ExecuteNow es auf "True" festgelegt ist |
StartTime |
Startzeit, die während der Berichtserstellung in der Anforderungsnutzlast angegeben wird |
ReportStatus |
Status der Berichtsausführung. Die möglichen Werte sind Pausiert, Aktiv und Inaktiv. |
RecurrenceInterval |
Wiederholungsintervall, das während der Berichtserstellung in der Anforderungsnutzlast angegeben wird |
RecurrenceCount |
Verbleibende Wiederholungsanzahl für den Bericht |
CallbackUrl |
Callback-URL, die während der Berichtserstellung in der Anforderungsnutzlast bereitgestellt wird |
CallbackMethod |
Callback-Methode, die während der Berichtserstellung in der Anforderungsnutzlast bereitgestellt wird |
Format |
Format der Berichtsdateien, die während der Berichtserstellung in der Anforderungsnutzlast bereitgestellt werden |
EndTime |
Endzeit, die während der Berichtserstellung in der Anforderungsnutzlast angegeben wird. Dies gilt nur, wenn ExecuteNow es auf "True" festgelegt ist |
TotalRecurrenceCount |
RecurrenceCount die während der Berichtserstellung in der Anforderungsnutzlast bereitgestellt werden |
nextExecutionStartTime |
UTC-Zeitstempel, wann die nächste Berichtsausführung gestartet wird |
TotalCount |
Anzahl der Datensätze im Value-Array |
StatusCode |
Ergebniscode. Die möglichen Werte sind 200, 400, 401, 403, 500 |
message |
Statusmeldung aus der Ausführung der API |
Abrufen der API für Berichtsausführungen
Sie können diese Methode verwenden, um den Status einer Berichtsausführung mithilfe der ReportId
von der Berichtserstellungs-API empfangenen abzufragen. Die Methode gibt den Link zum Herunterladen des Berichts zurück, wenn der Bericht zum Download bereit ist. Andernfalls gibt die Methode den Status zurück. Sie können diese API auch verwenden, um alle Ausführungen abzurufen, die für einen bestimmten Bericht stattgefunden haben.
Von Bedeutung
Für diese API sind Standardabfrageparameter für executionStatus=Completed
und getLatestExecution=true
festgelegt. Wenn Sie die API vor der ersten erfolgreichen Ausführung des Berichts aufrufen, wird daher 404 zurückgegeben. Ausstehende Ausführungen können durch Setzen von executionStatus=Pending
abgerufen werden.
Syntax der Anforderung
Methode | Anforderungs-URI |
---|---|
Herunterladen | https://api.partnercenter.microsoft.com/insights/v1.1/cmp/ScheduledReport/execution/{reportId}?executionId={executionId}&executionStatus={executionStatus}&getLatestExecution={getLatestExecution} |
Anforderungsheader
Kopfzeile | Typ | BESCHREIBUNG |
---|---|---|
Autorisierung | Schnur | Erforderlich. Das Microsoft Entra Zugriffstoken. Das Format ist Bearer <token> . |
Inhaltstyp | Schnur | application/json |
Pfadparameter
Nichts
Abfrageparameter
Parametername | Erforderlich | Typ | BESCHREIBUNG |
---|---|---|---|
reportId |
Ja | Schnur | Filtern Sie, um Ausführungsdetails nur von Berichten abzurufen, bei denen reportId in diesem Argument angegeben ist. |
executionId |
Nein | Schnur | Filtern Sie, um nur Details zu Berichten abzurufen, die executionId in diesem Argument angegeben sind. Mehrere executionIds können angegeben werden, indem sie durch ein Semikolon ";" getrennt werden. |
executionStatus |
Nein | Zeichenfolge/Enumeration | Filtern Sie, um nur Details zu Berichten abzurufen, die executionStatus in diesem Argument angegeben sind.Gültige Werte sind: Pending , Running , Paused und Completed Der Standardwert ist Completed . |
getLatestExecution |
Nein | Boolescher Wert | Die API gibt Details zur letzten Berichtsausführung zurück. Dieser Parameter ist standardmäßig auf true festgelegt. Wenn Sie den Wert dieses Parameters als false übergeben, gibt die API die Ausführungsinstanzen der letzten 90 Tage zurück. |
Nutzlast anfordern
Nichts
Beispiel für eine Antwort
Die Antwortnutzlast ist wie folgt strukturiert:
Antwort-Codes: 200, 400, 401, 403, 404, 500
Beispiel für Antwortnutzdaten:
{
"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
}
Sobald die Ausführung des Berichts abgeschlossen ist, wird der Ausführungsstatus Completed
angezeigt. Sie können den Bericht herunterladen, indem Sie die URL in der .reportAccessSecureLink
Glossar
Wichtige Definitionen von Elementen in der Antwort.
Parameter | BESCHREIBUNG |
---|---|
ExecutionId |
Universally Unique Identifier (UUID) der Ausführungsinstanz |
ReportId |
Berichts-ID, die der Ausführungsinstanz zugeordnet ist |
RecurrenceInterval |
Wiederholungsintervall, das während der Berichtserstellung bereitgestellt wird |
RecurrenceCount |
Wiederholungsanzahl, die während der Berichtserstellung bereitgestellt wird |
CallbackUrl |
Callback-URL, die der Ausführungsinstanz zugeordnet ist |
CallbackMethod |
Callback-Methode, die während der Berichtserstellung in der Anforderungsnutzlast bereitgestellt wird |
Format |
Format der generierten Datei am Ende der Ausführung |
ExecutionStatus |
Status der Instanz der Berichtsausführung. Gültige Werte sind: Pending , Running , Paused und Completed |
ReportLocation |
Speicherort, an den der Bericht heruntergeladen wird. |
ReportAccessSecureLink |
Link, über den der Bericht sicher aufgerufen werden kann |
ReportExpiryTime |
UTC Zeit, nach der der Berichtslink in diesem Format abläuft: yyyy-MM-ddTHH:mm:ssZ |
ReportGeneratedTime |
UTC Zeitpunkt, zu dem der Bericht in diesem Format erstellt wurde: yyyy-MM-ddTHH:mm:ssZ |
EndTime |
Endzeit, die während der Berichtserstellung in der Anforderungsnutzlast angegeben wird. Dies gilt nur, wenn ExecuteNow es auf "True" festgelegt ist |
TotalRecurrenceCount |
RecurrenceCount die während der Berichtserstellung in der Anforderungsnutzlast bereitgestellt werden |
nextExecutionStartTime |
UTC-Zeitstempel, wann die nächste Berichtsausführung gestartet wird |
TotalCount |
Anzahl der Datasets im Value-Array |
StatusCode |
Ergebnis-Code Die möglichen Werte sind 200, 400, 401, 403, 404 und 500 |
message |
Statusmeldung aus der Ausführung der API |
Sie können die APIs über die Swagger-API-URLausprobieren.