Programmatisches Zugriffsparadigma für den kommerziellen Marktplatz

Artikel
04/19/2024

Dieses Diagramm zeigt das API-Aufrufmuster zum Erstellen neuer Berichtsvorlagen, Planen von benutzerdefinierten Berichten und Abrufen von Fehlerdaten.

Abbildung 1: Allgemeines Ablauf des API-Aufrufmusters

Weitere Details zu Abbildung 1:

Die Clientanwendung kann das benutzerdefinierte Berichtsschema bzw. die benutzerdefinierte Vorlage definieren, indem sie die API zum Erstellen von Berichtsabfragen aufruft. Alternativ können Sie auch eine Berichtsvorlage (QueryId) aus der Liste der Systemabfragen verwenden.
Wenn der Vorgang erfolgreich ist, gibt die API zum Erstellen von Berichtsvorlagen QueryId zurück.
Die Clientanwendung ruft dann die API zum Erstellen von Berichten mithilfe von QueryID zusammen mit dem Startdatum des Berichts, dem Wiederholungsintervall, der Serie und einem optionalen Rückruf-URI auf.
Wenn der Vorgang erfolgreich ist, gibt die API zum Erstellen von BerichtenReportID zurück.
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 der Report ID und dem Datumsbereich abzufragen.
Bei erfolgreicher Ausführung wird der Link zum Herunterladen des Berichts zurückgegeben, und die Anwendung kann den Download der Daten initiieren.

Spezifikation der Berichtsabfragesprache

Wir stellen Ihnen zwar Systemabfragen zur Verfügung, die Sie zum Erstellen von Berichten verwenden können, Sie können aber auch eigene Abfragen basierend auf den Anforderungen Ihres Unternehmens erstellen. Weitere Informationen zu benutzerdefinierten Abfragen finden Sie unter Spezifikation für benutzerdefinierte Abfragen.

Erstellen einer Berichtsabfrage-API

Mithilfe dieser API können Sie benutzerdefinierte Abfragen erstellen, mit denen das Dataset definiert wird, aus dem Spalten und Metriken exportiert werden müssen. Die API bietet die Flexibilität, die für das Erstellen einer neuen Berichtsvorlage notwendig ist, die auf den Anforderungen Ihres Unternehmens basiert.

Sie können ebenfalls die von uns bereitgestellten Systemabfragen verwenden. Wenn benutzerdefinierte Berichtsvorlagen nicht benötigt werden, können Sie die Berichts-API erstellen direkt mithilfe der Abfrage-ID der von uns bereitgestellten Systemabfragen aufrufen.

Im folgenden Beispiel wird gezeigt, wie Sie eine benutzerdefinierte Abfrage erstellen können, um einen normalisierten Verbrauch und Kostenschätzungen für kostenpflichtige SKUs aus dem Dataset ISVUsage für den letzten Monat zu erhalten.

Anforderungssyntax

Methode	Anforderungs-URI
NACHRICHT	`https://api.partnercenter.microsoft.com/insights/v1.1/cmp/ScheduledQueries`

Anforderungsheader

Header	Typ	Beschreibung
Autorisierung	Zeichenfolge	Erforderlich. Das Microsoft Entra-Zugriffstoken. Das Format ist `Bearer <token>`.
Inhaltsart	`string`	`application/JSON`

Pfadparameter

Keine

Abfrageparameter

Keine

Beispiel für Anforderungsnutzdaten

{
    "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 Schlüsseldefinitionen der Elemente in den Anforderungsnutzdaten.

Parameter	Erforderlich	Beschreibung	Zulässige Werte
`Name`	Ja	Benutzerfreundlicher Name der Abfrage	Zeichenfolge
`Description`	No	Beschreibung der erstellten Abfrage	Zeichenfolge
`Query`	Ja	Abfragezeichenfolge basierend auf geschäftlichem Bedarf	Zeichenfolge

Hinweis

Beispiele für benutzerdefinierte Abfragen finden Sie unter Beispielabfragen.

Beispiel für eine Antwort

Die Antwortnutzdaten sind wie folgt strukturiert:

Antwortcodes: 200, 400, 401, 403, 500

Beispiel einer Antwortnutzlast:

{
  "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 Schlüsseldefinitionen 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 während der Abfrageerstellung in der Anforderungsnutzlast bereitgestellt wird
`Query`	Benutzerdefinierte Berichtsabfrage, die während der Abfrageerstellung in der Anforderungsnutzlast bereitgestellt wird
`Type`	`userDefined` Für manuell erstellte Abfragen festgelegt
`User`	Benutzer-ID, die zum Erstellen der Abfrage verwendet wird
`CreatedTime`	UTC-Zeit, zu der 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 der API-Ausführung

Erstellen einer Berichts-API

Wenn Sie erfolgreich eine benutzerdefinierte Berichtsvorlage erstellt und die QueryID als Teil der Antwort der API zum Erstellen von Berichten erhalten haben, kann diese API aufgerufen werden, um eine Abfrage zu planen, die in regelmäßigen Abständen ausgeführt werden soll. Sie können eine Häufigkeit und einen Zeitplan für die Übermittlung des Berichts festlegen. Für die von uns bereitgestellten Systemabfragen kann die API zum Erstellen von Berichten ebenfalls mit der QueryID abgerufen werden.

Anforderungssyntax

Methode	Anforderungs-URI
NACHRICHT	`https://api.partnercenter.microsoft.com/insights/v1.1/cmp/ScheduledReport`

Anforderungsheader

Header	Typ	Beschreibung
Autorisierung	Zeichenfolge	Erforderlich. Das Microsoft Entra-Zugriffstoken. Das Format ist `Bearer <token>`.
Inhaltstyp	Zeichenfolge	`application/JSON`

Pfadparameter

Keine

Abfrageparameter

Keine

Beispiel für Anforderungsnutzdaten

{
  "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 Schlüsseldefinitionen der Elemente in den Anforderungsnutzdaten.

Parameter	Erforderlich	Beschreibung	Zulässige Werte
`ReportName`	Ja	Benutzerfreundlicher Name, der dem Bericht zugewiesen ist	String
`Description`	No	Beschreibung des erstellten Berichts	String
`QueryId`	Ja	Abfrage-ID, die für die Berichtsgenerierung verwendet werden muss	String
`StartTime`	Ja	Der UTC-Zeitstempel für den Start der Berichtsgenerierung. Das Format sollte wie folgt lauten: yyyy-MM-ddTHH:mm:ssZ.	String
`ExecuteNow`	No	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`	Boolesch
`QueryStartTime`	Nein	Gibt optional die Startzeit für die Abfrage an, die die Daten extrahiert. Dieser Parameter ist nur für einen Zeitausführungsbericht anwendbar, bei dem `ExecuteNow` auf `true` festgelegt ist. Das Format sollte wie folgt lauten: yyyy-MM-ddTHH:mm:ssZ.	Zeitstempel als Zeichenfolge
`QueryEndTime`	No	Gibt optional die Startzeit für die Abfrage an, die die Daten extrahiert. Dieser Parameter ist nur für einen Zeitausführungsbericht anwendbar, bei dem `ExecuteNow` auf `true` festgelegt ist. Das Format sollte wie folgt lauten: yyyy-MM-ddTHH:mm:ssZ.	Zeitstempel als Zeichenfolge
`RecurrenceInterval`	Ja	Die Häufigkeit (in Stunden), mit der der Bericht generiert werden soll. Der Mindestwert ist 1, und der Maximalwert ist 17520.	Integer
`RecurrenceCount`	Ja	Anzahl der zu generierenden Berichte. Der Grenzwert ist abhängig vom Serienintervall.	Ganzzahl
`Format`	No	Dateiformat für die exportierte Datei. Standardformat ist CSV	CSV/TSV
`CallbackUrl`	No	Öffentlich zugängliche URL, die optional als Rückrufziel konfiguriert werden kann	String
`CallbackMethod`	No	Get/Post-Methode, die mit der Rückruf-URL konfiguriert werden kann	GET/POST
`EndTime`	Ja	UTC-Zeitstempel, an dem die Berichterstellung beendet wird. Das Format sollte wie folgt lauten: yyyy-MM-ddTHH:mm:ssZ.	String

Hinweis

Beim Erstellen des Berichts ist entweder EndTime oder eine Kombination aus RecurrenceInterval und RecurrenceCount ist obligatorisch.

Beispiel für eine Antwort

Die Antwortnutzdaten sind wie folgt strukturiert:

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

Antwortnutzlast:

{
  "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 Schlüsseldefinitionen der Elemente in der Antwort.

Parameter	Beschreibung
`ReportId`	Universally Unique Identifier (UUID) des von Ihnen erstellten Berichts
`ReportName`	Name, der während der Berichtserstellung in der Anforderungsnutzlast angegeben wird
`Description`	Beschreibung, die in der Anforderungsnutzlast während der Berichtserstellung 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, die zum Erstellen des Berichts verwendet wird
`CreatedTime`	Die UTC-Zeit, zu der der Bericht erstellt wurde, im folgenden Format: yyyy-MM-ddTHH:mm:ssZ
`ModifiedTime`	Die UTC-Zeit, zu der der Bericht zuletzt geändert wurde, im folgenden Format: yyyy-MM-ddTHH:mm:ssZ
`ExecuteNow`	ExecuteNow-Parameter, der während der Berichtserstellung in der Anforderungsnutzlast bereitgestellt wird
`queryStartTime`	Abfragestartzeit, die in der Anforderungsnutzlast während der Berichtserstellung bereitgestellt wird. Dies gilt nur, wenn `ExecuteNow` sie auf "True" festgelegt ist.
`queryEndTime`	Abfrageendzeit, die in der Anforderungsnutzlast während der Berichtserstellung bereitgestellt wird. Dies gilt nur, wenn `ExecuteNow` sie auf "True" festgelegt ist.
`StartTime`	Startzeit, die in der Anforderungsnutzlast während der Berichtserstellung bereitgestellt wird
`ReportStatus`	Status der Berichtsausführung. Die möglichen Werte lauten Angehalten, Aktiv und Inaktiv.
`RecurrenceInterval`	Wiederholungsintervall, das während der Berichtserstellung in der Anforderungsnutzlast bereitgestellt wird
`RecurrenceCount`	Wiederholungsanzahl für den Bericht Standard
`CallbackUrl`	Rückruf-URL, die während der Berichtserstellung in der Anforderungsnutzlast bereitgestellt wird
`CallbackMethod`	Callbackmethode, 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 in der Anforderungsnutzlast während der Berichtserstellung bereitgestellt wird. Dies gilt nur, wenn `ExecuteNow` sie auf "True" festgelegt ist.
`TotalRecurrenceCount`	`RecurrenceCount` in der Anforderungsnutzlast während der Berichtserstellung bereitgestellt
`nextExecutionStartTime`	UTC-Zeitstempel, wenn die ausführung des nächsten Berichts gestartet wird
`TotalCount`	Anzahl der Datensätze im Value-Array
`StatusCode`	Ergebniscode. Die möglichen Werte sind 200, 400, 401, 403, 500.
`message`	Statusmeldung der API-Ausführung

API zum Abrufen von Berichtsausführungen

Sie können diese Methode verwenden, um den Status einer Berichtsausführung mithilfe der von der API zum Erstellen von Berichten empfangenen ReportId 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 für einen bestimmten Bericht abzurufen.

Wichtig

Diese API verfügt über Standardabfrageparameter, die für executionStatus=Completed und getLatestExecution=true festgelegt sind. Daher wird beim Aufrufen der API vor der ersten erfolgreichen Ausführung des Berichts der Fehler 404 zurückgegeben. Ausstehende Ausführungen können durch Festlegen von executionStatus=Pending abgerufen werden.

Anforderungssyntax

Methode	Anforderungs-URI
Abrufen	`https://api.partnercenter.microsoft.com/insights/v1.1/cmp/ScheduledReport/execution/{reportId}?executionId={executionId}&executionStatus={executionStatus}&getLatestExecution={getLatestExecution}`

Anforderungsheader

Header	Typ	Beschreibung
Autorisierung	Zeichenfolge	Erforderlich. Das Microsoft Entra-Zugriffstoken. Das Format ist `Bearer <token>`.
Inhaltstyp	Zeichenfolge	`application/json`

Pfadparameter

Keine

Abfrageparameter

Parametername	Erforderlich	Type	BESCHREIBUNG
`reportId`	Ja	Zeichenfolge	Filter, mit dem Sie ausschließlich Ausführungsdetails zu Berichten abrufen können, wobei die `reportId` in diesem Argument angegeben ist.
`executionId`	No	Zeichenfolge	Filter, mit dem Sie ausschließlich Details zu Berichten abrufen können, wobei die `executionId` in diesem Argument angegeben ist. Mehrere `executionIds` können angegeben werden, indem sie durch ein Semikolon ";" getrennt werden.
`executionStatus`	No	Zeichenfolge/Enumeration	Filter, mit dem Sie ausschließlich Details zu Berichten abrufen können, wobei die `executionStatus` in diesem Argument angegeben ist. Gültige Werte sind `Pending`, `Running`, `Paused` und `Completed`. Der Standardwert ist `Completed`.
`getLatestExecution`	No	boolean	Die API gibt Details der aktuellen 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.

Anforderungsnutzlast

Keine

Beispiel für eine Antwort

Die Antwortnutzdaten sind wie folgt strukturiert:

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

Beispiel einer Antwortnutzlast:

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

Wenn die Berichtsausführung beendet ist, wird der Ausführungsstatus Completed angezeigt. Sie können den Bericht herunterladen, indem Sie die URL im reportAccessSecureLink auswählen.

Glossar

Wichtige Definitionen der Elemente 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 bei der Erstellung des Berichts angegeben wurde
`RecurrenceCount`	Wiederholungsanzahl, die bei der Erstellung des Berichts angegeben wurde
`CallbackUrl`	Rückruf-URL, die der Ausführungsinstanz zugeordnet ist
`CallbackMethod`	Callbackmethode, die während der Berichtserstellung in der Anforderungsnutzlast bereitgestellt wird
`Format`	Format der generierten Datei am Ende der Ausführung
`ExecutionStatus`	Status der Berichtsausführungsinstanz Gültige Werte sind `Pending`, `Running`, `Paused` und `Completed`.
`ReportLocation`	Speicherort, an dem der Bericht heruntergeladen wird.
`ReportAccessSecureLink`	Link, über den sicher auf den Bericht zugegriffen werden kann
`ReportExpiryTime`	Die UTC-Zeit, nach der der Berichtslink abläuft, im folgenden Format: yyyy-mm-ddThh: mm: SSZ
`ReportGeneratedTime`	Die UTC-Zeit, zu der der Bericht generiert wurde, im folgenden Format: yyyy-mm-ddThh: mm: SSZ
`EndTime`	Endzeit, die in der Anforderungsnutzlast während der Berichtserstellung bereitgestellt wird. Dies gilt nur, wenn `ExecuteNow` sie auf "True" festgelegt ist.
`TotalRecurrenceCount`	`RecurrenceCount` in der Anforderungsnutzlast während der Berichtserstellung bereitgestellt
`nextExecutionStartTime`	UTC-Zeitstempel, wenn die ausführung des nächsten Berichts gestartet wird
`TotalCount`	Anzahl von Datasets im Wertarray
`StatusCode`	Ergebniscode Die möglichen Werte sind 200, 400, 401, 403, 404 und 500
`message`	Statusmeldung der API-Ausführung

Nächste Schritte

Sie können die APIs über die Swagger-API-URL testen.
Erstellen Ihres ersten API-Aufrufs für Marketplace Insights-Berichte

Freigeben über

Programmatisches Zugriffsparadigma für den kommerziellen Marktplatz

Spezifikation der Berichtsabfragesprache

Erstellen einer Berichtsabfrage-API

Erstellen einer Berichts-API

API zum Abrufen von Berichtsausführungen

Nächste Schritte

Feedback

Feedback

Zusätzliche Ressourcen