Begrenzungen und Best Practices

Die Facebook Insights API stellt Performance-Daten aus Facebook-Marketingkampagnen bereit. Um die System-Performance und -stabilität zu gewährleisten, bieten wir Schutzmaßnahmen an, damit wir Systemressourcen gleichmäßig auf Apps aufteilen können. Änderungen an allen im Folgenden von uns beschriebenen Richtlinien sind vorbehalten.

Begrenzungen für Daten pro Aufruf

Wir begrenzen die Daten pro Aufruf, um zu verhindern, dass eine Abfrage zu viele Daten abruft und das System somit überlastet. Es gibt zwei Arten von Datenbegrenzungen:

1. Anzahl der Zeilen in der Antwort und
2. Anzahl der erforderlichen Datenpunkte für die Berechnung der Summe (wie eine Summenzeile).

Diese Begrenzungen gelten sowohl für synchrone als auch für asynchrone /insights-Aufrufe. Wenn sie überschritten werden, geben wir einen Fehler zurück:

error_code = 100,  CodeException (error subcode: 1487534)

Best Practices, Begrenzungen für Daten pro Aufruf

• Grenze deine Abfrage ein, indem du den Datumsbereich oder die Anzahl der Werbeanzeigen-IDs angibst. Du kannst deine Abfrage auch auf die erforderlichen Kennzahlen eingrenzen oder in mehrere Abfragen aufgliedern, die jeweils eine Teilmenge der Kennzahlen anfordern.
• Vermeide Abfragen auf Kontoebene, die Aufschlüsselungen mit hoher Kardinalität umfassen, wie action_target_id oder product_id, sowie größere Zeiträume wie die Lebensdauer.
• Verwende die /insights-Edge direkt mit Werbeobjekten einer niedrigeren Ebene, um genaue Daten für diese Ebene abzurufen. Verwende beispielsweise zunächst die Abfrage auf Kontoebene, um die Liste der Objekts-IDs der unteren Ebenen mit den Parametern level und filtering abzurufen. In diesem Beispiel rufen wir alle Kampagnen auf, die Impressionen aufgezeichnet haben:

curl -G \
-d 'access_token=<ACCESS_TOKEN>' \
-d 'level=campaign' \
-d 'filtering=[{field:"ad.impressions",operator:"GREATER_THAN",value:0}]' \
'https://graph.facebook.com/v2.7/act_<ACCOUNT_ID>/insights'

• Dann können wir /<campaign_id>/insights mit jedem zurückgegebenen Wert verwenden, um die Statistikanfragen für diese Kampagnen in einem einzelnen Aufruf abzufragen und in einem Batch zusammenzufassen:

curl \
-F 'access_token=<ACCESS_TOKEN>' \
-F 'batch=[ \
  { \
    "method": "GET", \
    "relative_url": "v21.0/<CAMPAIGN_ID_1>/insights?fields=impressions,spend,ad_id,adset_id&level=ad" \
  }, \
  { \
    "method": "GET", \
    "relative_url": "v21.0/<CAMPAIGN_ID_2>/insights?fields=impressions,spend,ad_id,adset_id&level=ad" \
  }, \
  { \
    "method": "GET", \
    "relative_url": "v21.0/<CAMPAIGN_ID_3>/insights?fields=impressions,spend,ad_id,adset_id&level=ad" \
  } \
]' \
'https://graph.facebook.com'

• Nutze den filtering-Parameter nur zum Abrufen von Statistiken für Werbeobjekte mit Daten. Der beim filtering angegebene Feldwert nutzt die DOT-Notation zur Angabe der Felder unter dem Objekt. Beachte, dass die Zusammenfassungsdaten durch Filtern mit STARTS_WITH und CONTAIN nicht verändert werden. Verwende in diesem Fall den IN-Operator. Hier ist ein Beispiel für eine filtering-Anfrage:

curl -G \
-d 'access_token=<ACCESS_TOKEN>' \
-d 'level=ad' \
-d 'filtering=[{field:"ad.impressions",operator:"GREATER_THAN",value:0},]' \
'https://graph.facebook.com/v21.0/act_<ACCOUNT_ID>/insights'

• Verwende nach Möglichkeit date_preset. Benutzerdefinierte Datumsbereiche sind weniger effizient in unserem System.
• Nutze Batch-Anfragen für mehrere synchrone und asynchrone Aufrufe, um beim Abrufen großer Datenmengen Zeitüberschreitungen zu vermeiden.
• Versuche es zunächst mit synchronen Aufrufen und dann mit asynchronen Aufrufen, wenn es bei synchronen Aufrufen zu einer Zeitüberschreitung kommt
• Die Statistiken werden alle 15 Minuten aktualisiert und ändern sich 28 Tage nach der Meldung nicht

Begrenzungen für die Insights-Aufruflast

Neunzig Tage nach Veröffentlichung von Version 3.3 und der Gültigkeit für alle öffentlichen Versionen ändern wir die Durchsatzratenbegrenzung auf Anzeigenkontoebene, um die Menge der benötigten API-Aufrufe besser darstellen zu können. Wir berechnen die Durchsatzratenbegrenzungsquote für unsere Marketing API-Zugangs-Tier und das Unternehmen, dem deine App gehört. Siehe Zugriff und Authentifizierung. Diese Änderung gilt für alle Ads Insights API-Endpunkte: GET {adaccount_ID}/insights, GET {campaign_ID}/insights, GET {adset_ID}/insights, GET {ad_ID}/insights, POST {adaccount_ID}/insights, POST {campaign_ID}/insights, POST {adset_ID}/insights, POST {ad_ID}/insights.

Wir begrenzen die Last im Sinne einer optimalen Berichtsnutzung. Wir messen sowohl die Rate von API-Aufrufen als auch die erforderlichen Ressourcen. Dabei lassen wir eine feste Lastbegrenzung pro App pro Sekunde zu. Wenn diese Begrenzung überschritten wird, schlagen deine Anfragen fehl.

Prüfe den x-fb-ads-insights-throttle-HTTP-Header in jeder API-Antwort, damit du immer weißt, wie nahe deine App an der Begrenzung ist, und einschätzen kannst, wie groß die Last einer Abfrage sein könnte. Insights-Aufrufe unterliegen ebenfalls den Standardbegrenzungen von Werbekonten gemäß dem x-ad-account-usage-HTTP-Header. Weitere Details findest du hier: Marketing API, Best Practices

Wenn eine App die Begrenzung erreicht hat, erhält der Aufruf eine Fehlerantwort mit dem Code error_code = 4, CodedException. Du solltest deutlich unter deiner Begrenzung bleiben. Wenn deine App die zulässigen Grenzwerte erreicht, wird nur ein bestimmter Prozentsatz der Anfragen weitergeleitet (je nach Abfrage und Rate).

Wir wenden die Durchsatzratenbegrenzung auf jede App an, die synchrone und asynchrone /insights-Aufrufe zusammen sendet. Bei den Begrenzungen werden zwei Hauptparameter berücksichtigt: App und Werbekonto.

Hier folgt ein Beispiel für einen HTTP-Header, der in Prozent angibt, wie nahe die App an den Begrenzungen liegt:

X-FB-Ads-Insights-Throttle: { "app_id_util_pct": 100, "acc_id_util_pct": 10, "ads_api_access_tier": "standard_access" }

Der Header „x-fb-ads-insights-throttle“ ist ein JSON-Wert mit den folgenden Informationen:

• app_id_util_pct: Der Prozentsatz der belegten zugewiesenen Kapazität für die jeweilige app_id.
• acc_id_util_pct: Der Prozentsatz der belegten zugewiesenen Kapazität für die jeweilige account_id des Werbekontos.
• ads_api_access_tier: Stufen ermöglichen deiner App den Zugriff auf die Marketing API. standard_access aktiviert eine niedrigere Durchsatzratenbegrenzung.

Globale Ratenbegrenzungen

In Zeiten mit erhöhter globaler Last für den /insights-Endpunkt kann das System zum Schutz des Backends Anfragen drosseln. Dies kann in seltenen Fällen auftreten, wenn zu viele Abfragen hoher Komplexität (große Zeiträume, komplexe Kennzahlen und/oder eine hohe Anzahl von Werbeobjekt-IDs) gleichzeitig eingehen. Daraufhin wird ein Fehler wie der Folgende zurückgegeben:

error_code = 4,  CodeException (error subcode: 1504022), error_title: Too many API requests

In solchen Zeiten ist es ratsam, die Anzahl der Aufrufe zu verringern, kurz zu warten und die Abfrage erneut zu senden.

Durchsatzratenbegrenzungen und Best Practices

• Wenn du viele Abfragen gleichzeitig sendest, erreichst du eher unsere Durchsatzratenbegrenzung. Versuche, deine /insights-Abfragen zu verteilen, indem du Wartezeiten zwischen Abfragen im Job einrichtest.
• Berücksichtige die Rateninformationen im HTTP-Antwort-Header, um deine Aufrufe richtig zu planen. Ergänze einen Wartemechanismus, um deine /insights-Abfragen langsamer zu senden oder anzuhalten, wenn du nahe an der 100 %-Grenze für deine App oder dein Werbekonto bist.
• In Werbeanzeigenstatistiken ist die Zeitzone des Werbekontos angegeben. Wenn du täglich Insights-Daten für das betreffende Werbekonto abrufen möchtest, solltest du die Tageszeit in der Zeitzone des Kontos berücksichtigen. Dies hilft dabei, die Abfragen den gesamten Tag über schnell zu bearbeiten.
• Überprüfe die ads_api_access_tier, die dir den Zugriff auf die Marketing API ermöglicht. Standardmäßig befinden sich Apps in der Stufe development_access und standard_access aktiviert die niedrigere Durchsatzratenbegrenzung. Um eine höhere Ratenbegrenzung zu erhalten und in die Standardstufe zu gelangen, kannst du „erweiterten Zugriff“ auf die Funktion Standardzugriff für Anzeigenmanagement anfordern.

Asynchrone Jobs der Insights API

Rufe Statistiken zu zahlreichen Objekten ab und filtere und sortiere die Daten. Dazu haben wir den asynchronen Workflow vereinfacht:

1. Sende eine POST-Anfrage an den <AD_OBJECT>/insights-Endpunkt, der mit der id einer Werbeanzeigen-Berichtsausführung antwortet.

{
  "report_run_id": 6023920149050,
}
    

Speichere die report_run_id nicht für die langfristige Nutzung, sie läuft nach 30 Tagen ab.

1. Werbeanzeigen-Berichtsausführungen enthalten Informationen zu diesem asynchronen Job, z. B. async_status. Frage dieses Feld ab, bis async_status = Job Completed und async_percent_completion = 100 ist.

{
  "id": "6044775548468",
  "account_id": "1010035716096012",
  "time_ref": 1459788928,
  "time_completed": 1459788990,
  "async_status": "Job Completed",
  "async_percent_completion": 100
}
    

1. Dann kannst du die <AD_REPORT_RUN_ID>/insights-Edge abfragen, um das endgültige Ergebnis abzurufen.

{
  "data": [
    {
      "impressions": "9708",
      "date_start": "2009-03-28",
      "date_stop": "2016-04-04"
    },
    {
      "impressions": "18841",
      "date_start": "2009-03-28",
      "date_stop": "2016-04-04"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MQZDZD"
    }
  }
}
    

Dieser Job ruft alle Statistiken für das Konto ab und gibt die ID eines asynchronen Jobs zurück:

curl \
  -F 'level=campaign' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/<CAMPAIGN_ID>/insights
curl -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/1000002
curl -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/1000003/insights

Status des asynchronen Jobs

Berichte exportieren

Wir bieten einen praktischen Endpunkt für den Export von <AD_REPORT_RUN_ID> in ein lokalisiertes, für Menschen lesbares Format.

Hinweis: Dieser Endpunkt ist nicht Teil unserer versionierten Graph API und entspricht daher nicht der Benachrichtigungspolitik für funktionsgefährdende Änderungen. Skripte und Programme sollten sich nicht auf das Ergebnisformat verlassen, da dieses ohne Vorankündigung geändert werden kann.

  curl -G \
  -d 'report_run_id=<AD_REPORT_RUN_ID>' \
  -d 'name=myreport' \
  -d 'format=xls' \
'https://www.facebook.com/ads/ads_insights/export_report/'