Method: advertisers.creatives.list

בתיבת הדו-שיח הזו מפורטים נכסי קריאייטיב של מפרסם.

הסדר מוגדר על ידי הפרמטר orderBy. אם לא יצוין filter של entityStatus, קריאייטיבים עם ENTITY_STATUS_ARCHIVED לא ייכללו בתוצאות.

בקשת HTTP

GET https://displayvideo.googleapis.com/v2/advertisers/{advertiserId}/creatives

בכתובת ה-URL נעשה שימוש בתחביר המרת קידוד של gRPC.

פרמטרים של נתיב

פרמטרים
advertiserId

string (int64 format)

חובה. המזהה של המפרסם שעבורו רוצים להציג את נכסי הקריאייטיב.

פרמטרים של שאילתה

פרמטרים
pageSize

integer

גודל הדף המבוקש. חייב להיות בין 1 ל-200. אם לא צויין ערך, ברירת המחדל תהיה 100. הפונקציה מחזירה את קוד השגיאה INVALID_ARGUMENT אם צוין ערך לא חוקי.

pageToken

string

אסימון שמזהה דף תוצאות שהשרת צריך להחזיר. בדרך כלל, זהו הערך של nextPageToken שהוחזר מהקריאה הקודמת ל-method creatives.list. אם לא מציינים זאת, המערכת תחזיר את דף התוצאות הראשון.

orderBy

string

השדה שלפיו צריך למיין את הרשימה. הערכים הקבילים הם:

  • creativeId (ברירת מחדל)
  • createTime
  • mediaDuration
  • dimensions (קודם מיון לפי רוחב ואחר כך לפי גובה)

ברירת המחדל של סדר המיון היא בסדר עולה. כדי לציין סדר יורד בשדה, הסיומת 'תיאור' יש להוסיף לשם השדה. דוגמה: createTime desc

filter

string

מאפשר סינון לפי שדות קריאייטיב.

תחביר נתמך:

  • ביטויי הסינון מורכבים מהגבלה אחת או יותר.
  • אפשר לשלב את ההגבלות באמצעות אופרטורים לוגיים AND או OR. רצף של הגבלות משתמש באופן מרומז ב-AND.
  • הגבלה היא בצורה הבאה: {field} {operator} {value}.
  • השדה lineItemIds חייב להשתמש באופרטור HAS (:).
  • השדה updateTime חייב להשתמש באופרטורים GREATER THAN OR EQUAL TO (>=) או LESS THAN OR EQUAL TO (<=).
  • בכל שאר השדות צריך להשתמש באופרטור EQUALS (=).
  • בשדות entityStatus, minDuration, maxDuration, updateTime ו-dynamic, יכול להיות שתהיה הגבלה אחת לכל היותר.

שדות נתמכים:

  • approvalStatus
  • creativeId
  • creativeType
  • dimensions (קלט בפורמט {width}x{height})
  • dynamic
  • entityStatus
  • exchangeReviewStatus (קלט בפורמט {exchange}-{reviewStatus})
  • lineItemIds
  • maxDuration (קלט בפורמט {duration}s. רק שניות נתמכות)
  • minDuration (קלט בפורמט {duration}s. רק שניות נתמכות)
  • updateTime (קלט בפורמט ISO 8601 או YYYY-MM-DDTHH:MM:SSZ)

הערות:

  • לגבי updateTime, ערך השדה של משאב קריאייטיב משקף את הפעם האחרונה שבה קריאייטיב עודכן, כולל עדכונים שבוצעו על ידי המערכת (למשל, עדכונים שבוצעו במהלך הבדיקה של הקריאייטיב).

דוגמאות:

  • כל הקריאייטיבים המותאמים: creativeType="CREATIVE_TYPE_NATIVE"
  • כל הקריאייטיבים הפעילים בגודל 300x400 או 50x100: entityStatus="ENTITY_STATUS_ACTIVE" AND (dimensions="300x400" OR dimensions="50x100")
  • כל הקריאייטיבים הדינמיים שאושרו על ידי AdX או AppNexus, למשך זמן מינימלי של 5 שניות ו-200 אלפיות שנייה: dynamic="true" AND minDuration="5.2s" AND (exchangeReviewStatus="EXCHANGE_GOOGLE_AD_MANAGER-REVIEW_STATUS_APPROVED" OR exchangeReviewStatus="EXCHANGE_APPNEXUS-REVIEW_STATUS_APPROVED")
  • כל הקריאייטיבים של וידאו שמשויכים למזהה הפריט 1 או 2: creativeType="CREATIVE_TYPE_VIDEO" AND (lineItemIds:1 OR lineItemIds:2)
  • חיפוש קריאייטיבים לפי כמה מזהי קריאייטיבים: creativeId=1 OR creativeId=2
  • כל נכסי הקריאייטיב שמועד העדכון שלהם הוא 2020-11-04T18:54:47Z (בפורמט ISO 8601) או גדול ממנו: updateTime>="2020-11-04T18:54:47Z"

האורך של השדה הזה לא יעלה על 500 תווים.

לקבלת מידע נוסף, אפשר לעיין במדריך שלנו בנושא בקשות לסינון LIST.

גוף הבקשה

גוף הבקשה חייב להיות ריק.

גוף התשובה

אם הפעולה בוצעה ללא שגיאות, גוף התגובה יכיל נתונים במבנה הבא:

ייצוג JSON
{
  "creatives": [
    {
      object (Creative)
    }
  ],
  "nextPageToken": string
}
שדות
creatives[]

object (Creative)

רשימת נכסי הקריאייטיב.

אם הרשימה ריקה, הרשימה תיעלם.

nextPageToken

string

אסימון לאחזור של דף התוצאות הבא. צריך להעביר את הערך הזה בשדה pageToken בקריאה הבאה לשיטה ListCreativesRequest, כדי לאחזר את דף התוצאות הבא. אם השדה הזה הוא null, המשמעות היא שזהו הדף האחרון.

היקפי ההרשאות

נדרש היקף ההרשאות הבא של OAuth:

  • https://www.googleapis.com/auth/display-video

למידע נוסף, קראו את המאמר סקירה כללית של OAuth 2.0.