Best Practices für die Compute Engine API

Dieses Dokument beschreibt die empfohlenen Best Practices für die Verwendung der Compute Engine API und richtet sich an Nutzer, die bereits mit ihr vertraut sind. Wenn Sie Anfänger sind, informieren Sie sich über die Voraussetzungen und die Verwendung der Compute Engine API.

Wenn Sie diese Best Practices befolgen, können Sie Zeit sparen, Fehler vermeiden und die Auswirkungen von Ratenkontingenten mindern.

Clientbibliotheken verwenden

Clientbibliotheken sind die empfohlene Methode für den programmatischen Zugriff auf die Compute Engine API. Clientbibliotheken bieten Code, mit dem Sie über gängige Programmiersprachen auf die API zugreifen können. Dadurch können Sie Zeit sparen und die Leistung Ihres Codes verbessern.

Weitere Informationen zu Compute Engine-Clientbibliotheken und Best Practices für Clientbibliotheken.

REST-Anfragen mit der Cloud Console generieren

Generieren Sie beim Erstellen einer Ressource die REST-Anfrage mithilfe der Ressourcenerstellungsseiten oder Detailseiten in der Google Cloud Console. Die Verwendung einer generierten REST-Anfrage spart Zeit und hilft, Syntaxfehler zu vermeiden.

Weitere Informationen zum Generieren von REST-Anfragen

Auf Fertigstellung von Vorgängen warten

Gehen Sie nicht davon aus, dass ein Vorgang – eine API-Anfrage, mit der eine Ressource geändert wird – abgeschlossen oder erfolgreich ist. Verwenden Sie stattdessen eine wait-Methode für die Ressource Operation, um zu prüfen, ob der Vorgang abgeschlossen ist. Sie müssen keine Anfrage prüfen, die keine Ressourcen ändert, z. B. eine Leseanfrage mit einem HTTP-Verb GET, da die API-Antwort bereits angibt, ob die Anfrage erfolgreich. Daher gibt die Compute Engine API für diese Anfragen keine Operation-Ressourcen zurück.

Wenn eine API-Anfrage erfolgreich initiiert wurde, wird der HTTP-Statuscode 200 zurückgegeben. Obwohl der 200 angezeigt wird, dass der Server die API-Anfrage erfolgreich empfangen hat, gibt dieser Statuscode nicht an, ob der angeforderte Vorgang erfolgreich abgeschlossen wurde oder nicht. Sie können beispielsweise eine 200 erhalten, aber der Vorgang ist möglicherweise noch nicht abgeschlossen oder fehlgeschlagen.

Jede Anfrage zum Erstellen, Aktualisieren oder Löschen eines Vorgangs mit langer Ausführungszeit gibt eine Operation-Ressource zurück, die erfasst den Status dieser Anfrage. Ein Vorgang ist abgeschlossen, wenn das Feld status der Ressource Operation DONE ist. Verwenden Sie zum Prüfen des Status die Methode wait, die mit dem Bereich der zurückgegebenen Operation-Ressource übereinstimmt:

Die Methode wait wird zurückgegeben, wenn der Vorgang abgeschlossen ist oder sich die Anfrage der Frist von zwei Minuten nähert. Vermeiden Sie bei der Verwendung der Methode wait kurze Abfrageintervalle, Ihre Clients also kontinuierlich Anfragen an den Server senden, ohne auf eine Antwort zu warten. Verwenden Sie die Methode wait in einer Wiederholungsschleife mit dem exponentiellen Backoff, um den Status Ihrer Anfrage zu prüfen, anstatt die Methode get mit kurzen Abfragen für die Operation-Ressource zu verwenden. Dies trägt dazu bei, Ihre Ratenkontingente beizubehalten und die Latenz zu reduzieren.

Weitere Informationen und Beispiele zur Verwendung der Methode wait finden Sie unter API-Antworten verarbeiten

Informationen zum Prüfen des Status eines angeforderten Vorgangs finden Sie unter Vorgangsstatus prüfen.

Berücksichtigen Sie während des Wartens auf einen Vorgang die Mindestaufbewahrungsdauer für Vorgänge, da abgeschlossene Vorgänge nach diesem Zeitraum aus der Datenbank entfernt werden können.

Listenergebnisse paginieren

Wenn Sie eine Listenmethode verwenden (z. B. eine *.list-, eine *.aggregatedList- oder eine andere Methode, die eine Liste zurückgibt), paginieren Sie die Ergebnisse nach Möglichkeit, damit Sie die gesamte Antwort lesen können. Ohne Paginierung können Sie maximal die ersten 500 Elemente empfangen, wie durch den Abfrageparameter maxResults festgelegt.

Weitere Informationen zur Paginierung in Google Cloud finden Sie unter Paginierung. Weitere Informationen und Beispiele finden Sie in der Referenzdokumentation für die Listenmethode, die Sie verwenden möchten, z. B. instances.list.

Sie können auch Cloud-Clientbibliotheken verwenden, um die Paginierung zu verarbeiten.

Clientseitige Listenfilter zur Vermeidung von Kontingentfehlern verwenden

Wenn Sie Filter mit den Methoden *.list oder *.aggregatedList verwenden, fallen zusätzliche Kontingentgebühren an, wenn mehr als 10.000 gefilterte Ressourcen aus den Anfragen vorhanden sind. Weitere Informationen finden Sie unter filtered_list_cost_overhead unter „Ratenkontingente“.

Wenn Ihr Projekt diese Ratenbegrenzung überschreitet, erhalten Sie einen 403-Fehler mit dem Grund rateLimitExceeded. Verwenden Sie clientseitige Filter für die Listenanfragen, um diesen Fehler zu vermeiden.

Fehlercodes nutzen, keine Fehlermeldungen

Google APIs müssen die von google.rpc.Code definierten kanonischen Fehlercodes verwenden. Fehlermeldungen können jedoch ohne Vorankündigung geändert werden. Fehlermeldungen sind im Allgemeinen für Entwickler gedacht, nicht für Programme.

Weitere Informationen zu API-Fehlern.

Clientseitige Wiederholungsversuche minimieren, um Ratenkontingente einzuhalten

Minimieren Sie die Anzahl der clientseitigen Wiederholungsversuche für ein Projekt, um rateLimitExceeded-Fehler zu vermeiden und die Auslastung Ihrer Ratenkontingente zu maximieren. Die folgenden Praktiken können Ihnen dabei helfen, die Ratenkontingente für Ihre Projekte beizubehalten:

  • Vermeiden Sie kurze Abfrageintervalle.
  • Verwenden Sie Bursting sparsam und selektiv.
  • Führen Sie Ihre Aufrufe immer in einer Wiederholungsschleife mit exponentiellem Backoff aus.
  • Verwenden Sie eine clientseitige Ratenbegrenzung.
  • Teilen Sie Ihre Anwendungen auf mehrere Projekte auf.

Kurze Abfrageintervalle vermeiden

Vermeiden Sie kurze Abfrageintervalle, bei denen Ihre Clients fortlaufend Anfragen an den Server senden, ohne auf Antwort zu warten. Bei kurzen Abfrageintervallen wird es schwieriger, fehlerhafte Anfragen abzufangen, die keine nützlichen Daten zurückgeben, aber dennoch auf Ihr Kontingent angerechnet werden.

Anstelle von kurzen Abfragen sollten Sie auf die Fertigstellung von Vorgängen warten.

Bursting sparsam und selektiv verwenden

Verwenden Sie Bursting sparsam und selektiv. Bursting bedeutet, dass ein bestimmter Client in kurzer Zeit viele API-Anfragen ausführen darf. Normalerweise ist Bursting eine Maßnahme in außergewöhnlichen Situationen, z. B. wenn Ihre Anwendung mehr Traffic als gewöhnlich verarbeiten muss. Bursting führt zu einem schnellen Verbrauch der Ratenkontingente. Sie sollten diese Funktion nur verwenden, wenn es unbedingt notwendig ist.

Wenn Bursting erforderlich ist, verwenden Sie nach Möglichkeit dedizierte Batch-APIs, z. B. die Bulk Instance API oder verwalteten Instanzgruppen.

Weitere Informationen zu Batchanfragen

Aufrufe immer in einer Wiederholungsschleife mit exponentiellem Backoff ausführen

Verwenden Sie exponentielles Backoff, um den Abstand zwischen den Anfragen stufenweise zu erhöhen, sobald das Zeitlimit oder das Ratenkontingent erreicht wurde.

Jede Wiederholungsschleife sollte einen exponentiellen Backoff haben, der dafür sorgt, dass häufige Wiederholungsversuche die Anwendung nicht überlasten und Ihre Ratenkontingente nicht überschreiten. Andernfalls riskieren Sie, dass sich alle anderen Systeme im selben Projekt negativ auswirken.

Wenn Sie eine Wiederholungsschleife für einen fehlgeschlagenen Vorgang benötigen, weil das Ratenkontingent erreicht ist, sollte Ihre exponentielle Backoff-Strategie genügend Zeit zwischen den Wiederholungen haben, damit der Kontingent-Bucket wieder aufgefüllt werden kann (normalerweise jede Minute).

Wenn Sie hingegen eine Wiederholungsschleife benötigen, wenn das Warten auf einen Vorgang das Zeitlimit erreicht, sollte das maximale Intervall Ihrer exponentiellen Backoff-Strategie die Mindestaufbewahrungsdauer für Vorgänge nicht überschreiten. Andernfalls erhalten Sie möglicherweise den Fehler Not Found.

Ein Beispiel für die Implementierung eines exponentiellen Backoffs finden Sie unter Exponentieller Backoff-Algorithmus für die Identity and Access Management API.

Clientseitige Ratenbegrenzung verwenden

Verwenden Sie eine clientseitige Ratenbegrenzung. Damit wird ein künstliches Limit definiert, das der betreffende Client nicht überschreiten darf. Er hat dann nur ein bestimmtes Kontingent zur Verfügung. Dadurch wird verhindert, dass ein einzelner Client das gesamtes Kontingent verbraucht.

Anwendungen auf mehrere Projekte aufteilen

Durch die Aufteilung der Anwendungen auf mehrere Projekte kann die Anzahl der Anfragen für Ihre Kontingent-Buckets minimiert werden. Da Kontingente auf Projektebene angewendet werden, können Sie Ihre Anwendungen so aufteilen, dass jede Anwendung über einen eigenen Kontingent-Bucket verfügt.

Zusammenfassung der Checkliste

In der folgenden Checkliste sind die Best Practices für die Verwendung der Compute Engine API zusammengefasst.

Nächste Schritte