Freigeben über


Programmgesteuertes Zugriffsparadigma für den kommerziellen Marketplace

Dieses Diagramm zeigt das API-Aufrufmuster, das zum Erstellen einer neuen Berichtsvorlage, zum Planen des benutzerdefinierten Berichts und zum Abrufen von Fehlerdaten verwendet wird.

Veranschaulicht 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.

  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.
  2. Bei Erfolg gibt die API zum Erstellen von Berichtsvorlagen die QueryId.
  3. 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.
  4. Bei Erfolg gibt die API zum Erstellen eines Berichts die ReportID.
  5. Die Clientanwendung wird über den Rückruf-URI benachrichtigt, sobald die Berichtsdaten zum Download bereit sind.
  6. Die Clientanwendung verwendet dann die API zum Abrufen von Berichtsausführungen , um den Status des Berichts mit dem Report ID Datumsbereich und abzufragen.
  7. 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, RecurrenceCountund 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 truefestgelegt 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 truefestgelegt 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=truefestgelegt. 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=Pendingabgerufen 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, Pausedund 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, Pausedund 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.