Ograniczenia interfejsu API

Interfejs Google Ads API egzekwuje limity operacji interfejsu API, takie jak liczba operacji, które można wysłać w jednym żądaniu modyfikacji. W tabeli poniżej znajdziesz podsumowanie niektórych ważnych limitów, o których warto pamiętać.

Dzienny limit operacji interfejsu API

Dzienny limit wykorzystania interfejsu API zależy od liczby operacji interfejsu API wykonywanych przez projekt Google Cloud. Operacje interfejsu API to łączna suma żądań Search i SearchStream, poszczególnych operacji mutacji i innych żądań usługi. Limity dziennych operacji interfejsu API zależą od poziomu dostępu do interfejsu API w projekcie Google Cloud. Przewodnik po poziomach dostępu i dozwolonych zastosowaniach zawiera szczegółowe informacje o limitach operacji interfejsu API na poszczególnych poziomach dostępu.

Żądania, które naruszają te limity, są odrzucane z błędem: RESOURCE_EXHAUSTED.

Ograniczenia gRPC

Wszystkie biblioteki klienta interfejsu Google Ads API używają gRPC do generowania żądań i odpowiedzi. Domyślnie gRPC ma rozmiar wiadomości 4 MB, ale nasze biblioteki klienta ustawiają maksymalny rozmiar wiadomości na 64 MB, aby zwiększyć wydajność.

Odpowiedzi nie mogą przekraczać tego limitu. Na przykład żądanie wyszukiwania, które zawiera wiele pól, może wygenerować odpowiedź o rozmiarze przekraczającym 64 MB. Aby uniknąć tego limitu, możesz zmniejszyć liczbę wybranych pól lub użyć strumieniowania. W przypadku mutacji wysyłaj mniej operacji na żądanie.

Żądania, które naruszają to ograniczenie, nie wygenerują błędu GoogleAdsError, ale wygenerują błąd RESOURCE_EXHAUSTED (kod gRPC 8 / HTTP 429). Zapoznaj się z listą kodów błędów i komunikatów gRPC.

Żądania modyfikacji

Oprócz tego, że żądanie modyfikacji wlicza się do dziennego limitu operacji użytkownika,nie może ono zawierać więcej niż 10 000 operacji modyfikacji. Żądania, które naruszają to ograniczenie, są odrzucane z błędem: TOO_MANY_MUTATE_OPERATIONS.

Poniżej opisano dodatkowe limity i kwestie dotyczące konkretnych usług i typów żądań.

Wyszukaj żądania

Żądanie Search lub SearchStream jest liczone jako jedna operacja w ramach dziennego limitu operacji użytkownika. Jedno żądanie SearchStream liczy się jako jedna operacja interfejsu API niezależnie od liczby partii.

Żądania z podziałem na strony

Żądania z podziałem na strony (np. żądania zawierające prawidłowy parametr next_page_token) nie są wliczane do dziennego limitu operacji użytkownika. Jednak żądania podziału na strony, które zawierają wygasły lub nieprawidłowy token strony, wygenerują wyjątek i będą wliczane do dziennego limitu operacji.

Więcej informacji o stronicowaniu znajdziesz w artykule Stronicowanie wyników.

Inne typy próśb

Żądanie, które nie jest żądaniem Mutate, Search ani SearchStream, jest liczone jako jedna operacja w ramach dziennego limitu operacji użytkownika.

Oto kilka przykładów takich próśb:

• BatchJobService.ListBatchJobResults
• ConversionUploadService.UploadCallConversions
• ConversionUploadService.UploadClickConversions
• OfflineUserDataJobService.AddOfflineUserDataJobOperations
• OfflineUserDataJobService.CreateOfflineUserDataJob
• UserDataService.UploadUserData

Żądania, które zwracają wyjątki interfejsu API

Żądania odrzucone z błędem GoogleAdsFailure nadal wliczają się do dziennego limitu operacji użytkownika.

Żądania, które nie powiodły się, ale nie zwróciły błędu GoogleAdsFailure, np. z powodu błędu na poziomie sieci, nie będą wliczane do dziennego limitu operacji użytkownika, ponieważ nigdy nie dotarły do usługi. Przykładem może być awaria połączenia sieciowego.

Usługa planowania słów kluczowych

Ze względu na koszty i złożoność te metody usługi Planer słów kluczowych podlegają innym limitom niż pozostałe typy żądań.

• Ograniczenie do 1 żądania na sekundę na ID klienta:

  • KeywordPlanIdeaService.GenerateKeywordIdeas
  • KeywordPlanIdeaService.GenerateKeywordHistoricalMetrics
  • KeywordPlanIdeaService.GenerateKeywordForecastMetrics

  Żądania, które naruszają te ograniczenia, są odrzucane z błędem: RESOURCE_EXHAUSTED.

• 1 zapytanie na sekundę jest obliczane jako 60 żądań na 60 sekund.

• Limit wynosi 2 żądania na sekundę na ID klienta:

  • KeywordPlanIdeaService.GenerateAdGroupThemes

Podczas tworzenia planu słów kluczowych pamiętaj o tych limitach.

Usługa statystyk odbiorców

Te metody w AudienceInsightsService podlegają określonym limitom:

• Limit wynosi około 200 żądań dziennie na identyfikator klienta:
  • AudienceInsightsService.GenerateAudienceCompositionInsights
  • AudienceInsightsService.GenerateSuggestedTargetingInsights
• Limit wynosi 2 żądania na sekundę na projekt Google Cloud:
  • AudienceInsightsService.GenerateTargetingSuggestionMetrics

Usługa przesyłania konwersji

• Limit wynosi 2000 konwersji telefonicznych lub konwersji polegających na kliknięciu na żądanie:

  • ConversionUploadService.UploadCallConversions
  • ConversionUploadService.UploadClickConversions

  Żądania, które naruszają te limity, są odrzucane z błędem: TOO_MANY_CONVERSIONS_IN_REQUEST.

Usługa przesyłania korekt konwersji

• Limit wynosi 2000 dostosowań konwersji na żądanie:

  • ConversionAdjustmentUploadService.UploadConversionAdjustments

  Żądania, które naruszają te limity, są odrzucane z błędem: TOO_MANY_ADJUSTMENTS_IN_REQUEST.

Reguły wartości konwersji

• Limit wynosi 100 000 reguł wartości konwersji na konto.

  Żądania, które naruszają ten limit, są odrzucane z błędem ResourceCountLimitExceededError.ACCOUNT_LIMIT.

Jeśli na koncie istnieje już ConversionValueRuleSet z attachment_type o wartości CUSTOMER, musisz dodać do tego zbioru nowe reguły wartości konwersji, aby stały się aktywne. Jeśli nie ma takiego zestawu reguł wartości konwersji, musisz go utworzyć i dodać do niego reguły wartości konwersji zgodnie z opisem w sekcji Tworzenie zestawów reguł.

Usługi rozliczeniowe i budżetu konta

• Zmiany można wprowadzać tylko na kontach skonfigurowanych do fakturowania miesięcznego.

  Żądania, które naruszają to ograniczenie, są odrzucane z błędem: MUTATE_NOT_ALLOWED.

• W przypadku żądań modyfikacji dozwolona jest tylko 1 operacja.

  Żądania, które naruszają to ograniczenie, są odrzucane z błędem: TOO_MANY_MUTATE_OPERATIONS.

• Pomiędzy zmianami budżetu konta (AccountBudget lub AccountBudgetProposal) na tym samym koncie należy odczekać co najmniej 12 godzin. Wprowadzenie zmian przed upływem 12 godzin może spowodować nieodwracalne błędy, które może rozwiązać tylko opiekun klienta Google Ads.

zaproszenia na konta klientów,

Nowych użytkowników można zapraszać na istniejące konta klientów za pomocą CustomerUserAccessInvitationService. Ta funkcja wysyła e-maile z zaproszeniem do innych użytkowników, więc może być nadużywana. Dlatego obowiązują pewne ograniczenia:

• Użytkownicy nie mogą otrzymać więcej niż 1 oczekującego zaproszenia na to samo konto klienta. Jeśli zostanie wysłana kolejna prośba o wysłanie zaproszenia do użytkownika, który ma już oczekujące zaproszenie, zwrócony zostanie ten błąd: EMAIL_ADDRESS_ALREADY_HAS_PENDING_INVITATION.

• Konta klientów nie mogą mieć więcej niż 70 oczekujących zaproszeń jednocześnie. Jeśli zostanie wysłane żądanie, które spowoduje przekroczenie tej wartości, zwrócony zostanie ten błąd: PENDING_INVITATIONS_LIMIT_EXCEEDED.

Dane użytkownika

Danymi użytkowników zarządza się za pomocą UserDataService i OfflineUserDataJobService.

Każdy obiekt UserData w operacji create lub remove dotyczy jednego użytkownika. Pole user_identifiers w pojedynczym obiekcie UserData może zawierać maksymalnie 20 identyfikatorów. Przekroczenie tego limitu w jednym obiekcie UserData spowoduje błąd OfflineUserDataJobError.TOO_MANY_USER_IDENTIFIERS lub UserDataError.TOO_MANY_USER_IDENTIFIERS.

Postępowanie w przypadku użytkowników, którzy mają więcej niż 20 identyfikatorów

Jeśli jeden użytkownik ma więcej niż 20 identyfikatorów, które chcesz przesłać, musisz rozdzielić te identyfikatory między kilka obiektów UserData. Aby mieć pewność, że Google może powiązać wszystkie te identyfikatory z tym samym użytkownikiem, każdy obiekt UserData tego użytkownika musi zawierać co najmniej 1 wspólny element user_identifier, np. ten sam hashed_email, hashed_phone_number lub third_party_user_id. Google używa tych udostępnionych identyfikatorów, aby połączyć i scalić informacje z oddzielnych operacji UserData z odpowiednim profilem użytkownika.

Jeśli korzystasz z informacji umożliwiających identyfikację, takich jak zaszyfrowane adresy e-mail lub numery telefonów, upewnij się, że są one znormalizowane i zaszyfrowane zgodnie z wymaganiami interfejsu Google Ads API (SHA-256, małe litery, bez spacji), aby zapobiec błędom łączenia.

Jeśli na przykład użytkownik ma 30 adresów e-mail, możesz wysłać 2 obiekty UserData, które mają wspólny identyfikator third_party_user_id (umieszczając identyfikator thirdPartyUserId i adresy e-mail od 1 do 19 w pierwszym obiekcie, aby nie przekroczyć limitu 20 identyfikatorów, a identyfikator thirdPartyUserId i adresy e-mail od 20 do 30 w drugim):

{
  "userIdentifiers": [
    { "thirdPartyUserId": "user123" },
    { "hashedEmail": "SHA256_OF_EMAIL_1" },
    // Hashed emails 2 through 18 are omitted here.
    { "hashedEmail": "SHA256_OF_EMAIL_19" }
  ]
}

{
  "userIdentifiers": [
    { "thirdPartyUserId": "user123" },
    { "hashedEmail": "SHA256_OF_EMAIL_20" },
    // Hashed emails 21 through 29 are omitted here.
    { "hashedEmail": "SHA256_OF_EMAIL_30" }
  ]
}

Łączny limit user_identifiers we wszystkich operacjach w jednym AddOfflineUserDataJobOperationsRequest wynosi 100 000 (OfflineUserDataJob może akceptować wiele wywołań AddOfflineUserDataJobOperationsRequest, maksymalnie 1 000 000 operacji na zadanie). W przypadku przesyłania synchronicznego za pomocą UploadUserDataRequest (UserDataService.UploadUserData) każde żądanie jest ograniczone do maksymalnie 10 operacji i 100 user_identifiers w całym żądaniu.

Inne rodzaje limitów

Pole powtarzane, np. lista operacji, które zawiera zbyt wiele elementów w żądaniu, może spowodować błąd: REQUEST_SIZE_LIMIT_EXCEEDED. Ten sam komunikat o błędzie może też być spowodowany innymi problemami.

Jeśli napotkasz to ograniczenie i wysyłasz żądania, które używają pola powtarzanego, spróbuj zmniejszyć liczbę elementów w tym polu, dzieląc listę operacji na kilka żądań modyfikacji.

Podczas tworzenia zapytania GAQL maksymalna liczba elementów w klauzuli IN wynosi 20 000. Jeśli przekroczysz ten limit, zwrócony zostanie błąd FILTER_HAS_TOO_MANY_VALUES.