Bestellungen anlegen, Rechnungen freigeben und bezahlen und den Workspace einrichten.

API-Referenz

Cloud-Verbindungen

Schreibgeschützte Verbindungen zur Abrechnung Ihrer Cloud-Anbieter-Konten.

Mehr zu dieser Ressource

Eine Cloud-Verbindung gibt Pleaxy Lesezugriff auf die Abrechnung eines Kontos bei einem Cloud-Anbieter, über einen Zugang, den Sie in Ihrem eigenen Konto mit einem Setup-Skript anlegen. AWS verwendet eine kontoübergreifende IAM-Rolle, Google Cloud Workload Identity Federation und Azure eine föderierte Anmeldeinformation, jeweils für kurzlebige Sitzungen, ohne dass ein langlebiger Schlüssel gespeichert wird. Oracle Cloud verwendet einen API-Signaturschlüssel, den Pleaxy für die Verbindung erzeugt; Sie laden nur dessen öffentlichen Schlüssel hoch. Das Verbinden besteht aus zwei Aufrufen: init gibt die Werte zurück, die das Setup-Skript braucht, dann prüft CreateCloudConnection den Zugang und schließt die Verbindung ab. Nur die Person, die ein Setup gestartet hat, kann es abschließen oder abbrechen.

Endpunkte

GET…/cloud-connections
POST…/cloud-connections/aws/init
POST…/cloud-connections/{provider}/init
POST…/cloud-connections/azure/discover
POST…/cloud-connections
POST…/cloud-connections/{id}/sync
DELETE…/cloud-connections/{id}
POST…/cloud-connections/{provider}/supplier

Cloud-Verbindungen auflisten

Listet die Cloud-Verbindungen des Workspace auf.

GET/v1/workspaces/{regionId}/cloud-connections

Rückgabe

200 OK mit dem in der Antwort gezeigten Objekt.

Weitere Details

Listet die Cloud-Verbindungen des Workspace auf, einschließlich noch laufender Setups (status pending). Gibt nie Geheimnisse oder die beim Setup verwendeten Kennungen zurück (Rollen-ARN, externe ID, Dienstkonto, OCIDs, Tenant- oder App-IDs).

Antwortfelder

dataSourcesArray<"invoices" | "current_cost">
Was Pleaxy lesen darf: abgeschlossene Rechnungen und/oder die Kosten seit Monatsbeginn. Fehlt das Feld, beides.
lastSyncStatus"ok" | "error" | "throttled" | "never"
Wie die letzte Abrechnungssynchronisierung verlief. lastSyncErrorCode gibt an, warum eine fehlgeschlagen ist: throttled, access_revoked, platform_config, data_not_enabled oder unknown.

Fehler

401 Unauthorized - Es wurden keine Zugangsdaten übermittelt, oder der Bearer-Token bzw. der X-Api-Key-Wert fehlt, ist ungültig, abgelaufen oder widerrufen.
403 Forbidden - Der Bearer-Token oder API-Schlüssel des Aufrufers gewährt keinen Zugriff auf diesen Workspace (regionId) oder hat nicht die erforderliche Rolle.

GET /v1/workspaces/{regionId}/cloud-connections

Anfrage

curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/cloud-connections" \
  -H "X-Api-Key: $PLEAXY_API_KEY"

Antwort · 200 OK

[
   {
      "id": "string",
      "provider": "aws" | "gcp" | "azure" | "oci",
      "accountLabel": "string",
      "detail": "string",
      "spend": number,
      "status": "connected" | "pending" | "error",
      "connectedAt": "string",
      "awsAccountId": "string",
      "dataSources": [ "invoices" | "current_cost" ],
      "gcp": { "billingAccountId": "string", "providerId": "string" },
      "oci": { "homeRegion": "string", "keyFingerprint": "string" },
      "azure": { "scopeDisplayName": "string", "agreementType": "string" },
      "lastSyncedAt": "string",
      "lastSyncStatus": "ok" | "error" | "throttled" | "never",
      "lastSyncError": "string",
      "lastSyncErrorCode": "throttled" | "access_revoked" | "platform_config" | "data_not_enabled" | "unknown"
   }
]

AWS-Cloud-Verbindung initialisieren

Startet das Verbinden eines AWS-Kontos.

POST/v1/workspaces/{regionId}/cloud-connections/aws/init

Rückgabe

201 Created mit dem in der Antwort gezeigten Objekt.

Weitere Details

Startet das Verbinden eines AWS-Kontos und gibt die Werte für das Setup-Skript zurück (CloudFormation, CDK oder CLI), das eine schreibgeschützte IAM-Rolle in Ihrem Konto anlegt. Ein erneuter Aufruf gibt Ihr eigenes noch nicht abgeschlossenes Setup mit derselben externen ID zurück. Erwartet keinen Body.

Antwortfelder

connectionIdstring
Übergeben Sie es an CreateCloudConnection als awsConnectionId.
cloudFormationTemplateUrlstring
Fehlt, wenn diese Installation keine CloudFormation-Vorlage veröffentlicht; verwenden Sie dann das CDK- oder CLI-Skript.

Fehler

401 Unauthorized - Es wurden keine Zugangsdaten übermittelt, oder der Bearer-Token bzw. der X-Api-Key-Wert fehlt, ist ungültig, abgelaufen oder widerrufen.
403 Forbidden - Der Bearer-Token oder API-Schlüssel des Aufrufers gewährt keinen Zugriff auf diesen Workspace (regionId) oder hat nicht die erforderliche Rolle.

POST /v1/workspaces/{regionId}/cloud-connections/aws/init

Anfrage

curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/cloud-connections/aws/init" \
  -H "X-Api-Key: $PLEAXY_API_KEY"

Antwort · 201 Created

{
   "connectionId": "string",
   "platformAwsAccountId": "string",
   "externalId": "string",
   "cloudFormationTemplateUrl": "string"
}

Cloud-Verbindung initialisieren

Startet das Verbinden eines Google Cloud-, Azure- oder Oracle Cloud-Kontos.

POST/v1/workspaces/{regionId}/cloud-connections/{provider}/init

Parameter

provider"gcp" | "azure" | "oci"Pflicht
Der zu verbindende Anbieter.

Rückgabe

201 Created mit dem in der Antwort gezeigten Objekt.

Weitere Details

Dasselbe wie InitAwsCloudConnection für Google Cloud, Azure oder Oracle Cloud: gibt die verbindungsspezifischen Werte zurück, die das Setup-Skript des jeweiligen Anbieters festschreibt, einschließlich einer connectionId für CreateCloudConnection (als gcpConnectionId, azureConnectionId oder ociConnectionId). Ein erneuter Aufruf gibt Ihr eigenes noch nicht abgeschlossenes Setup zurück. Erwartet keinen Body.

Antwortfelder

gcpobject
connectionId, platformAwsAccountId, federationRoleArn, expectedSubject, poolId und providerId: die Werte der Workload Identity Federation, die das Setup-Skript festschreibt.
azureobject
connectionId, issuer, subject, audience, appDisplayName und credentialName: die föderierte Anmeldeinformation, die das Setup-Skript für Ihre App anlegt.
ociobject
connectionId, publicKeyPem, fingerprint und regions: der öffentliche Schlüssel, der beim Benutzer pleaxy-billing hochgeladen wird, und die Home-Regionen zur Auswahl.

Fehler

404 Not Found - Der Live-Connector dieses Anbieters ist in dieser Installation nicht aktiviert ("Real connections to this provider aren't switched on.").
401 Unauthorized - Es wurden keine Zugangsdaten übermittelt, oder der Bearer-Token bzw. der X-Api-Key-Wert fehlt, ist ungültig, abgelaufen oder widerrufen.
403 Forbidden - Der Bearer-Token oder API-Schlüssel des Aufrufers gewährt keinen Zugriff auf diesen Workspace (regionId) oder hat nicht die erforderliche Rolle.

POST /v1/workspaces/{regionId}/cloud-connections/{provider}/init

Anfrage

curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/cloud-connections/{provider}/init" \
  -H "X-Api-Key: $PLEAXY_API_KEY"

Antwort · 201 Created

{
   "connectionId": "string",
   ...the provider's setup values
}

Azure-Abrechnungsbereiche ermitteln

Listet die Azure-Abrechnungsprofile auf, die Sie verbinden können.

POST/v1/workspaces/{regionId}/cloud-connections/azure/discover

Body

azureConnectionIdstringPflicht
connectionId aus InitCloudConnection.
azureTenantIdstringPflicht
Der Microsoft Entra-Tenant, in dem die App registriert wurde (GUID).
azureClientIdstringPflicht
Die Anwendungs-(Client-)ID der App-Registrierung (GUID).
azureBillingAccountIdstringPflicht
Die ID des Abrechnungskontos der Microsoft Customer Agreement (<guid>:<guid>_YYYY-MM-DD).
azureBillingProfileIdstringPflicht
Die ID des Abrechnungsprofils, für das die App die Rolle Billing profile reader hat.

Rückgabe

201 Created mit dem in der Antwort gezeigten Objekt.

Weitere Details

Nur Azure, zwischen init und CreateCloudConnection: prüft die Tenant-ID und die App-(Client-)ID, die das Setup-Skript ausgegeben hat, und liest das angegebene Abrechnungskonto und Abrechnungsprofil der Microsoft Customer Agreement, damit Sie das zu verbindende Profil auswählen können. Nur die Person, die das Setup gestartet hat, darf dies aufrufen, und es zählt zum selben Versuchslimit und zur selben Wartezeit wie CreateCloudConnection.

Fehler

404 Not Found - Der Live-Connector für Azure ist nicht aktiviert, oder das Setup existiert nicht mehr oder wurde von jemand anderem gestartet.
429 Too Many Requests - Zu früh erneut versucht; retryAfterSeconds gibt an, wann es wieder geht.
401 Unauthorized - Es wurden keine Zugangsdaten übermittelt, oder der Bearer-Token bzw. der X-Api-Key-Wert fehlt, ist ungültig, abgelaufen oder widerrufen.
403 Forbidden - Der Bearer-Token oder API-Schlüssel des Aufrufers gewährt keinen Zugriff auf diesen Workspace (regionId) oder hat nicht die erforderliche Rolle.

POST /v1/workspaces/{regionId}/cloud-connections/azure/discover

Anfrage

curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/cloud-connections/azure/discover" \
  -H "X-Api-Key: $PLEAXY_API_KEY"

Antwort · 201 Created

{
   "scopes": [
      { "billingAccountId": "string", "billingProfileId": "string", "displayName": "string", "billingAccountDisplayName": "string", "agreementType": "string" }
   ]
}

Cloud-Verbindung anlegen

Schließt das Verbinden eines Cloud-Kontos ab.

POST/v1/workspaces/{regionId}/cloud-connections

Body

provider"aws" | "gcp" | "azure" | "oci"Pflicht
Der zu verbindende Cloud-Anbieter.
accountLabelstringPflicht
Ihre Bezeichnung für dieses Konto, z. B. "Production payer".
dataSourcesArray<"invoices" | "current_cost">
Was Pleaxy lesen darf: abgeschlossene Rechnungen und/oder die Kosten seit Monatsbeginn. Ohne Angabe: beides. Pleaxy ruft den Anbieter nie für eine Quelle auf, die Sie weglassen, auch nicht bei einer manuellen Synchronisierung. Manche Anbieter berechnen Abfragen der aktuellen Kosten pro Anfrage (AWS Cost Explorer).
supplierContactEmailstring
Optionaler Ansprechpartner beim Anbieter für den damit angelegten Lieferanteneintrag.
awsConnectionIdstring
AWS, erforderlich: connectionId aus InitAwsCloudConnection.
roleArnstring
AWS, erforderlich: die vom Setup-Skript angelegte IAM-Rolle, arn:aws:iam::<12-digit account>:role/<name>.
gcpConnectionIdstring
Google Cloud: connectionId aus InitCloudConnection.
gcpProjectNumberstring
Google Cloud: die Nummer des Projekts für den Abrechnungsexport (Ziffern).
gcpServiceAccountEmailstring
Google Cloud: das Dienstkonto, das das Setup-Skript in diesem Projekt angelegt hat.
gcpExportTablestring
Google Cloud: die Standardtabelle für den Export der Nutzungskosten, project.dataset.gcp_billing_export_v1_XXXXXX_XXXXXX_XXXXXX.
azureConnectionIdstring
Azure: connectionId aus InitCloudConnection.
azureBillingAccountIdstring
Azure: das Abrechnungskonto des mit DiscoverAzureBillingScopes ausgewählten Profils.
azureBillingProfileIdstring
Azure: das mit DiscoverAzureBillingScopes ausgewählte Abrechnungsprofil.
ociConnectionIdstring
Oracle Cloud: connectionId aus InitCloudConnection.
ociTenancyOcidstring
Oracle Cloud: die Tenancy-OCID (ocid1.tenancy.oc1..…).
ociUserOcidstring
Oracle Cloud: die OCID des Benutzers pleaxy-billing, den das Setup-Skript angelegt hat.
ociHomeRegionstring
Oracle Cloud: die Home-Region der Tenancy, eine der von InitCloudConnection aufgelisteten.
detailstring
Nur für eine Demo-Verbindung, bei der der Live-Connector eines Anbieters deaktiviert ist: eine Kontokennung, die Sie eingeben. Eine Live-Verbindung liest sie stattdessen beim Anbieter aus.

Rückgabe

201 Created mit dem in der Antwort gezeigten Objekt.

Weitere Details

Schließt ein mit init gestartetes Setup ab: Pleaxy prüft, ob es Ihre Abrechnung mit dem vom Setup-Skript angelegten Zugang lesen kann, markiert die Verbindung dann als verbunden und fügt den Anbieter zu Ihren Lieferanten hinzu. Senden Sie die Felder für Ihren Anbieter. Nur die Person, die das Setup gestartet hat, darf es abschließen. Abhängig vom Plan der Region: Der Free-Plan erlaubt einen verbundenen Anbieter.

Fehler

400 Bad Request - Die Validierung ist fehlgeschlagen; Pleaxy konnte die Abrechnung mit dem angegebenen Zugang nicht lesen (der Code nennt den Anbieter, z. B. CLOUD_VERIFY_FAILED); zu viele fehlgeschlagene Versuche für dieses Setup, beginnen Sie also erneut mit init (Code endet auf ATTEMPTS_EXHAUSTED); oder der Plan der Region hat sein Limit an verbundenen Anbietern erreicht (Free: 1).
404 Not Found - Das Setup existiert nicht mehr, ist abgelaufen oder wurde von jemand anderem gestartet.
409 Conflict - Dieses Setup oder dasselbe Abrechnungskonto bzw. derselbe Abrechnungsbereich ist bereits verbunden.
429 Too Many Requests - Nach einem fehlgeschlagenen Versuch zu früh erneut versucht; retryAfterSeconds gibt an, wann es wieder geht.
401 Unauthorized - Es wurden keine Zugangsdaten übermittelt, oder der Bearer-Token bzw. der X-Api-Key-Wert fehlt, ist ungültig, abgelaufen oder widerrufen.
403 Forbidden - Der Bearer-Token oder API-Schlüssel des Aufrufers gewährt keinen Zugriff auf diesen Workspace (regionId) oder hat nicht die erforderliche Rolle.

POST /v1/workspaces/{regionId}/cloud-connections

Anfrage

curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/cloud-connections" \
  -H "X-Api-Key: $PLEAXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d @body.json

body.json

{
   "provider": "aws",
   "accountLabel": "string",
   "awsConnectionId": "string",
   "roleArn": "string",
   "dataSources": [ "invoices", "current_cost" ]
}

Antwort · 201 Created

{
   "id": "string",
   "provider": "aws" | "gcp" | "azure" | "oci",
   "accountLabel": "string",
   "detail": "string",
   "spend": number,
   "status": "connected" | "pending" | "error",
   "connectedAt": "string",
   "awsAccountId": "string",
   "dataSources": [ "invoices" | "current_cost" ],
   "gcp": { "billingAccountId": "string", "providerId": "string" },
   "oci": { "homeRegion": "string", "keyFingerprint": "string" },
   "azure": { "scopeDisplayName": "string", "agreementType": "string" },
   "lastSyncedAt": "string",
   "lastSyncStatus": "ok" | "error" | "throttled" | "never",
   "lastSyncError": "string",
   "lastSyncErrorCode": "throttled" | "access_revoked" | "platform_config" | "data_not_enabled" | "unknown"
}

Cloud-Verbindung synchronisieren

Synchronisiert die Abrechnungsdaten eines Cloud-Kontos sofort.

POST/v1/workspaces/{regionId}/cloud-connections/{id}/sync

Parameter

idstringPflicht
Die ID der Cloud-Verbindung.

Rückgabe

201 Created mit dem in der Antwort gezeigten Objekt.

Weitere Details

Synchronisiert die Abrechnungsdaten eines verbundenen Kontos sofort und liest dabei nur die dataSources der Verbindung. Einmal alle 15 Minuten pro Verbindung. Erwartet keinen Body.

Fehler

400 Bad Request - Vor weniger als 15 Minuten synchronisiert ("…try again in {n}m."), oder die Verbindung ist kein verbundenes Konto mit aktivem Abrechnungs-Connector.
404 Not Found - Im Workspace gibt es keine solche Verbindung, oder sie wurde getrennt.
401 Unauthorized - Es wurden keine Zugangsdaten übermittelt, oder der Bearer-Token bzw. der X-Api-Key-Wert fehlt, ist ungültig, abgelaufen oder widerrufen.
403 Forbidden - Der Bearer-Token oder API-Schlüssel des Aufrufers gewährt keinen Zugriff auf diesen Workspace (regionId) oder hat nicht die erforderliche Rolle.

POST /v1/workspaces/{regionId}/cloud-connections/{id}/sync

Anfrage

curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/cloud-connections/{id}/sync" \
  -H "X-Api-Key: $PLEAXY_API_KEY"

Antwort · 201 Created

{
   "id": "string",
   "provider": "aws" | "gcp" | "azure" | "oci",
   "accountLabel": "string",
   "detail": "string",
   "spend": number,
   "status": "connected" | "pending" | "error",
   "connectedAt": "string",
   "awsAccountId": "string",
   "dataSources": [ "invoices" | "current_cost" ],
   "gcp": { "billingAccountId": "string", "providerId": "string" },
   "oci": { "homeRegion": "string", "keyFingerprint": "string" },
   "azure": { "scopeDisplayName": "string", "agreementType": "string" },
   "lastSyncedAt": "string",
   "lastSyncStatus": "ok" | "error" | "throttled" | "never",
   "lastSyncError": "string",
   "lastSyncErrorCode": "throttled" | "access_revoked" | "platform_config" | "data_not_enabled" | "unknown"
}

Cloud-Verbindung trennen

Trennt ein Cloud-Konto.

DELETE/v1/workspaces/{regionId}/cloud-connections/{id}

Parameter

idstringPflicht
Die ID der Cloud-Verbindung.

Rückgabe

200 OK mit dem in der Antwort gezeigten Objekt.

Weitere Details

Trennt ein Cloud-Konto oder bricht ein laufendes Setup ab. Löscht die Verbindung mit allem, was Pleaxy dafür gespeichert hat (bei Oracle Cloud ihren verschlüsselten API-Schlüssel), und hält fest, wer sie getrennt hat. Bei Oracle Cloud nennt die Antwort den Schlüssel-Fingerprint, der beim Benutzer pleaxy-billing zu löschen ist. Entfernen Sie den Zugang auch in Ihrem eigenen Konto.

Angemeldete Sitzung mit 'edit'-Zugriff auf Lieferanten; ein API-Schlüssel erhält 403. Ein laufendes Setup kann nur die Person abbrechen, die es gestartet hat.

Fehler

403 Forbidden - Der Aufrufer ist ein API-Schlüssel, hat kein 'edit' für Lieferanten oder bricht das Setup einer anderen Person ab ("Only the person who started this setup can cancel it.").
404 Not Found - Im Workspace gibt es keine solche Verbindung.
401 Unauthorized - Es wurden keine Zugangsdaten übermittelt, oder der Bearer-Token bzw. der X-Api-Key-Wert fehlt, ist ungültig, abgelaufen oder widerrufen.

DELETE /v1/workspaces/{regionId}/cloud-connections/{id}

Anfrage

curl -X DELETE "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/cloud-connections/{id}" \
  -H "X-Api-Key: $PLEAXY_API_KEY"

Antwort · 200 OK

{
   "id": "string",
   "provider": "aws" | "gcp" | "azure" | "oci",
   "ociKeyFingerprint": "string"
}

Cloud-Anbieter als Lieferant hinzufügen

Fügt einen Cloud-Anbieter als Lieferanten hinzu, ohne ein Konto zu verbinden.

POST/v1/workspaces/{regionId}/cloud-connections/{provider}/supplier

Parameter

provider"aws" | "gcp" | "azure" | "oci"Pflicht
Der hinzuzufügende Anbieter.

Rückgabe

201 Created mit dem in der Antwort gezeigten Objekt.

Weitere Details

Fügt einen Cloud-Anbieter Ihrer Lieferantenliste hinzu, ohne ein Konto zu verbinden, sodass Sie POs an ihn ausstellen können. Vom Anbieter wird nichts gelesen. Gibt den vorhandenen Lieferanteneintrag des Anbieters zurück, falls es einen gibt, und ein späteres Verbinden verknüpft mit demselben Eintrag. Erfordert 'create'-Zugriff auf Lieferanten. Erwartet keinen Body.

Fehler

404 Not Found - Unbekannter Anbieter.
409 Conflict - Code SUPPLIER_ALREADY_LISTED: Für einen Lieferanten mit diesem Namen läuft bereits ein Onboarding, oder es ist freigegeben.
401 Unauthorized - Es wurden keine Zugangsdaten übermittelt, oder der Bearer-Token bzw. der X-Api-Key-Wert fehlt, ist ungültig, abgelaufen oder widerrufen.
403 Forbidden - Der Bearer-Token oder API-Schlüssel des Aufrufers gewährt keinen Zugriff auf diesen Workspace (regionId) oder hat nicht die erforderliche Rolle.

POST /v1/workspaces/{regionId}/cloud-connections/{provider}/supplier

Anfrage

curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/cloud-connections/{provider}/supplier" \
  -H "X-Api-Key: $PLEAXY_API_KEY"

Antwort · 201 Created

{
   "id": "string",
   "buyerOrgId": "string",
   "supplierName": "string",
   "cloudProvider": "aws" | "gcp" | "azure" | "oci",
   "status": "pending_invite" | "invited" | "in_progress" | "submitted" | "approved" | "rejected",
   "createdAt": "string"
}