API 액세스 설정

SDK 또는 REST를 사용하여 데이터 관리 도구 API에 대한 액세스를 설정하는 방법은 다음과 같습니다.

기본 요건

Data API를 사용하려면 다음이 필요합니다.

  1. Google Cloud 프로젝트
  2. 다음 두 기준을 모두 충족하는 Google 계정:
    1. 데이터 관리 도구 API 관심사 양식을 작성한 후 데이터 관리 도구 API에 대한 액세스 권한이 부여되었습니다. API 제품 세부정보 페이지가 표시되면 액세스 권한이 있는 것입니다.
    2. Google Cloud 프로젝트에 대한 serviceusage.services.enable 권한이 있거나 해당 권한이 포함된 역할이 있습니다. 예를 들어 roles/ownerroles/serviceusage.serviceUsageAdmin 모두 serviceusage.services.enable 권한을 포함합니다. 권한을 확인하려면 현재 액세스 권한 보기를 참고하세요.

API 사용 설정

아직 사용 설정하지 않은 경우 데이터 관리 도구 API 사용 설정을 클릭하여 데이터 관리 도구 API를 사용 설정하거나 안내에 따라 이 단계를 수동으로 실행합니다.

Data Manager API 사용 설정하기

데이터 관리 도구 API를 찾을 수 없거나 데이터 관리 도구 API 사용 설정이 실패하는 경우 Google 계정이 기본 요건을 충족하는지 확인하세요.

인증 설정

API 키 외에도 Google의 인증 방법을 사용할 수 있습니다. 사용 사례에 적합한 인증 방법을 선택하는 방법을 검토하여 사용 사례에 적합한 접근 방식을 결정하는 것이 좋습니다.

일반적인 인증 방법에는 사용자 계정서비스 계정이 있습니다.

  • 사용자 계정: Google API 및 서비스와 직접 상호작용하는 사용자를 나타냅니다.
  • 서비스 계정: 사용자가 사람이 아닌 앱을 나타냅니다. 이를 통해 앱에서 인증 및 승인을 관리할 수 있습니다. 예를 들어 앱이 Google Cloud 리소스에 액세스해야 하는 경우입니다.

통합에서 애플리케이션 기본 사용자 인증 정보 (ADC)를 사용하여 환경에서 사용자 인증 정보를 자동으로 찾을 수 있으므로 인증을 위해 클라이언트 코드를 변경할 필요가 없습니다.

사용자 계정 또는 서비스 계정 가장을 선택하여 ADC를 설정합니다.

사용자 계정 사용자 인증 정보로 인증하는 단계는 다음과 같습니다.

  1. 프로젝트의 Google 인증 플랫폼 설정을 구성합니다.

    1. Google Cloud 콘솔에서 브랜딩 페이지를 엽니다.

    2. 프로젝트를 선택합니다.

    3. 양식을 작성하고 만들기를 클릭합니다.

  2. 데이터 관리 도구 API 범위는 민감한 범위이므로 다음 단계가 필요합니다.

    1. 프로젝트의 데이터 액세스 설정으로 이동합니다.

    2. 범위 추가 또는 삭제를 클릭합니다.

    3. 범위 목록에서 Data Manager API 옆의 체크박스를 선택하고 업데이트를 클릭합니다.

    4. 저장을 클릭합니다.

    5. Google Cloud 콘솔에서 잠재고객으로 이동하여 게시 상태사용자 유형을 업데이트합니다. 앱 잠재고객 관리에서 이러한 설정에 대해 자세히 알아보세요.

  3. OAuth2 클라이언트 만들기를 클릭하여 프로젝트에서 OAuth2 클라이언트를 만들거나 안내에 따라 데스크톱 OAuth2 클라이언트를 만듭니다.

    OAuth2 클라이언트 만들기

    마지막 단계에서 클라이언트 구성 다운로드를 클릭하고 선택한 다운로드 위치를 기록해 둡니다.

  4. 다음 명령어를 실행하여 로컬 ADC 파일을 생성합니다. 이 명령어는 API와 함께 사용하는 Google 계정에 로그인하라는 메시지가 표시되는 웹 흐름을 실행합니다.

    PATH_TO_CLIENT_JSON을 다운로드한 JSON 파일 이름으로 바꿉니다.

    gcloud auth application-default login \
      --scopes="https://www.googleapis.com/auth/datamanager,https://www.googleapis.com/auth/cloud-platform" \
      --client-id-file="PATH_TO_CLIENT_JSON"
    
  5. 다음 명령어를 사용하여 사용자 인증 정보가 올바르게 설정되었는지 확인합니다. 성공하면 명령어가 콘솔에 액세스 토큰을 출력합니다.

    gcloud auth application-default print-access-token
    

앱의 인증 및 사용자 인증 정보에 대해 자세히 알아보려면 Google 인증 방법애플리케이션 기본 사용자 인증 정보의 작동 방식을 참고하세요.

운영 계정 액세스 설정

사용자 계정과 연결된 이메일에 Destination 액세스 권한을 부여합니다.

  • Google Ads 또는 데이터 파트너 계정을 사용하는 경우 안내에 따라 사용자의 이메일을 계정에 추가합니다.
  • Display & Video 360 계정을 사용하는 경우 안내에 따라 사용자 이메일을 계정에 추가합니다.

프로그래밍 언어의 SDK 설정

로컬 머신에 원하는 SDK를 설치합니다.

REST

  1. 다음 샘플에서 OPERATING_ACCOUNT_PRODUCT, OPERATING_ACCOUNT_ID, AUDIENCE_ID과 같은 자리표시자를 계정 및 대상의 값으로 업데이트합니다.
  2. PROJECT_ID를 Google Cloud의 ID로 바꿉니다.
  3. 샘플을 명령줄에 복사하여 요청을 보냅니다.

    설정된 제품 링크를 사용하여 operatingAccount에 액세스하지 않는 경우 destinations의 항목에서 linkedAccount 속성을 삭제합니다.

    #!/bin/bash
    
    # Uses gcloud to get an access token. If the Application Default
    # Credentials aren't for a service account, the command that specifies
    # --scopes fails. This sample falls back to the command without the
    # --scopes argument.
    DATA_MANAGER_ACCESS_TOKEN="$(gcloud auth application-default print-access-token --scopes=https://www.googleapis.com/auth/datamanager || \
      gcloud auth application-default print-access-token)"
    
    # Fetches and prints the scope information for the access token. If you
    # get scope-related errors when you send the request in the next step,
    # verify that this output includes the Data Manager API scope:
    #   https://www.googleapis.com/auth/datamanager
    curl https://www.googleapis.com/oauth2/v1/tokeninfo?access_token="${DATA_MANAGER_ACCESS_TOKEN}"
    
    # Sends the request.
    curl -X POST "https://datamanager.googleapis.com/v1/audienceMembers:ingest" \
      --header "Authorization: Bearer ${DATA_MANAGER_ACCESS_TOKEN}" \
      --header "x-goog-user-project: PROJECT_ID" \
      --header "Content-Type: application/json" \
      --data @- <<EOF
    {
      "destinations": [
        {
          "operatingAccount": {
            "product": "OPERATING_ACCOUNT_PRODUCT",
            "accountId": "OPERATING_ACCOUNT_ID"
          },
          "loginAccount": {
            "product": "LOGIN_ACCOUNT_PRODUCT",
            "accountId": "LOGIN_ACCOUNT_ID"
          },
          "linkedAccount": {
            "product": "LINKED_ACCOUNT_PRODUCT",
            "accountId": "LINKED_ACCOUNT_ID"
          },
          "productDestinationId": "AUDIENCE_ID"
        }
      ],
      "audienceMembers": [
        {
          "userData": {
            "userIdentifiers": [
              {
                "emailAddress": "07e2f1394b0ea80e2adca010ea8318df697001a005ba7452720edda4b0ce57b3"
              },
              {
                "emailAddress": "1df6b43bc68dd38eca94e6a65b4f466ae537b796c81a526918b40ac4a7b906c7"
              }
            ]
          }
        },
        {
          "userData": {
            "userIdentifiers": [
              {
                "emailAddress": "2ef46c4214c3fc1b277a2d976d55194e12b899aa50d721f28da858c7689756e3"
              },
              {
                "emailAddress": "54e410b14fa652a4b49b43aff6eaf92ad680d4d1e5e62ed71b86cd3188385a51"
              },
              {
                "emailAddress": "e8bd3f8da6f5af73bec1ab3fbf7beb47482c4766dfdfc94e6bd89e359c139478"
              }
            ]
          }
        },
        {
          "userData": {
            "userIdentifiers": [
              {
                "emailAddress": "05bb62526f091b45d20e243d194766cca8869137421047dc53fa4876d111a6f0"
              },
              {
                "emailAddress": "f1fcde379f31f4d446b76ee8f34860eca2288adc6b6d6c0fdc56d9eee75a2fa5"
              }
            ]
          }
        },
        {
          "userData": {
            "userIdentifiers": [
              {
                "emailAddress": "83a834cc5327bc4dee7c5408988040dc5813c7662611cd93b707aff72bf7d33f"
              },
              {
                "emailAddress": "223ebda6f6889b1494551ba902d9d381daf2f642bae055888e96343d53e9f9c4"
              }
            ]
          }
        }
      ],
      "consent": {
        "adUserData": "CONSENT_GRANTED",
        "adPersonalization": "CONSENT_GRANTED"
      },
      "encoding": "HEX",
      "termsOfService": {
        "customerMatchTermsOfServiceStatus": "ACCEPTED"
      },
      "validateOnly": true
    }
    EOF
    

.NET

  1. google-cloud-ads-datamanager-v1-csharp.tar.gz를 다운로드하고 압축을 해제합니다.

  2. .NET 프로젝트에서 Data Manager API 라이브러리에 대한 ProjectReference 종속 항목을 선언합니다. PATH_TO_CLIENT_LIBRARYgoogle-cloud-ads-datamanager-v1-csharp.tar.gz에서 google-cloud-ads-datamanager-v1-csharp 디렉터리를 추출한 위치로 바꿉니다.

    <ProjectReference Include="PATH_TO_CLIENT_LIBRARY\Google.Ads.DataManager.V1\Google.Ads.DataManager.V1.csproj" />
    
  3. 선택사항. 유틸리티 라이브러리 및 코드 샘플을 가져옵니다.

    1. data-manager-dotnet.tar.gz를 다운로드하고 추출합니다.

    2. .NET 프로젝트에서 유틸리티 라이브러리에 대한 ProjectReference 종속 항목을 선언합니다. PATH_TO_UTILITY_LIBRARYdata-manager-dotnet.tar.gz에서 data-manager-dotnet 디렉터리를 추출한 위치로 바꿉니다.

      <ProjectReference Include="PATH_TO_UTILITY_LIBRARY\Google.Ads.DataManager.Util\src\Google.Ads.DataManager.Util.csproj" />
      
    3. 데이터 형식을 지정하려면 .NET 프로젝트에서 Formatter 유틸리티를 사용하세요.

    4. samples 하위 디렉터리에서 코드 샘플을 찾아봅니다.

      코드 샘플을 실행하려면 google-cloud-ads-datamanager-v1-csharp.tar.gz에서 google-cloud-ads-datamanager-v1-csharp 디렉터리를 추출한 위치로 DATA_MANAGER_DOTNET_LIB 환경 변수를 설정합니다.

      export DATA_MANAGER_DOTNET_LIB="PATH_TO_CLIENT_LIBRARY"
      

      samples 디렉터리로 변경하고 dotnet run을 사용하여 사용 가능한 샘플 목록을 가져옵니다.

      dotnet run --framework net8.0
      

      샘플을 실행할 때 --help 인수를 전달하여 예상 매개변수와 함께 사용법 문을 출력합니다.

      dotnet run --framework net8.0 -- ingest-audience-members --help
      

      샘플 데이터를 시작하려면 samples/sampledata/audience_members_1.csv의 파일을 사용하세요.

자바

  1. google-cloud-ads-datamanager-v1-java.tar.gz를 다운로드하고 압축을 풉니다.
  2. google-cloud-ads-datamanager-v1-java 디렉터리로 이동합니다.
  3. 다음 명령어를 실행하여 Maven 또는 Gradle과 함께 사용할 라이브러리를 로컬 Maven 저장소에 빌드하고 게시합니다.

    ./gradlew -Pversion=0.1.0 install
    
  4. Java 프로젝트에서 데이터 관리자 API 라이브러리에 대한 종속 항목을 선언합니다.

    Gradle:

    implementation 'com.google.cloud:gapic-google-cloud-ads-datamanager-v1-java:0.1.0'
    

    Maven:

    <dependency>
      <groupId>com.google.cloud</groupId>
      <artifactId>gapic-google-cloud-ads-datamanager-v1-java</artifactId>
      <version>0.1.0</version>
    </dependency>
    
  5. 선택사항. 유틸리티 라이브러리 및 코드 샘플을 가져옵니다.

    1. GitHub 저장소를 클론합니다.

      git clone https://github.com/googleads/data-manager-java.git
      
    2. data-manager-java 디렉터리로 이동합니다.

    3. 유틸리티 라이브러리를 빌드하고 로컬 Maven 저장소에 게시합니다.

      ./gradlew data-manager-util:install
      
    4. Java 프로젝트에서 유틸리티 라이브러리의 종속 항목을 선언합니다.

      Gradle:

      implementation 'com.google.api-ads:data-manager-util:0.1.0'
      

      Maven:

      <dependency>
         <groupId>com.google.api-ads</groupId>
         <artifactId>data-manager-util</artifactId>
         <version>0.1.0</version>
      </dependency>
      
    5. 데이터를 포맷하고 암호화하려면 Java 프로젝트에서 UserDataFormatterEncrypter 유틸리티를 사용합니다.

    6. data-manager-samples 하위 디렉터리 또는 GitHub에서 코드 샘플을 살펴봅니다. 명령줄에서 샘플을 실행하려면 Gradle run 작업을 사용하세요.

      예를 들어 다음 명령어는 IngestAudienceMembers 샘플을 실행하고 사용법 문을 출력합니다.

      ./gradlew data-manager-samples:run \
        --args='IngestAudienceMembers --help'
      

      샘플 데이터를 시작하려면 data-manager-samples/src/main/resources/sampledata/audience_members_1.csv의 파일을 사용하세요.

Python

  1. ads-datamanager-v1-py.tar.gz를 다운로드합니다.
  2. 다운로드 디렉터리로 이동합니다.
  3. 다음 명령어를 실행하여 라이브러리를 빌드하고 동일한 Python 환경의 다른 프로젝트에서 사용할 수 있도록 합니다.

    pip install ./ads-datamanager-v1-py.tar.gz
    
  4. Python 프로젝트에서 데이터 관리자 API 라이브러리의 종속 항목을 선언합니다. 예를 들어 프로젝트에서 requirements.txt 파일을 사용하는 경우 파일에 다음 줄을 추가합니다.

    google-ads-data-manager=0.1.0
    
  5. 선택사항. 유틸리티 라이브러리 및 코드 샘플을 가져옵니다.

    1. data-manager-python.tar.gz를 다운로드하고 추출합니다.
    2. data-manager-python 디렉터리로 이동합니다.
    3. Python 환경에 유틸리티 라이브러리를 설치하려면 다음 명령어를 실행합니다.

      pip install .
      
    4. Python 프로젝트에서 유틸리티 라이브러리의 종속 항목을 선언합니다. 예를 들어 프로젝트에서 requirements.txt 파일을 사용하는 경우 파일에 다음 줄을 추가합니다.

      google-ads-data-manager-util=0.1.0
      
    5. 데이터를 포맷하고 암호화하려면 Python 프로젝트에서 FormatterEncrypter 유틸리티를 사용합니다.

    6. samples 하위 디렉터리에서 코드 샘플을 찾아봅니다. 샘플을 실행할 때 --help 인수를 전달하여 예상 매개변수와 함께 사용법 문을 출력합니다.

      샘플 데이터를 시작하려면 samples/sampledata/audience_members_1.csv의 파일을 사용하세요.

Node.js

  1. ads-datamanager-v1-nodejs.tar.gz를 다운로드하고 압축을 해제합니다.
  2. ads-datamanager-v1-nodejs 디렉터리로 이동합니다.
  3. 다음 명령어를 실행하여 npm에서 사용할 수 있도록 라이브러리를 .tgz 파일로 컴파일하고 패키징합니다.

    npm install
    npm pack
    

    이 명령어는 google-cloud-datamanager-0.1.0.tgz라는 보관 파일을 생성합니다.

  4. Node.js 프로젝트에서 google-cloud-datamanager-0.1.0.tgz 파일의 전체 경로와 파일 이름에 대한 dependencies 항목을 추가하여 데이터 관리 도구 API 라이브러리의 종속 항목을 선언합니다.

PHP

  1. google-cloud-ads-datamanager-v1-php.tar.gz를 다운로드하고 압축을 해제합니다.
  2. google-cloud-ads-datamanager-v1-php 디렉터리로 이동합니다.
  3. 다음 명령어를 실행하여 라이브러리의 종속 항목을 해결합니다.

    composer update --prefer-dist
    
  4. 동일한 호스트에 있는 PHP 프로젝트의 composer.json 파일에서 다음 단계에 따라 Data Manager API 라이브러리의 종속 항목을 선언합니다.

    1. google-cloud-ads-datamanager-v1-php 디렉터리의 위치를 가리키는 repositories 섹션을 추가합니다.

      "repositories" : [
         {
            "type" : "path",
            "url" : "PATH_TO_CLIENT_LIBRARY"
         }
      ]
      
    2. 데이터 관리자 API 라이브러리에 대한 종속 항목을 선언합니다.

      "require": {
         "googleads/data-manager": "^0.1.0"
      }
      
  5. (선택사항) 유틸리티 라이브러리 및 코드 샘플을 가져옵니다.

    1. data-manager-php.tar.gz를 다운로드하고 추출합니다.
    2. data-manager-php 디렉터리로 이동합니다.
    3. 다음 명령어를 실행하여 라이브러리의 종속 항목을 해결합니다.

      composer update --prefer-dist
      
    4. 동일한 호스트에 있는 PHP 프로젝트의 composer.json 파일에서 다음 단계에 따라 유틸리티 라이브러리의 종속 항목을 선언합니다.

      1. data-manager-php 디렉터리의 위치를 가리키는 항목을 repositories 섹션에 추가합니다.

        "repositories" : [
           {
              "type" : "path",
              "url" : "PATH_TO_UTILITY_LIBRARY"
           }
        ]
        
      2. 유틸리티 라이브러리에 대한 종속 항목을 선언합니다.

        "require": {
           "googleads/data-manager-util": "@dev"
        }
        

      데이터 형식을 지정하려면 PHP 프로젝트에서 Formatter 유틸리티를 사용하세요.

    5. samples 하위 디렉터리에서 코드 샘플을 찾아봅니다. 다음 단계에 따라 샘플을 실행합니다.

      1. samples 디렉터리로 이동합니다.

      2. DATA_MANAGER_PHP_LIB 환경 변수를 클라이언트 라이브러리를 추출한 경로로 설정합니다.

        export DATA_MANAGER_PHP_LIB="PATH_TO_CLIENT_LIBRARY"
        
      3. 다음 명령어를 실행하여 라이브러리의 종속 항목을 해결합니다.

        composer update --prefer-dist
        
      4. 필요한 인수를 전달하여 샘플을 실행합니다. 샘플을 실행할 때 --help 인수를 전달하여 예상 매개변수와 함께 사용법 문을 출력합니다.

      샘플 데이터를 시작하려면 samples/sampledata/audience_members_1.csv의 파일을 사용하세요.

다음 단계