Druckerregistrierung bei Universelles Drucken (UP)
1. (Registrierung)
1.1 Flow
1.2 APIs
Im globalen UP-Registrierungsdienst für die Registrierung von Druckern sind die folgenden APIs verfügbar.
Basis-URL des globalen UP-Registrierungsdiensts: https://register.print.microsoft.com
Die vollständige URL ist die Kombination aus der globalen Basis-URL und dem (den) unten aufgeführten Endpunkt(en).
1.2.1 /register
Der Register-Endpunkt dient zum Registrieren eines Druckers. Die Registrierung teilt sich in zwei Phasen.
Erstregistrierungsaufruf zum Registrieren des Druckers
Abrufen des Registrierungsstatus zum Abschießen der Registrierungsanforderung
1.2.1.1 Registrierung initiieren
Die erste Phase besteht darin, eine Registrierungsanforderung im globalen Registrierungsdienst zu initiieren. Dazu wird an den Register-Endpunkt eine POST-Anforderung mit den Registrierungsnutzdaten im JSON-Format ausgegeben.
1.2.1.1.1 HTTP-Anforderung
POST /api/{version}/register
{version} ist die Version der UP-Registrierungs-API/des Protokolls, das der Drucker verwendet.
Die derzeit unterstützten Versionen sind:
- v1.0
1.2.1.1.2 Anforderungsheader
Für v1.0:
| Name | Beschreibung |
|---|---|
| Autorisierung | Bearer {token} erforderlich. Der Drucker muss bei Administrator*innen bei Microsoft Entra ID angemeldet sein, indem er den Gerätecodefluss oder einem anderen Autorisierungsablauf befolgt. |
1.2.1.1.3 Inhaltstyp anfordern
application/json
1.2.1.1.4 Anforderungsnutzdaten
Die Nutzdaten der Registrierungsanforderung haben das JSON-Format mit den folgenden Werten (Groß-/Kleinschreibung beachten):
| Name des Werts | Werttyp | Beschreibung | Erforderlich |
|---|---|---|---|
| name | Zeichenfolge | Der Anzeigename des Druckers. | Ja |
| Hersteller | Zeichenfolge | Der Hersteller des Druckers. | Ja |
| Modell | Zeichenfolge | Das Modell des Druckers. | Ja |
| device_id | Zeichenfolge | Die physische Geräte-UUID des Druckers. | Ja |
| device_type | Zeichenfolge | Der Gerätetyp. Unterstützte Werte (ohne Anführungszeichen): „Printer“ | Ja |
| certificate_request | DeviceCertRequest-Objekt | Die X.509-Zertifikatsignaturanforderung (Certificate Signing Request, CSR) für das Zertifikat, das vom Drucker erstellt und verwendet wird, um sich selbst zu identifizieren. Ein Codierungsbeispiel zum Erstellen einer CSR mit der BouncyCastle .NET-Bibliothek finden Sie in Anhang A.1. | Ja |
Das DeviceCertRequest-Objekt weist die folgenden Werte auf (Groß-/Kleinschreibung beachten):
| Name des Werts | Werttyp | Beschreibung | Erforderlich |
|---|---|---|---|
| Typ | Zeichenfolge | Eine Eigenschaft, die „pkcs10“ enthalten MUSS. | Ja |
| data | Zeichenfolge | Eine Eigenschaft, die eine base64-codierte PKCS#10-Zertifikatanforderung RFC4211 enthält. Die Zertifikatanforderung MUSS einen RSA-Algorithmus des öffentlichen Schlüssels mit einem 2048-Bit-Schlüssel, einem SHA256WithRSAEncryption-Signaturalgorithmus und einem SHA256-Hashalgorithmus verwenden. | Ja |
| transport_key | Zeichenfolge | Der base64-codierte öffentliche Teil eines asymmetrischen Schlüssels, der vom Client generiert wird. | Ja |
1.2.1.1.5 Erfolgreiche Antwort
Bei Erfolg (202 Akzeptiert) haben die Nutzdaten der Registrierungsanforderung das JSON-Format mit den folgenden Werten (Groß-/Kleinschreibung beachten):
| Name des Werts | Werttyp | Beschreibung | Erforderlich |
|---|---|---|---|
| registration_id | Zeichenfolge | Die eindeutige ID, die diese Registrierungsanforderung repräsentiert. Sie wird beim Abrufen des Registrierungsstatus verwendet. | Yes |
| interval | integer | Dauer des Abrufintervalls (in Sekunden) zum Überprüfen des Abschlusses der Registrierungsanforderung. | Ja |
1.2.1.1.6 Fehlerantwort
Bei einem Fehler werden die folgenden HTTP-Statuscodes zusammen mit den Fehlerantwort-Nutzdaten zurückgegeben. Die Fehlerantwort-Nutzdaten enthalten ein JSON-Fehlerobjekt nach dem Format in Abschnitt 2.
HTTP-Statuscodes
| HTTP-Statuscode | Beschreibung |
|---|---|
| 400 (Ungültige Anforderung) | Die Anforderung ist nicht wohlgeformt oder falsch. Details dazu finden Sie unter Fehlerantwort-Nutzdaten. Korrigieren sie die Anforderung, und senden Sie sie erneut. |
| 500 (Interner Serverfehler) | Beim Dienst ist ein interner Fehler aufgetreten. Details dazu finden Sie unter Fehlerantwort-Nutzdaten. Wiederholen Sie die Anforderung (wenn möglich, wird retry_timeout gesetzt). |
Fehlercodes
| Fehlercodes | Beschreibung | HTTP-Statuscode |
|---|---|---|
| invalid_request | Die Nutzdaten der Registrierungsanforderung waren falsch formatiert/ungültig. Das kommt in der Regel während der Entwicklungsphasen vor. Weitere Informationen finden Sie unter error_description. | 400 |
| device_code_error | Der Dienst konnte kein Geräte-/Benutzercode-Paar generieren. | 500 |
| storage_error | Beim Dienst ist ein Fehler mit dem Back-End-Speicher aufgetreten. | 500 |
| service_error | Serverfehler. Weitere Informationen finden Sie unter error_description. | 500 |
1.2.1.1.7 Beispiele
1.2.1.1.7.5 Anforderung v1.0
POST https://register.print.microsoft.com/api/v1.0/register HTTP/1.1
Connection: Keep-Alive
Content-Type: application/json; charset=utf-8
Accept-Encoding: gzip, deflate
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6IkZ6U3pHTVZ1a0U2Nm9EQnpwR0JUY2NBMlVRYyIsImtpZCI6IkZ6U3pHTVZ1a0U2Nm9EQnpwR0JUY2NBMlVRYyJ9.eyJhdWQiOiJodHRwczovL3ByaW50LnByaW50LXBwZS5taWNyb3NvZnQuY29tIiwiaXNzIjoiaHR0cHM6Ly9zdHMud2luZG93cy1wcGUubmV0LzIwZGY5NTlmLWE0OTItNGU3NC05N2E3LTE0YWJiM2ZlZjFkYi8iLCJpYXQiOjE1NjE2NzUxNjYsIm5iZiI6MTU2MTY3NTE2NiwiZXhwIjoxNTYxNjc5MDY2LCJhY3IiOiIxIiwiYWlvIjoiNDJOZ1lOQXNYbUtTSHZSM3Jvcjd2RVdMMWtmc0NMUi93R085cjYzMGl2T1RLWlVoV1ZzQSIsImFtciI6WyJwd2QiXSwiYXBwaWQiOiI0MTdhZTZlYi1hYWM4LTQyYzgtOTAwYy0wZTUwZGViYmE2ODgiLCJhcHBpZGFjciI6IjAiLCJmYW1pbHlfbmFtZSI6IlN0YWdlciIsImdpdmVuX25hbWUiOiJNYWRlbGluZSIsImdyb3VwcyI6WyI1YjljNGVkMS0yMWUyLTRkNzktYjE0Zi1mMzYyMTI5ODcyYjIiXSwiaXBhZGRyIjoiMTMxLjEwNy4xNTkuMjAiLCJuYW1lIjoiTWFkZWxpbmUgU3RhZ2VyIiwib2lkIjoiYzJmMjg2NDctMWQ4ZS00YTdhLWIzZjctZjU4YmQ3ODYxODk4IiwicHVpZCI6IjEwMDM0MDAwMDA2OEJFQzgiLCJzY3AiOiJzYW1wbGVzLnJlYWQgc2FtcGxlcy53cml0ZSIsInN1YiI6IlR6b2hRcmNzTHNjNUNHR09hWndxa1ZiajhaSkh4MnB1dzdpcWhWVXFWRGsiLCJ0ZW5hbnRfY3RyeSI6IlVTIiwidGlkIjoiMjBkZjk1OWYtYTQ5Mi00ZTc0LTk3YTctMTRhYmIzZmVmMWRiIiwidW5pcXVlX25hbWUiOiJtYXN0YWdlckBjbG91ZHByaW50cHBlLmNjc2N0cC5uZXQiLCJ1cG4iOiJtYXN0YWdlckBjbG91ZHByaW50cHBlLmNjc2N0cC5uZXQiLCJ1dGkiOiJlal84QlAtLW1rZWNNWjdncFJNR0FBIiwidmVyIjoiMS4wIiwid2lkcyI6WyI2MmU5MDM5NC02OWY1LTQyMzctOTE5MC0wMTIxNzcxNDVlMTAiXX0.e1RpyZDQzqlV11uyRXWRmaqf6wk2mg763muoIiMG2Qq8DW221Rg91cLP5px6KSfhpd7nv-Ln_KUFsZ4IlJqfmsrfCL_vgKHjYQuRDv2BY8-vrIqUC_5XVA_sj2Ib7iT7SjDYyMv6QDZM2rf7kVggvRuaZihUxxGZWby84EXD8KKAYfAQGo3r6AceuSDJOvToMy-Kp-MEqRuzExZdq2p1_qRIBtHe8Its4xuR8ZHEVqWnY0Y_qeVA8uxl3mQxZSvH8BVYn4Bdy_VZcNtrNKt3YpHFzG4kgy5V6wGLecRI7IBzYd4uK_FwpaYXHpkrSbO0ATEX3tjrgPnHbicA053Ilw
Content-Length: 1600
{
"name": "Test Printer",
"manufacturer": "Test Manufacturer",
"model": "Test Model",
"device_type": "printer",
"device_id": "a188d9e8-8daa-44c9-862b-d6202bcf1b68",
"certificate_request":
{
"type": "pkcs10",
"data": "MIICpDCCAYwCAQAwYTELMAkGA1UEBhMCVVMxEzARBgNVBAgMCldhc2hpbmd0b24xEDAOBgNVBAcMB1JlZG1vbmQxFzAVBgNVBAoMDk1pY3Jvc29mdCBDb3JwMRIwEAYDVQQDDAlNaWNyb3NvZnQwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDJ1xUdFKBlFdS9dHqSrD7YS0ZJ6MgcYy5wI3P0wOWrDi28OCBLbt6HBg02KDh1MlmVrfIR2O6WWeJ59M63JuwEn2e2WoGnIb/M6NyANyBBmgZ3bjp39UJHbXtYYXm/VJrPcOLM09dST7KR1zAcD2J+rnK8ZVUtYuTl58D7R6zsrYshw5CwxfLYPXeXwiSoKhtEC8Xn1lz3mi5B2SdsFHdjaQb6E0tCG5zdrVzzhCEVPaoo4e9SCTB9jDNulTU1ZkHzGBk+UzlKv4APsclyGCTEgA01T6/ueBrVeKY9d4DYfz/pu4sm0Vf1E+2hggtwbBOP60sFtkfnKiwtVoDF1KC9AgMBAAEwDQYJKoZIhvcNAQELBQADggEBACdggPBJ5MoJJ3QjVYDypuJGWDVWBT0G4pXNZHNz5Q4OVDze7aCw3Sl78Qdzy++XsrSXjtyZyEb+A5R36YKTpzRBCHSOWyZkZKpxj0Uo8/+RzjzJ1uvtwfhelfQ6EVktFsz6a2hixcaa47bN/bjj9stJbbRsxjJwR1K5YI/i+9DaUE7r7VDXiknQ7/ZyEYquAqY/O/LEnFOGhkSvkLlFPTbnJ7fzURyNnQhmp8p3DMj5dXYgKfWPxViqvJChx8pJf9zM4TjzaTZIj08tSOp2LtWGeMNkFgYJH4URe3t4OPx5crkKj8i5aIW1Ulb8ezJLW1IU7W8hF71ooZWFTOsAnjQ=",
"transport_key":"MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAydcVHRSgZRXUvXR6kqw+2EtGSejIHGMucCNz9MDlqw4tvDggS27ehwYNNig4dTJZla3yEdjullniefTOtybsBJ9ntlqBpyG/zOjcgDcgQZoGd246d/VCR217WGF5v1Saz3DizNPXUk+ykdcwHA9ifq5yvGVVLWLk5efA+0es7K2LIcOQsMXy2D13l8IkqCobRAvF59Zc95ouQdknbBR3Y2kG+hNLQhuc3a1c84QhFT2qKOHvUgkwfYwzbpU1NWZB8xgZPlM5Sr+AD7HJchgkxIANNU+v7nga1XimPXeA2H8/6buLJtFX9RPtoYILcGwTj+tLBbZH5yosLVaAxdSgvQIDAQAB"
}
}
1.2.1.1.7.6 Antwort v1.0
HTTP/1.1 202 Accepted
Date: Thu, 27 Jun 2019 22:47:34 GMT
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
{
"registration_id": "fbbd6371-7e88-4881-8818-8d2ea2e8fe88",
"interval": 5
}
1.2.1.2 Abrufen des Registrierungsstatus
Nachdem die Registrierungsanforderung erfolgreich akzeptiert wurde, ruft der Drucker vom Endpunkt /register den Status der Registrierungsanforderung ab. Der Drucker sollte den Abruf basierend auf dem in der Registrierungsantwort empfangenen Intervallwert abfragen und muss den empfangenen registration_id angeben.
1.2.1.2.1 HTTP-Anforderung
GET /api/{version}/register?{Query Parameters}
{version} ist die Version der UP-Registrierungs-API/des Protokolls, das der Drucker verwendet.
Die derzeit unterstützten Versionen sind:
- v1.0
{Query Parameters} werden im nächsten Abschnitt angegeben
1.2.1.2.2 Anforderungsheader
Für v1.0:
| Name | Beschreibung |
|---|---|
| Autorisierung | Bearer {token} Erforderlich. Der Drucker muss bei Administrator*innen bei Microsoft Entra ID angemeldet sein oder dem Gerätecodefluss folgen. Es kann das gleiche Token verwendet werden, das für die erste Registeranforderung erworbenen wurde. |
1.2.1.2.3 Abfrageparameter anfordern
| Parametername | Beschreibung | Erforderlich |
|---|---|---|
| registration_id | Die mit der Antwort auf die Registrierungsanforderung empfangene Registrierungs-ID. | Ja |
1.2.1.2.4 Erfolgreiche Antworten
Die folgenden HTTP-Statuscodes werden für die folgenden Erfolgsszenarien zurückgegeben:
| HTTP-Statuscode | Registrierungsphase |
|---|---|
| 200 (OK) | Registrierung abgeschlossen |
| 202 (Akzeptiert) | Registrierung in Arbeit – Bitte nehmen Sie eine weitere Anforderung vor, nachdem die Intervallzeit abgelaufen ist. |
Antwortnutzdaten
Registrierung in Arbeit (202 akzeptiert):
Die Nutzdaten der Registrierungsantwort haben das JSON-Format mit den folgenden Werten (Groß-/Kleinschreibung beachten):
| Name des Werts | Werttyp | Beschreibung | Erforderlich |
|---|---|---|---|
| interval | integer | Dauer des Abrufintervalls (in Sekunden) zum Überprüfen des Abschlusses der Registrierungsanforderung. Beachten Sie, dass die Dauer des Abrufintervalls nicht jedes Mal gleich ist. | Ja |
Registrierung abgeschlossen (200 OK):
Die Nutzdaten der Registrierungsantwort haben das JSON-Format mit den folgenden Werten (Groß-/Kleinschreibung beachten):
| Name des Werts | Werttyp | Beschreibung | Erforderlich |
|---|---|---|---|
| cloud_device_id | Zeichenfolge | Die UUID des Druckers in der Cloud, die dieser Drucker repräsentiert. | Ja |
| Zertifikat | Zeichenfolge | Base64-codiertes signiertes X.509-Zertifikat. | Ja |
| print_svc_url | Zeichenfolge | Die URL für den Universelles Drucken (UP) Dienst, der Druckervorgänge verarbeitet. | Ja |
| notification_url | Zeichenfolge | Die URL, die vom Drucker zum Überwachen auf Benachrichtigungen verwendet werden sollte (neuer Druckauftrag, Abbrechen des Druckauftrags usw.). | Ja |
| mcp_svc_resource_id | Zeichenfolge | Die Ressourcen-ID des UP-Diensts. Erforderlich beim Anfordern des OAuth-Tokens für die Kommunikation mit UP und den UP-Benachrichtigungsdiensten. | Ja |
| device_token_url | Zeichenfolge | Die URL der Secure Token Authority (STA), die der Drucker zum Abrufen von Tokens für UP und die UP-Benachrichtigungsdienste verwenden sollte. | Ja |
1.2.1.2.5 Fehlerantwort
Bei einem Fehler werden die folgenden HTTP-Statuscodes zusammen mit den Fehlerantwort-Nutzdaten zurückgegeben. Die Fehlerantwort-Nutzdaten enthalten ein JSON-Fehlerobjekt nach dem Format in Abschnitt 2.
HTTP-Statuscodes
| HTTP-Statuscode | Beschreibung |
|---|---|
| 400 (Ungültige Anforderung) | Die Anforderung ist nicht wohlgeformt oder falsch. Details dazu finden Sie unter Fehlerantwort-Nutzdaten. Die Registrierung sollte erneut gestartet werden. |
| 500 (Interner Serverfehler) | Beim Dienst ist ein interner Fehler aufgetreten. Details dazu finden Sie unter Fehlerantwort-Nutzdaten. Die Registrierung sollte erneut gestartet werden. |
Fehlercodes
| Fehlercodes | Beschreibung | HTTP-Statuscode |
|---|---|---|
| invalid_registration_id | Die angegebene Registrierungs-ID ist ungültig. Das kann vorkommen, wenn die Registrierungs-ID falsch gespeichert wurde oder die Druckerregistrierung nicht innerhalb des Registrierungstimeouts abgeschlossen wurde. Die Registrierung sollte erneut gestartet werden. | 400 |
| device_already_exists | Das zu registrierende Gerät ist bereits registriert. Der Administrator sollte im UP-Portal prüfen, ob das registrierte Gerät vorhanden ist. Wenn ja, könnte es sich um einen veralteten Eintrag handeln, den der Administrator vergessen hat, zu löschen/aufzuheben. Die Registrierung sollte erneut gestartet werden. | 400 |
| user_token_error | Der Server konnte das Benutzertoken zum Durchführen der Registrierung nicht abrufen. Die Registrierung sollte erneut gestartet werden. | 500 |
| storage_error | Beim Dienst ist ein Fehler mit dem Back-End-Speicher aufgetreten. Die Registrierung sollte erneut gestartet werden. | 500 |
| service_error | Serverfehler. Weitere Informationen finden Sie unter error_description. Die Registrierung sollte erneut gestartet werden. | 500 |
1.2.1.2.6 Beispiele
1.2.1.2.6.3 Anforderung v1.0
GET https://register.print.microsoft.com/api/v1.0/register?registration_id=bb86db79-2918-
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6IkZ6U3pHTVZ1a0U2Nm9EQnpwR0JUY2NBMlVRYyIsImtpZCI6IkZ6U3pHTVZ1a0U2Nm9EQnpwR0JUY2NBMlVRYyJ9.eyJhdWQiOiJodHRwczovL3ByaW50LnByaW50LXBwZS5taWNyb3NvZnQuY29tIiwiaXNzIjoiaHR0cHM6Ly9zdHMud2luZG93cy1wcGUubmV0LzIwZGY5NTlmLWE0OTItNGU3NC05N2E3LTE0YWJiM2ZlZjFkYi8iLCJpYXQiOjE1NjE2NzUxNjYsIm5iZiI6MTU2MTY3NTE2NiwiZXhwIjoxNTYxNjc5MDY2LCJhY3IiOiIxIiwiYWlvIjoiNDJOZ1lOQXNYbUtTSHZSM3Jvcjd2RVdMMWtmc0NMUi93R085cjYzMGl2T1RLWlVoV1ZzQSIsImFtciI6WyJwd2QiXSwiYXBwaWQiOiI0MTdhZTZlYi1hYWM4LTQyYzgtOTAwYy0wZTUwZGViYmE2ODgiLCJhcHBpZGFjciI6IjAiLCJmYW1pbHlfbmFtZSI6IlN0YWdlciIsImdpdmVuX25hbWUiOiJNYWRlbGluZSIsImdyb3VwcyI6WyI1YjljNGVkMS0yMWUyLTRkNzktYjE0Zi1mMzYyMTI5ODcyYjIiXSwiaXBhZGRyIjoiMTMxLjEwNy4xNTkuMjAiLCJuYW1lIjoiTWFkZWxpbmUgU3RhZ2VyIiwib2lkIjoiYzJmMjg2NDctMWQ4ZS00YTdhLWIzZjctZjU4YmQ3ODYxODk4IiwicHVpZCI6IjEwMDM0MDAwMDA2OEJFQzgiLCJzY3AiOiJzYW1wbGVzLnJlYWQgc2FtcGxlcy53cml0ZSIsInN1YiI6IlR6b2hRcmNzTHNjNUNHR09hWndxa1ZiajhaSkh4MnB1dzdpcWhWVXFWRGsiLCJ0ZW5hbnRfY3RyeSI6IlVTIiwidGlkIjoiMjBkZjk1OWYtYTQ5Mi00ZTc0LTk3YTctMTRhYmIzZmVmMWRiIiwidW5pcXVlX25hbWUiOiJtYXN0YWdlckBjbG91ZHByaW50cHBlLmNjc2N0cC5uZXQiLCJ1cG4iOiJtYXN0YWdlckBjbG91ZHByaW50cHBlLmNjc2N0cC5uZXQiLCJ1dGkiOiJlal84QlAtLW1rZWNNWjdncFJNR0FBIiwidmVyIjoiMS4wIiwid2lkcyI6WyI2MmU5MDM5NC02OWY1LTQyMzctOTE5MC0wMTIxNzcxNDVlMTAiXX0.e1RpyZDQzqlV11uyRXWRmaqf6wk2mg763muoIiMG2Qq8DW221Rg91cLP5px6KSfhpd7nv-Ln_KUFsZ4IlJqfmsrfCL_vgKHjYQuRDv2BY8-vrIqUC_5XVA_sj2Ib7iT7SjDYyMv6QDZM2rf7kVggvRuaZihUxxGZWby84EXD8KKAYfAQGo3r6AceuSDJOvToMy-Kp-MEqRuzExZdq2p1_qRIBtHe8Its4xuR8ZHEVqWnY0Y_qeVA8uxl3mQxZSvH8BVYn4Bdy_VZcNtrNKt3YpHFzG4kgy5V6wGLecRI7IBzYd4uK_FwpaYXHpkrSbO0ATEX3tjrgPnHbicA053Ilw
Host: register.print.microsoft.com
1.2.1.2.6.4 Antwort In Bearbeitung v1.0
HTTP/1.1 202 Accepted
Cache-Control: no-cache
Pragma: no-cache
{
"interval": 15
}
1.2.1.2.6.7 Antwort Abgeschlossen v1.0
HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Length: 267
Content-Type: application/json; charset=utf-8
{
"cloud_device_id": "7c907b43-d8f0-4e42-a279-1e37eb4fd2bf",
"certificate": "MIID8jCCAtqgAwIBAgIQR2Y15zkurJhCGxcaQ0d7tjANBgkqhkiG9w0BAQsFADB4MXYwEQYKCZImiZPyLGQBGRYDbmV0MBUGCgmSJomT8ixkARkWB3dpbmRvd3MwHQYDVQQDExZNUy1Pcmdhbml6YXRpb24tQWNjZXNzMCsGA1UECxMkODJkYmFjYTQtM2U4MS00NmNhLTljNzMtMDk1MGMxZWFjYTk3MB4XDTE4MDExOTAwNTIxM1oXDTI4MDExOTAxMjIxM1owLzEtMCsGA1UEAxMkZjVlYjVmNWUtMDYyNC00YTNiLThmZjItNjQ5ZTAyM2ZiNzJkMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEApQc0Twp+vlT5Vc74zLoXbrufcIKnoW980OWFKHf7lRlRqjj9MWpea99j+3K8JQSoifXJvS5QzyjXrH9phsrfX84I258y6dM/aUadLYYKjO38wx9c1vQppZi1P3LcDaJiXPgNQ8omWCtDNoVwQlTUmB9Pq6h+V6S4P59Mq9cem6yEE7pu4DLqLSB68jexvLQnuGDfn6PsVUC3ML21zDmAr3QDikiZDe9Iy03IRrXvl6obj5QZtkGFbK9ueArFcWpymsEK
FfVhrKL7ca/rAEFHsHacJYHkJNMw3Qzs0yMYZRsH/fS+eBebvQWUEujQ+BX8xZQX48ukwtC8R37RsqrLjwIDAQABo4HAMIG9MAwGA1UdEwEB/wQCMAAwFgYDVR0lAQH/BAwwCgYIKwYBBQUHAwIwIgYLKoZIhvcUAQWCHAIEEwSBEF5f6/UkBjtKj/JkngI/ty0wIgYLKoZIhvcUAQWCHAMEEwSBEHXH6W+38IhBoi1uqlWcNhUwIgYLKoZIhvcUAQWCHAUEEwSBEAWT1qlxl5pLvXhzFTIfL2swFAYLKoZIhvcUAQWCHAgEBQSBAk5BMBMGCyqGSIb3FAEFghwHBAQEgQEwMA0GCSqGSIb3DQEBCwUAA4IBAQCXpFMa9DCgIIJTD3RlEyPN8WB/HgMkhLBqwtZugkmIn8D80ckuhrfa2jJfWkNxEfFXanjq9B4tAvkNt7vBXiYw+PKj8+CE5FgfUTNtIw3Q/06tnJBj20mz28ZNbdRUgXzxXiY7oZss54dbHH+7TFO9k9Pm1CuUOzLFX4LeC48wo/S6uN7JDeID6pQjcR00eYJ+gcD800AXBYXrqSreYhdtl1swcD71qgshELAo2qXu0kzuKj05GIB5SXFOoU+KhuB0LMuEZF5rsQPN4KcasGaAb/8MIORAxkYStNLQZQLYbDve/dUownbfruW/o3tnjJP0GA0gY/Ohv5ssgrCFsiBq",
"print_svc_url": "https://print.print.microsoft.com/",
"notification_url": "https://notification.print.microsoft.com/",
"mcp_svc_resource_id":"https://print.print.microsoft.com",
"device_token_url": "https://login.microsoftonline.com/common/oauth2/token"
}
1.2.1.3 Authentifizierung
Bevor Sie den Drucker registrieren, müssen Administrator*innen bei Microsoft Entra ID authentifiziert werden, indem sie den Gerätecodefluss oder einen anderen Autorisierungsablauf befolgen. Das abgerufene Zugriffstoken des Druckeradministrators muss im Autorisierungsheader der Anforderung zum Registrieren eines Druckers gesendet werden. Dokumentation zu Gerätecode und anderen Authentifizierungsabläufen, die von Microsoft Entra ID unterstützt werden, finden Sie unter Unterstützte Authentifizierungsabläufe.
1.2.1.3.1 Gerätecodeablauf-Parameter
Dokumentation zum Gerätecodefluss, der von Microsoft Entra ID unterstützt wird, finden Sie unter OAuth 2.0-Gerätecodefluss. Die unten aufgeführte client_id ist temporär. Wir werden in naher Zukunft zusätzliche Informationen bereitstellen.
| Parametername | Beschreibung | Erforderlich |
|---|---|---|
| tenant | Verwenden Sie „Organisationen“ für den Mandantenparameter. | Ja |
| client_id | Verwenden Sie registered client ID für die client_id. Weitere Informationen finden Sie unter Registrieren des OEM-Clients. |
Ja |
| scope | Verwenden Sie https://print.print.microsoft.com/.default für den Bereich |
Ja |
1.2.1.3.2 Beispiel für Anforderungen des Gerätecodeablaufs
1.2.1.3.2.1 Einleiten des Gerätecodeflows
Anforderung:
POST https://login.microsoftonline.com/organizations/oauth2/v2.0/devicecode HTTP/1.1
Accept-Charset: utf-8
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Host: login.microsoftonline.com
Content-Length: 103
Expect: 100-continue
Connection: Keep-Alive
client_id=<registered_client_id>&scope=https%3A%2F%2Fprint.print.microsoft.com%2F.default
Antwort:
HTTP/1.1 200 OK
Cache-Control: no-cache, no-store
Pragma: no-cache
Content-Type: application/json; charset=utf-8
Expires: -1
Content-Length: 473
{
"user_code": "FMTB7B3WR",
"device_code": "FAQABAAEAAAAP0wLlqdLVToOpA4kwzSnx3SB1wjNptiBt5jFM8ePgJKGOjX-WOEksHYT3zgqz9VVg4MqY8J6Tej_rpniyj4WjOsVe-RCJuGexX-IwPKDK-df38P0zpLv5ktxSCflT_F-8Cbef6BRDpk0Qm-lPOhC4bcbtdIaM8yqf-cS962rGC9VdVNFVFStePppCDRcumjAgAA",
"verification_uri": "https://microsoft.com/devicelogin",
"expires_in": 900,
"interval": 5,
"message": "To sign in, use a web browser to open the page https://microsoft.com/devicelogin and enter the code FMTB7B3WR to authenticate."
}
1.2.1.3.2.2 Abrufen des Benutzertokens
Anforderung:
POST https://login.microsoftonline.com/tenant/oauth2/v2.0/token HTTP/1.1
Accept-Charset: utf-8
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Host: login.microsoftonline.com
Content-Length: 289
Expect: 100-continue
grant_type=device_code&client_id=<registered_client_id>&device_code=FAQABAAEAAAAP0wLlqdLVToOpA4kwzSnx3SB1wjNptiBt5jFM8ePgJKGOjX-WOEksHYT3zgqz9VVg4MqY8J6Tej_rpniyj4WjOsVe-RCJuGexX-IwPKDK-df38P0zpLv5ktxSCflT_F-8Cbef6BRDpk0Qm-lPOhC4bcbtdIaM8yqf-cS962rGC9VdVNFVFStePppCDRcumjAgAA
Antwort: authorization_pending, der Benutzer hat sich noch nicht angemeldet.
HTTP/1.1 400 Bad Request
Cache-Control: no-cache, no-store
Pragma: no-cache
Content-Type: application/json; charset=utf-8
Expires: -1
Content-Length: 469
{
"error": "authorization_pending",
"error_description": "AADSTS70016: Pending end-user authorization.\r\nTrace ID: 60997c8b-15ed-4d12-99b6-6da879fd1400\r\nCorrelation ID: 7300aba9-1698-4a4e-b6dd-66459a828108\r\nTimestamp: 2019-09-26 23:13:43Z",
"error_codes": [70016],
"timestamp": "2019-09-26 23:13:43Z",
"trace_id": "60997c8b-15ed-4d12-99b6-6da879fd1400",
"correlation_id": "7300aba9-1698-4a4e-b6dd-66459a828108",
"error_uri": https://login.microsoftonline.com/error?code=70016
}
Antwort: success, der Benutzer hat sich angemeldet, Token wird zurückgegeben. Dieser Token kann im erforderlichen Autorisierungsheader (siehe Abschnitt 1.2.1.1.2) verwendet werden, wenn eine Anforderung zum Registrieren eines Universelles Drucken Druckers gesendet wird.
HTTP/1.1 200 OK
Cache-Control: no-cache, no-store
Pragma: no-cache
Content-Type: application/json; charset=utf-8
Expires: -1
Content-Length: 1763
{
"token_type": "Bearer",
"scope": "https://print.print.microsoft.com/Print.Device https://print.print.microsoft.com/.default",
"expires_in": 3599,
"ext_expires_in": 3599,
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6ImFQY3R3X29kdlJPb0VOZzNWb09sSWgydGlFcyIsImtpZCI6ImFQY3R3X29kdlJPb0VOZzNWb09sSWgydGlFcyJ9.eyJhdWQiOiJodHRwczovL3ByaW50LnByaW50Lm1pY3Jvc29mdC5jb20iLCJpc3MiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC9mMGQ4ODMyMy04OGY2LTQ4MTMtOGI0ZC05NGVjNjdlNjA3YmQvIiwiaWF0IjoxNTY5NTM5Mzc3LCJuYmYiOjE1Njk1MzkzNzcsImV4cCI6MTU2OTU0MzI3NywiYWNyIjoiMSIsImFpbyI6IkFTUUEyLzhNQUFBQVA1U1NzTklCYXRVQ2UxSGZXaEdvNHhqbUM4b2RCckNpeDNaN0dyZWJUMEE9IiwiYW1yIjpbInB3ZCJdLCJhcHBpZCI6IjQxN2FlNmViLWFhYzgtNDJjOC05MDBjLTBlNTBkZWJiYTY4OCIsImFwcGlkYWNyIjoiMCIsImdyb3VwcyI6WyIzMjVhNDljOS1mNjQ0LTQxNjEtODdmZS1kZTQ5ZGEyNDhjZTkiXSwiaXBhZGRyIjoiMTY3LjIyMC4yLjE4IiwibmFtZSI6Ik1hZGVsaW5lIFN0YWdlciIsIm9pZCI6ImIzZTE1ODM0LTAxZmUtNDIwNi05MjkwLTk5OTNiMzM1MWM2MSIsInB1aWQiOiIxMDAzN0ZGRUFDRjVBNUE1Iiwic2NwIjoiUHJpbnQuRGV2aWNlIiwic3ViIjoiN2hhQzVjdEZlYjZPVHBsMHROUDJmRDJVY3pWTFRjbTZlNkQ1eEZkOEpvYyIsInRlbmFudF9jdHJ5IjoiVVMiLCJ0aWQiOiJmMGQ4ODMyMy04OGY2LTQ4MTMtOGI0ZC05NGVjNjdlNjA3YmQiLCJ1bmlxdWVfbmFtZSI6Im1hc3RhZ2VyQGNsb3VkcHJpbnRwcm9kdWN0aW9uLm9ubWljcm9zb2Z0LmNvbSIsInVwbiI6Im1hc3RhZ2VyQGNsb3VkcHJpbnRwcm9kdWN0aW9uLm9ubWljcm9zb2Z0LmNvbSIsInV0aSI6Inp2N2EtdGRrR0VHQkFSMl9zWU1UQUEiLCJ2ZXIiOiIxLjAiLCJ3aWRzIjpbIjYyZTkwMzk0LTY5ZjUtNDIzNy05MTkwLTAxMjE3NzE0NWUxMCJdfQ.Nfz82GPdQUx6py2xwhVhI4hvpbLTdaaDSVFnGx4Eb3CeJHcQvCmmKoB9Lze7YITcEcLdxUkGEQGEXSh6M3yDrNP_hsoIROdWhe6RDjbYVPmJUL319lL4eNtQTJq8bKcJVbeM5SamlY1mBIhxH_sjL4TX0NN2RnDIuF_L1NSRW0IaHoZxzf257y0n7BqPROl3VpQ97wA8P-hhVBbfwwB9i-sLbsoCVszuE9JnHpgJPm6h9FDL9Px57ddTMZDvJchxOL5gUTA76gdRqUUzLROCMlz0R7vTJotl2RQnrzZBoNNoM9iJHL2KqQKuuezHEro1453lSRASiBkZHHEOFglzSg"
}
2. Struktur der Fehlerantwort
Bei den obigen APIs wird bei einem Fehler die folgende Fehlerstruktur in den Nutzdaten im JSON-Format mit den folgenden Werten (Groß-/Kleinschreibung beachten) zurückgegeben. Diese Fehlerantworten dienen hauptsächlich zu Entwicklungszwecken, und der Entwickler kann entscheiden, was dem Benutzer, wenn überhaupt, angezeigt werden soll.
| Name des Werts | Werttyp | Beschreibung | Erforderlich |
|---|---|---|---|
| error | Zeichenfolge | Eine Fehlercode-Zeichenfolge, die zur Klassifizierung der Art des aufgetretenen Fehlers verwendet wird. | Ja |
| error_description | Zeichenfolge | Eine spezifische Fehlermeldung, mit der Sie die Grundursache des Fehlers identifizieren können. | No |
| error_code | integer | Zusätzlicher Fehlercode, der die Problemdiagnose erleichtern kann. | No |
| http_status_code | integer | Der HTTP-Statuscode, der mit dieser Fehlerantwort zurückgegeben wurde. | No |
| retry_timeout | integer | Die Anzahl der Sekunden, die der Drucker warten soll, bevor erneut versucht wird, der Anforderung stattzugeben. | No |
Jede oben genannte API listet die mögliche(n) Fehlercodezeichenfolge(n) auf.
2.1 Antwortbeispiel
{
"error": "invalid_request",
"error_description": "Missing required field device_type"
}
Konnektivität mit dem Dienst für Universelles Drucken nach der Druckerregistrierung
Universelles Drucken unterstützt die erforderliche Funktionalität, die in PWG 5100.18 (IPP Infra) definiert ist. Von einsatzbereiten Universelles Drucken Druckern wird erwartet, dass Sie dieses Protokoll zur Kommunikation mit Universelles Drucken verwenden, wenn der Druckerregistrierungsprozess abgeschlossen ist. Um sicherzustellen, dass die aufrufende Funktion ein Drucker mit Zugriff ist, verwendet der Drucker das Geräte-Zugriffstoken, wie unter Abruf des Drucker-Zugriffstokens beschrieben, als Bearer-Wert für den HTTP-Header Authorization .