Partial Failure

一部の AdWords サービスでは有効なオペレーションはコミットされ、失敗したオペレーションはエラーを返すように設定できます。これは Partial Failure という機能で、失敗したオペレーションを最後に個別に処理できるメリットがあります。

技術情報

この機能を利用するには、次のような SOAP ヘッダーを設定する必要があります。

<partialFailure>true</partialFailure>

サービスがエラーのないオペレーションを実行し、成功した場合は結果が返され、失敗した場合はエラーが送出されます。mutate オペレーションでない場合はこのヘッダーは無視されます。

この機能は次のサービスで利用できます。

使用方法

複数のキーワードをアカウントに登録する必要があるとします。しかし、その一部は広告の編集に関するポリシーに違反している可能性があります。有効なキーワードはそのまま登録し、登録に失敗したキーワードではエラーが返されるようにするには次の手順を行います。

サービスを作成する

まずは、次のように partialFailure モードを有効にします。

// Enable partial failure.
session.setPartialFailure(true);

オペレーションを作成して API 呼び出しを行う

通常どおりに mutate オペレーションを作成して API 呼び出しを行います。

List<AdGroupCriterionOperation> operations = new ArrayList<AdGroupCriterionOperation>();

// Create keywords.
String[] keywords =
    new String[] {"mars cruise", "inv@lid cruise", "venus cruise", "b(a)d keyword cruise"};
for (String keywordText : keywords) {
  // Create keyword
  Keyword keyword = new Keyword();
  keyword.setText(keywordText);
  keyword.setMatchType(KeywordMatchType.BROAD);

  // Create biddable ad group criterion.
  BiddableAdGroupCriterion keywordBiddableAdGroupCriterion = new BiddableAdGroupCriterion();
  keywordBiddableAdGroupCriterion.setAdGroupId(adGroupId);
  keywordBiddableAdGroupCriterion.setCriterion(keyword);

  // Create operation.
  AdGroupCriterionOperation keywordAdGroupCriterionOperation =
      new AdGroupCriterionOperation();
  keywordAdGroupCriterionOperation.setOperand(keywordBiddableAdGroupCriterion);
  keywordAdGroupCriterionOperation.setOperator(Operator.ADD);
  operations.add(keywordAdGroupCriterionOperation);
}

// Add ad group criteria.
AdGroupCriterionReturnValue result =
    adGroupCriterionService.mutate(operations.toArray(new AdGroupCriterionOperation[] {}));

成功したオペレーションを処理する

オペレーションが成功した場合は、サービスによって結果の値が返されます。結果は必要に応じて出力します。

for (AdGroupCriterion adGroupCriterionResult : result.getValue()) {
  if (adGroupCriterionResult.getCriterion() != null) {
    System.out.printf("Ad group criterion with ad group ID %d, and criterion ID %d, "
        + "and keyword '%s' was added.%n", adGroupCriterionResult.getAdGroupId(),
        adGroupCriterionResult.getCriterion().getId(),
        ((Keyword) adGroupCriterionResult.getCriterion()).getText());
  }
}

失敗したオペレーションを処理する

オペレーションが失敗した場合は、partialFailureErrors フィールドでエラー情報が返されます。失敗したオペレーションのインデックスは、partialFailures リストの ApiError オブジェクトの fieldPathElements プロパティ(v201702 から利用可能)または fieldPath プロパティ(すべてのバージョンで利用可能)で確認できます。

for (ApiError apiError : result.getPartialFailureErrors()) {
  // Get the index of the failed operation from the error's field path elements.
  FieldPathElement[] fieldPathElements = apiError.getFieldPathElements();
  FieldPathElement firstFieldPathElement = null;
  if (fieldPathElements != null && fieldPathElements.length > 0) {
    firstFieldPathElement = fieldPathElements[0];
  }
  if (firstFieldPathElement != null
      && "operations".equals(firstFieldPathElement.getField())
      && firstFieldPathElement.getIndex() != null) {
    int operationIndex = firstFieldPathElement.getIndex();
    AdGroupCriterion adGroupCriterion = operations.get(operationIndex).getOperand();
    System.out.printf(
        "Ad group criterion with ad group ID %d and keyword '%s' "
            + "triggered a failure for the following reason: %s.%n",
        adGroupCriterion.getAdGroupId(),
        ((Keyword) adGroupCriterion.getCriterion()).getText(),
        apiError.getErrorString());
  } else {
    System.out.printf(
        "A failure has occurred for the following reason: %s%n", apiError.getErrorString());
  }
}

他の言語のコードサンプル

各言語のクライアント ライブラリErrorHandling フォルダには、この機能の使い方を説明するコードサンプルがあります。

フィードバックを送信...

ご不明な点がありましたら、Google のサポートページをご覧ください。