REST-API-Beispiele für Jitterbit App Builder

Einführung

Die Beispiele auf dieser Seite zeigen beispielhafte REST-API-Anfragen und -Antworten. Sie gehen von einem Webdienst mit dem folgenden API-Endpunkt aus:

http://example.com/Vinyl/rest/v1/sales

Darüber hinaus wird davon ausgegangen, dass eine Ressource unter dem folgenden Endpunkt vorhanden ist:

http://example.com/Vinyl/rest/v1/sales/customers

Die Ressource enthält die folgenden Felder.

Feld	Standardmäßig enthalten
`customerId`	Wahr
`companyName`	Wahr
`contactName`	Wahr
`contactTitle`	Wahr
`address`	Falsch
`city`	Falsch
`region`	Falsch
`postalCode`	Falsch
`phone`	Falsch

Die ersten zehn Kunden abrufen

Dieses Beispiel zeigt, wie man die erste Gruppe von zehn Kunden zurückgibt. App Builder gibt standardmäßig zehn Elemente zurück.

Anfrage

GET /rest/v1/sales/customers HTTP/1.1
Host: example.com:443
Accept: application/json
X-API-Key: DLOo9sPS5slJEMHpXBFt3g

Antwort

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 534

{
  "count": null,
  "items": [
    {
      "customerId": "0243783f-7405-4ede-98fb-98b6ce7d71f8",
      "companyName": "Microsoft",
      "contactName": "Satya Nadella",
      "contactTitle": "CEO"
    },
    ... 9 additional items excluded for brevity ...
  ],
  "message": null,
  "validations": [],
  "status": 200
}

Die ersten fünf Kunden abrufen

Dieses Beispiel zeigt, wie man steuert, wie viele Elemente auf einmal zurückgegeben werden. App Builder gibt standardmäßig zehn zurück. Die maximale Anzahl von Elementen, die auf einmal zurückgegeben werden können, beträgt 100.

Anfrage

GET /rest/v1/sales/customers?$limit=5 HTTP/1.1
Host: example.com:443
Accept: application/json
X-API-Key: DLOo9sPS5slJEMHpXBFt3g

Antwort

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 534

{
  "count": null,
  "items": [
    {
      "customerId": "0243783f-7405-4ede-98fb-98b6ce7d71f8",
      "companyName": "Microsoft",
      "contactName": "Satya Nadella",
      "contactTitle": "CEO"
    },
    ... 4 additional items excluded for brevity ...
  ],
  "message": null,
  "validations": [],
  "status": 200
}

Die nächsten fünf Kunden abrufen

Dieses Beispiel zeigt, wie man durch die Kundenliste blättert und die zweite Seite mit fünf Kunden abruft.

Anfrage

GET /rest/v1/sales/customers?$limit=5&$offset=5 HTTP/1.1
Host: example.com:443
Accept: application/json
X-API-Key: DLOo9sPS5slJEMHpXBFt3g

Antwort

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 534

{
  "count": null,
  "items": [
    {
      "customerId": "0243783f-7405-4ede-98fb-98b6ce7d71f8",
      "companyName": "Apple",
      "contactName": "Tim Cook",
      "contactTitle": "CEO"
    },
    ... 4 additional items excluded for brevity ...
  ],
  "message": null,
  "validations": [],
  "status": 200
}

Bestimmte Kundenfelder abrufen

Dieses Beispiel zeigt, wie man eine Liste von Kunden mit bestimmten Feldern zurückgibt. In diesem Fall sind die Felder auf customerId, companyName und country beschränkt.

Anfrage

GET /rest/v1/sales/customers?$fields=customerId,companyName,country HTTP/1.1
Host: example.com:443
Accept: application/json
X-API-Key: DLOo9sPS5slJEMHpXBFt3g

Antwort

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 534

{
  "count": null,
  "items": [
    {
      "customerId": "0243783f-7405-4ede-98fb-98b6ce7d71f8",
      "companyName": "Microsoft",
      "country": "USA"
    },
    ... 9 additional items excluded for brevity ...
  ],
  "message": null,
  "validations": [],
  "status": 200
}

Alle Kundenfelder abrufen

Dieses Beispiel zeigt, wie man eine Liste von Kunden abruft, die alle verfügbaren Kundenfelder enthält.

Anfrage

GET /rest/v1/sales/customers?$fields=* HTTP/1.1
Host: example.com:443
Accept: application/json
X-API-Key: DLOo9sPS5slJEMHpXBFt3g

Antwort

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 534

{
  "count": null,
  "items": [
    {
      "customerId": "0243783f-7405-4ede-98fb-98b6ce7d71f8",
      "companyName": "Microsoft",
      "contactName": "Satya Nadella",
      "contactTitle": "CEO",
      "address": "One Microsoft Way",
      "city": "Redmond",
      "region": "WA",
      "postalCode": "98052-6399",
      "country": "USA",
      "phone": "555-555-5555"
    },
    ... 9 additional items excluded for brevity ...
  ],
  "message": null,
  "validations": [],
  "status": 200
}

Sortierte Kundenliste abrufen

Dieses Beispiel zeigt, wie man eine Liste von Kunden abruft, die absteigend nach Land und aufsteigend nach Unternehmensname sortiert ist.

Anfrage

GET /rest/v1/sales/customers?$sort=-country,companyName HTTP/1.1
Host: example.com:443
Accept: application/json
X-API-Key: DLOo9sPS5slJEMHpXBFt3g

Antwort

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 534

{
  "count": null,
  "items": [
    {
      "customerId": "0243783f-7405-4ede-98fb-98b6ce7d71f8",
      "companyName": "Apple",
      "contactName": "Tim Cook",
      "contactTitle": "CEO"
    },
    ... 9 additional items excluded for brevity ...
  ],
  "message": null,
  "validations": [],
  "status": 200
}

Anzahl aller Kunden einbeziehen

Dieses Beispiel zeigt, wie man die Gesamtzahl der Elemente in der Sammlung einbezieht. App Builder gibt standardmäßig die Gesamtzahl nicht zurück.

Anfrage

GET /rest/v1/sales/customers?$count=true HTTP/1.1
Host: example.com:443
Accept: application/json
X-API-Key: DLOo9sPS5slJEMHpXBFt3g

Antwort

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 534

{
  "count": 12429,
  "items": [
    {
      "customerId": "0243783f-7405-4ede-98fb-98b6ce7d71f8",
      "companyName": "Microsoft",
      "contactName": "Satya Nadella",
      "contactTitle": "CEO"
    },
    ... 9 additional items excluded for brevity ...
  ],
  "message": null,
  "validations": [],
  "status": 200
}

Kundenliste nach Land abrufen

Dieses Beispiel zeigt, wie man die Kundenliste nach Land einschränkt.

Anfrage

GET /rest/v1/sales/customers?country=USA HTTP/1.1
Host: example.com:443
Accept: application/json
X-API-Key: DLOo9sPS5slJEMHpXBFt3g

Antwort

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 534

{
  "count": null,
  "items": [
    {
      "customerId": "0243783f-7405-4ede-98fb-98b6ce7d71f8",
      "companyName": "Microsoft",
      "contactName": "Satya Nadella",
      "contactTitle": "CEO"
    },
    ... 9 additional items excluded for brevity ...
  ],
  "message": null,
  "validations": [],
  "status": 200
}

Neuen Kunden erstellen

Dieses Beispiel zeigt, wie man einen neuen Kunden erstellt, indem man in die Kundensammlung POSTet.

Anfrage

POST /rest/v1/sales/customers HTTP/1.1
Host: example.com:443
Accept: application/json
X-API-Key: DLOo9sPS5slJEMHpXBFt3g
Content-Type: application/json

{
  "companyName": "Jitterbit",
  "city": "Miami Beach",
  "region": "FL",
  "postalCode": "33139",
  "country": "USA"
}

Antwort

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 347

{
  "item": {
    "customerId": "9ce33474-8690-4a75-ab90-65caa6c3c24e",
    "companyName": "Jitterbit",
    "contactName": null,
    "contactTitle": null,
    "address": null,
    "city": "Miami Beach",
    "region": "FL",
    "postalCode": "33139",
    "country": "USA",
    "phone": null
  },
  "message": null,
  "validations": [],
  "status": 200
}

Vorhandenen Kunden abrufen

Dieses Beispiel zeigt, wie man einen vorhandenen Kunden aus der Kundensammlung abruft.

Anfrage

GET /rest/v1/sales/customers/9ce33474-8690-4a75-ab90-65caa6c3c24e HTTP/1.1
Host: example.com:443
Accept: application/json
X-API-Key: DLOo9sPS5slJEMHpXBFt3g

Antwort

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 347

{
  "item": {
    "customerId": "9ce33474-8690-4a75-ab90-65caa6c3c24e",
    "companyName": "Jitterbit",
    "contactName": null,
    "contactTitle": null,
    "address": null,
    "city": "Miami Beach",
    "region": "FL",
    "postalCode": "33139",
    "country": "USA",
    "phone": null
  },
  "message": null,
  "validations": [],
  "status": 200
}

Einen vorhandenen Kunden aktualisieren

Dieses Beispiel zeigt, wie man einen vorhandenen Kunden durch POST an das Sammlungselement aktualisiert.

Anfrage

POST /rest/v1/sales/customers/9ce33474-8690-4a75-ab90-65caa6c3c24e HTTP/1.1
Host: example.com:443
Accept: application/json
X-API-Key: DLOo9sPS5slJEMHpXBFt3g
Content-Type: application/json

{
  "companyName": "Jitterbit",
  "city": "Miami Beach",
  "region": "FL",
  "postalCode": "33139",
  "country": "USA"
}

Antwort

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 347

{
  "item": {
    "customerId": "9ce33474-8690-4a75-ab90-65caa6c3c24e",
    "companyName": "Jitterbit",
    "contactName": null,
    "contactTitle": null,
    "address": null,
    "city": "Miami Beach",
    "region": "FL",
    "postalCode": "33139",
    "country": "USA",
    "phone": null
  },
  "message": null,
  "validations": [],
  "status": 200
}

Einen vorhandenen Kunden mit einem Validierungsfehler aktualisieren

Dieses Beispiel zeigt, wie App Builder reagiert, wenn eine Aktualisierung einen Validierungsfehler auslöst. In diesem Fall zeigt der HTTP-Statuscode 400 an, dass der Vorgang nicht erfolgreich abgeschlossen wurde.

Anfrage

POST /rest/v1/sales/customers/9ce33474-8690-4a75-ab90-65caa6c3c24e HTTP/1.1
Host: example.com:443
Accept: application/json
X-API-Key: DLOo9sPS5slJEMHpXBFt3g
Content-Type: application/json

{
  "contactName": "This contact name is longer than permitted."
}

Antwort

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8
X-Vinyl-Version: 0.0.0
Date: Wed, 26 Oct 2016 19:11:55 GMT
Content-Length: 347

{
  "item": {
    "customerId": "9ce33474-8690-4a75-ab90-65caa6c3c24e",
    "companyName": "Jitterbit",
    "contactName": "This contact name is longer than permitted.",
    "contactTitle": null,
    "address": null,
    "city": "Miami Beach",
    "region": "FL",
    "postalCode": "33139",
    "country": "USA",
    "phone": null
  },
  "message": "The changes could not be saved.",
  "validations": [
    {
      "message": "ContactName has exceeded length of 30 by 13 characters.",
      "severity": "error",
      "field": "contactName"
    }
  ],
  "status": 200
}

Einen vorhandenen Kunden löschen

Dieses Beispiel zeigt, wie man einen vorhandenen Kunden aus der Sammlung löscht. Beachten Sie, dass der gelöschte Kundendatensatz in der Antwort zurückgegeben wird. Ein nachfolgender Versuch, den Kunden zu löschen, würde einen 404 zurückgeben, da der Kunde nicht mehr vorhanden ist.

Anfrage

DELETE /rest/v1/sales/customers/9ce33474-8690-4a75-ab90-65caa6c3c24e HTTP/1.1
Host: example.com:443
Accept: application/json
X-API-Key: DLOo9sPS5slJEMHpXBFt3g
Content-Type: application/json

Antwort

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 347

{
  "item": {
    "customerId": "9ce33474-8690-4a75-ab90-65caa6c3c24e",
    "companyName": "Jitterbit",
    "contactName": null,
    "contactTitle": null,
    "address": null,
    "city": "Miami Beach",
    "region": "FL",
    "postalCode": "33139",
    "country": "USA",
    "phone": null
  },
  "message": null,
  "validations": [],
  "status": 200
}

Ein benutzerdefiniertes Ereignis für einen Kunden aufrufen

Dieses Beispiel zeigt, wie man ein benutzerdefiniertes Ereignis SendWelcomeEmail aufruft, das auf dem Geschäftsobjekt „Kunde" definiert ist. Das Aufrufen des Ereignisses führt es aus und führt alle damit verbundenen Aktionen aus, wie Datenvorgänge, Benachrichtigungen oder Validierungen. Da dieses Ereignis nur eine Benachrichtigung sendet und den Datensatz nicht ändert, gibt die Antwort die Kundendaten unverändert zurück. Das Segment (SendWelcomeEmail) ist nicht case-sensitiv; (sendwelcomeemail), (SENDWELCOMEEMAIL) und (SendWelcomeEmail) rufen alle dasselbe Ereignis auf.

Anfrage

POST /rest/v1/sales/customers(SendWelcomeEmail)/9ce33474-8690-4a75-ab90-65caa6c3c24e HTTP/1.1
Host: example.com:443
Accept: application/json
X-API-Key: DLOo9sPS5slJEMHpXBFt3g

Antwort

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 347

{
  "item": {
    "customerId": "9ce33474-8690-4a75-ab90-65caa6c3c24e",
    "companyName": "Jitterbit",
    "contactName": null,
    "contactTitle": null,
    "address": null,
    "city": "Miami Beach",
    "region": "FL",
    "postalCode": "33139",
    "country": "USA",
    "phone": null
  },
  "message": null,
  "validations": [],
  "status": 200
}