Einleitung
Auf dieser Seite wird beschrieben, wie Sie die Service Control API v2 verwenden können, um Telemetrieberichte für verwaltete Dienste zu erstellen, die in Service Infrastructure eingebunden sind. Sie richtet sich an Dienstersteller, die ihre Dienste umfassend in Google Cloud integrieren möchten.
Service Infrastructure ist eine grundlegende Plattform, mit der Entwickler APIs und Dienste erstellen, verwalten, sichern und nutzen können. Sie verwendet ein einfaches, allgemeines Dienstnutzungsmodell: Ein Verbraucher nutzt einen von einem Ersteller verwalteten Dienst. Alle Google APIs und Google Cloud APIs verwenden dieses Modell, da sie auch auf Service Infrastructure basieren.
Wenn ein Nutzer auf einen Dienst zugreift, meldet der Dienst relevante Telemetriedaten an die Plattform, damit sowohl der Nutzer als auch der Ersteller den Zugriff beobachten kann. Bei Service Infrastructure wird dieser Prozess als Telemetrieberichterstellung bezeichnet und schließt Analysen, Auditing, Abrechnung, Logging und Monitoring mit ein.
Service Control API Version 2
Die Service Control API v2 bietet eine einfache services.report-Methode, mit der Telemetrieberichte für alle in Service Infrastructure integrierten Dienste bereitgestellt werden. Bei dieser Methode können Sie folgende Aktionen in einem einzigen Methodenaufruf durchführen:
- Analyse
- Audit
- Abrechnung
- Logging
- Überwachung
Wenn ein Dienst Telemetriedaten an die Service Control API meldet, werden die Daten je nach Dienstkonfiguration an den Nutzer, den Ersteller oder beide weitergegeben. Weitere Informationen zum Konfigurieren von Telemetrie finden Sie in den Abschnitten Logging und Monitoring von google.api.Service.
Damit ein Dienst die Service Control API aufrufen kann, muss der Ersteller die Service Control API für das Erstellerprojekt aktivieren und der Aufrufer muss die erforderlichen Berechtigungen für den Dienst haben. Weitere Informationen finden Sie unter Erste Schritte mit Cloud APIs und Zugriffssteuerung für die Service Control API.
Anfrageattribute
Wenn ein Client auf einen Dienst zugreift, muss der Dienst den Zugriff in Form einer Reihe von API-Anfragen modellieren und jede Anfrage mit dem Code AttributeContext beschreiben.
Wenn Sie mit der Service Control API API-Messwerte melden möchten, muss der Dienst die Methode services.report für jede Anfrage mit den folgenden Funktionen aufrufen: Die Service Control API generiert die API-Messwerte und sendet sie an Cloud Monitoring.
| Attribut | Beschreibung | Beispiel |
|---|---|---|
origin.ip |
Die IP-Adresse des Aufrufers. | "1.2.3.4" |
api.service |
Der API-Dienstname. | "endpointsapis.appspot.com" |
api.operation |
Der API-Methodenname. | "google.example.hello.v1.HelloService.GetHello" |
api.version |
Der API-Versionsstring. | "v1" |
api.protocol |
Der API-Protokollname. | "https" |
request.id |
Eine eindeutige Anfrage-ID. | "123e4567-e89b-12d3-a456-426655440000" |
request.time |
Der Anfragezeitstempel. | "2019-07-31T05:20:00Z" |
request.method |
Der Name der HTTP-Methode. | "POST" |
request.scheme |
Das URL-Schema | "https" |
request.host |
Der HTTP-Host-Header | "endpointsapis.appspot.com" |
request.path |
Der URL-Pfad | "/v1/hello" |
response.code |
Der Antwortstatuscode. | 200 |
response.size |
Die Antwortgröße in Byte. | 100 |
response.time |
Der Antwortzeitstempel. | "2019-07-31T05:20:02Z" |
response.backend_latency |
Die Backend-Latenz. | "0.007s" |
Telemetrieberichte erstellen
Sobald Sie Ihre Dienstkonfiguration für die Service Management API bereitgestellt haben und Ihr Dienst bereit ist, Anfragen von Clients zu bearbeiten, können Sie services.report für Ihren bereitgestellten Dienst aufrufen. Rufen Sie services.report auf, um Telemetrieberichte zu erstellen, nachdem Ihr Dienst eine Anfrage erhalten hat.
Wenn Sie schnell mit den Telemetrieberichten experimentieren möchten, können Sie mit dem Befehl gcurl die Methode services.report aufrufen. Die Schritte zur Ersteinrichtung werden unter Erste Schritte mit der Service Control API erläutert.
Das folgende Beispiel zeigt, wie Sie mit dem Befehl gcurl services.report über HTTP aufrufen.
gcurl -d '{
"service_config_id": "latest",
"operations": [{
"origin": {
"ip": "1.2.3.4"
},
"api": {
"service": "endpointsapis.appspot.com",
"operation", "google.example.endpointsapis.v1.Workspaces.GetWorkspace",
"version": "v1",
"protocol": "https"
},
"request": {
"id": "123e4567-e89b-12d3-a456-426655440000",
"size": 50,
"time": "2019-07-31T05:20:00Z",
},
"response": {
"size": 100,
"code": 200,
"time": "2019-07-31T05:20:02Z",
"backend_latency": "0.007s"
},
"destination": {
"region_code": "us-central1"
}
"resource": {
"name": "projects/123/locations/us-central1/workspaces/default"
}
}]
}' https://servicecontrol.googleapis.com/v2/services/endpointsapis.appspot.com:report
Wenn der Vorgang erfolgreich war, ist die Antwort der Methode services.report leer. Wenn der Vorgang fehlgeschlagen ist, enthält der API-Fehler detaillierte Fehlerinformationen.
Weitere Informationen zur Fehlerbehandlung finden Sie unter Leitfaden zum API-Design > Fehler.
Für Produktionsdienste sollten Sie eine der von Google bereitgestellten Clientbibliotheken verwenden, um die Service Control API aufzurufen. Diese Bibliotheken bieten eine hohe Nutzerfreundlichkeit und verarbeiten gängige Funktionen wie die Authentifizierung automatisch. Weitere Informationen erhalten Sie unter Erläuterung der Clientbibliotheken.