編輯

共用方式為


Update printer

Namespace: microsoft.graph

Update the properties of a printer object.

This API is available in the following national cloud deployments.

Global service US Government L4 US Government L5 (DOD) China operated by 21Vianet

Permissions

Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions only if your app requires it. For details about delegated and application permissions, see Permission types. To learn more about these permissions, see the permissions reference.

Permission type Least privileged permissions Higher privileged permissions
Delegated (work or school account) Printer.ReadWrite.All Printer.FullControl.All
Delegated (personal Microsoft account) Not supported. Not supported.
Application Printer.ReadWrite.All Not available.

Note: Right now, only printers that don't have physical devices can be updated using application permissions.

HTTP request

PATCH /print/printers/{printerId}

Request headers

Name Description
Authorization Bearer {token}. Required. Learn more about authentication and authorization.
Content-type application/json when using delegated permissions, application/ipp or application/json when using application permissions. Required.

Request body

Delegated permissions and JSON payload

If using delegated permissions, in the request body, supply the values for the relevant printer fields that should be updated. Existing properties that aren't included in the request body maintain their previous values or are recalculated based on changes to other property values. For best performance, don't include existing values that haven't changed.

The following properties can be updated using delegated permissions.

Property Type Description
defaults printerDefaults The printer's default print settings.
location printerLocation The physical and/or organizational location of the printer.
displayName String The name of the printer.

Application permissions and JSON payload

In the request body, supply the values for the relevant printer fields that should be updated. Existing properties that aren't included in the request body maintain their previous values or be recalculated based on changes to other property values. For best performance, don't include existing values that haven't changed.

The following properties can be updated using application permissions.

Property Type Description
defaults printerDefaults The printer's default print settings.
capabilities printerCapabilities The capabilities of the printer associated with this printer share.
displayName String The name of the printer.
manufacturer String The manufacturer of the printer.
model String The model name of the printer.
status printerStatus The processing status of the printer, including any errors.
isAcceptingJobs Boolean Whether the printer is currently accepting new print jobs.

Application permissions and IPP payload

With application permissions, a printer can also be updated using an Internet Printing Protocol (IPP) payload. In this case, the request body contains a binary stream that represents the Printer Attributes group in IPP encoding.

The client MUST supply a set of Printer attributes with one or more values (including explicitly allowed out-of-band values) as defined in RFC8011 section 5.2 Job Template Attributes ("xxx-default", "xxx-supported", and "xxx-ready" attributes), Section 5.4 Printer Description Attributes. The client must also supply any attribute extensions supported by the Printer. The value(s) of each Printer attribute supplied replaces the value(s) of the corresponding Printer attribute on the target Printer object. For attributes that can have multiple values (1setOf), all values supplied by the client replace all values of the corresponding Printer object attribute.

Note: Do not pass operation attributes in the request body. The request body should only contain printer attributes.

Note: For printers to work with a particular platform, it should meet the requirements of that platform. For example, on the Windows client, it is expected that the printer specifies all attributes that are considered mandatory as per MOPRIA specs. Please note MOPRIA specs are available to only the paid members of MOPRIA.

Response

Delegated permissions and JSON payload

If using delegated permissions, if successful, this method returns a 200 OK response code and an updated printer object in the response body.

Application permissions and JSON payload

If using delegated permissions, if successful, this method returns a 200 OK response code and an updated printer object in the response body.

Application permissions and IPP payload

If using application permissions, if successful, this method returns a 204 No content response code. It doesn't return anything in the response body.

Examples

Request

The following example shows a request.

PATCH https://graph.microsoft.com/v1.0/print/printers/{printerId}
Content-Type: application/json

{
  "name": "PrinterName",
  "location": {
    "latitude": 1.1,
    "longitude": 2.2,
    "altitudeInMeters": 3
  }
}

Response

The following example shows the response. Note: The response object shown here might be shortened for readability.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#print/printers/$entity",
  "id": "016b5565-3bbf-4067-b9ff-4d68167eb1a6",
  "displayName": "PrinterName",
  "manufacturer": "PrinterManufacturer",
  "model": "PrinterModel",
  "isShared": true,
  "registeredDateTime": "2020-02-04T00:00:00.0000000Z",
  "isAcceptingJobs": true,
  "status": {
    "state": "idle",
    "details": [],
    "description": ""
  },
  "defaults": {
    "copiesPerJob":1,
    "contentType": "application/oxps",
    "finishings": ["none"],
    "mediaType": "stationery"
  },
  "location": {
    "latitude": 1.1,
    "longitude": 2.2,
    "altitudeInMeters": 3,
    "streetAddress": "One Microsoft Way",
    "subUnit": [
        "Main Plaza",
        "Unit 400"
    ],
    "city": "Redmond",
    "postalCode": "98052",
    "countryOrRegion": "USA",
    "site": "Puget Sound",
    "building": "Studio E",
    "floor": "1",
    "floorDescription": "First Floor",
    "roomName": "1234",
    "roomDescription": "First floor copy room",
    "organization": [
        "C+AI",
        "Microsoft Graph"
    ],
    "subdivision": [
        "King County",
        "Red West"
    ],
    "stateOrProvince": "Washington"
  }
}