API によるカスタムドキュメントの同期

OpenAPI | gRPC

ポータルには、カスタムコンテンツを同期するための特殊な API があります。この API を呼び出すには、次の操作を行います。

少なくとも 1 回は、カスタムコンテンツを手動で同期します。
適切な権限とキーを使用してサービスアカウントを作成します。
HTTP リクエストによってコンテンツを同期します。

このドキュメントでは、サービスアカウントを作成する手順を説明し、Python またはコマンドラインからリクエストを行う例を示します。

承認済みサービスアカウントを作成する

API を使用してカスタムコンテンツを同期させるには、適切な権限と鍵を持つサービスアカウントが必要です。サービスアカウントを作成して適切な役割を付与し、必要な鍵ファイルを取得するには、次の手順に従います。

Console

サービスアカウントの作成:
1. Google Cloud コンソールで、[サービスアカウント] ページに移動します。
  
  [サービスアカウント] に移動
2. 対象の API が使用するよう構成されているプロジェクトを選択します。
3. [サービスアカウントを作成] をクリックします。
4. [サービスアカウント名] フィールドに名前を入力します。Google Cloud コンソールでは、この名前に基づいて [サービスアカウント ID] フィールドに値が設定されます。
5. 省略可: [サービスアカウントの説明] 欄に、サービスアカウントの説明を入力します。
6. [作成して続行] をクリックします。
7. [完了] をクリックして、サービスアカウントの作成を完了します。
  
  ブラウザウィンドウは閉じないでください。次のステップでこれを使用します。
作成したサービスアカウントの JSON キーをダウンロードします。
1. Google Cloud コンソールで、作成したサービスアカウントのメールアドレスをクリックします。
2. [キー] をクリックします。
3. [鍵を追加]、[新しい鍵を作成] の順にクリックします。
4. [作成] をクリックします。JSON キーファイルがパソコンにダウンロードされます。
  
  鍵ファイルは、サービスアカウントとしての認証で使用できるため、安全な場所に保管してください。このファイルは任意の場所に移動できます。名前の変更も可能です。
5. [閉じる] をクリックします。
Google Cloud コンソールで、プロジェクトの [エンドポイント] > [サービス] ページに移動します。

エンドポイントサービス
カスタムコンテンツを同期させるために使用する API の名前をクリックし、そのアクセス権を変更します。
[権限] サイドパネルが開いていない場合は、[+ 権限] をクリックします。
作成したサービスアカウントに API へのアクセス権を付与するには、[メンバーを追加] フィールドにそのサービスアカウントのメールアドレスを入力します。
[役割を選択] プルダウンリストで [サービス管理] をクリックし、サービスアカウントの役割として [Service Config 編集者] を選択します。

これで、サービスアカウントを作成し、その秘密鍵を JSON ファイルにダウンロードして、サービスアカウントに適切な役割を割り当てました。

gcloud

次のコマンドを入力して、Google Cloud プロジェクトのプロジェクト ID を表示します。
```
gcloud projects list
```
次のコマンドの [YOUR_PROJECT_ID] の部分を API が含まれているプロジェクトに置き換えて、デフォルトのプロジェクトに設定します。
```
gcloud config set project [YOUR_PROJECT_ID]
```
重要: API が含まれているプロジェクトと同じプロジェクト内でサービスアカウントを作成する必要があります。
Google Cloud CLI（gcloud）が、Google Cloud にある対象のデータとサービスへのアクセスが許可されていることを確認します。
```
gcloud auth login
```
アカウントが複数ある場合は、API がある Google Cloud プロジェクトのアカウントを選択してください。gcloud auth list を実行すると、選択したアカウントがプロジェクトの有効なアカウントとして表示されます。
サービスアカウントを作成するには、次のコマンドを実行します。このとき、[SERVICE_ACCOUNT_NAME] と [Service Account to Sync Custom Content] は、使用する名前と表示名で置き換えます。
```
gcloud iam service-accounts create [SERVICE_ACCOUNT_NAME] \
  --display-name "[Service Account to Sync Custom Content]"
```
このコマンドは、サービスアカウントのメールアドレスを次の形式で割り当てます。
```
[SERVICE_ACCOUNT_NAME]@[YOUR_PROJECT_ID].iam.gserviceaccount.com
```
このメールアドレスは、後で実行するコマンドで必要になります。

サービスアカウントキーのファイルを作成します。[KEY_FILE] は、キーのファイル名で置き換えてください。

gcloud iam service-accounts keys create ~/[KEY_FILE] \
  --iam-account [SERVICE_ACCOUNT_NAME]@[YOUR_PROJECT_ID].iam.gserviceaccount.com

カスタムコンテンツで使用する API へのアクセス権をサービスアカウントに付与するには、次のコマンドを実行します。このとき [YOUR_SERVICE_NAME] をカスタムコンテンツで使用する API の名前に置き換えます。
```
gcloud endpoints services add-iam-policy-binding [SERVICE-NAME] \
      --member=serviceAccount:[SERVICE_ACCOUNT_NAME]@[YOUR_PROJECT_ID].iam.gserviceaccount.com \
      --role roles/servicemanagement.configEditor
```

カスタムコンテンツの同期リクエストを送信する

次の例は、カスタムコンテンツの同期をリクエストする方法を示しています。このリクエストは次のようになります。

 POST https://endpointsportal.[YOUR_PROJECT_ID].cloud.goog/api/v1/[YOUR_SERVICE_NAME]/custom-content/

[YOUR_PROJECT_ID] と [YOUR_SERVICE_NAME] は、適切な値で置き換えてください。リクエストが正常に完了すると、200 の HTTP ステータスコードが返されます。

次の例で、Google の承認サーバーからアクセストークンを取得し、そのトークンを使ってポータルのエンドポイントに対してリクエストを実行する方法を、Python とコマンドラインのそれぞれを使用した場合について説明します。

Python

必要な Python ライブラリをインストールします。
```
    pip install --upgrade google-auth
```

サービスアカウントの認証情報と、エンドポイントが必要とするスコープを使って Credentials オブジェクトを作成し、コンテンツの同期リクエストを行います。[YOUR_PROJECT_ID]、/path/to/service.json、および [YOUR_SERVICE_NAME] をそれぞれ適切な値に置き換えてください。

from google.oauth2 import service_account
from google.auth.transport.requests import AuthorizedSession

SCOPES = ["https://www.googleapis.com/auth/service.management.readonly"]
SERVICE_ACCOUNT_FILE = "/path/to/service.json"
PROJECT_ID = "[YOUR_PROJECT_ID]"
SERVICE_NAME = "[YOUR_SERVICE_NAME]"

credentials = service_account.Credentials.from_service_account_file(
   SERVICE_ACCOUNT_FILE, scopes=SCOPES)
authed_session = AuthorizedSession(credentials)
endpoint =
"https://endpointsportal.%s.cloud.goog/api/v1/%s/custom-content" % (PROJECT_ID, SERVICE_NAME)
result = authed_session.post(endpoint)
print result

コマンドライン

Cloud Shell を開きます。または、Linux パソコンに gcloud CLI がインストールされている場合はターミナルウィンドウを開きます。
サービスアカウントに対する認証を行うには、次のコマンドを実行します。[KEY_FILE] は、サービスアカウントキーファイルのパスで置き換えてください。
```
gcloud auth activate-service-account --key-file [KEY_FILE]
```
サービスアカウントを使用して承認トークンを取得します。
```
ACCESS_TOKEN=$(gcloud auth print-access-token)
```
API を呼び出す際は、このトークンの値を Authorization ヘッダーで署名なしトークンとして渡します。[YOUR_PROJECT_ID] と [YOUR_SERVICE_NAME] は、適切な値で置き換えてください。
```
curl -X POST -H "Authorization: Bearer ${ACCESS_TOKEN}" \
https://endpointsportal.[YOUR_PROJECT_ID].cloud.goog/api/v1/[YOUR_SERVICE_NAME]/custom-content
```