This add-on is operated by Salesforce

Build smarter apps with image recognition and natural language processing

Einstein Vision および Language

最終更新日 2022年10月06日(木)

アドオンのプロビジョニング
Einstein Platform Services の認証
Ruby でトークンを生成する
Java でトークンを生成する
Node.js でトークンを生成する
サンプルコード
カスタムモデルを共有する
プラン間の移行
アドオンの削除
サポート
追加リソース
Einstein.ai API サービス利用規約

Einstein Vision および Einstein Language API は Salesforce Einstein テクノロジスイートの一部であり、これらを使用してアプリを AI 対応にすることができます。Einstein Vision API を使用すると、事前にトレーニングされた分類子を利用したり、さまざまな特殊な画像認識ユースケースを解決するように独自のカスタム分類子をトレーニングしたりできます。Einstein Language API を使用すると、強力な自然言語処理機能を利用してテキストを分析し、そのテキストの背後にある感情または意図を推論できます。

アドオンのプロビジョニング

アプリの Einstein Platform Services アドオンは、CLI を使用してプロビジョニングできます。

$ heroku addons:create einstein-vision:starter --app coral-brook-39111
Creating einstein-vision:starter on ⬢ coral-brook-39111... free

選択可能なすべてのプランのリストはここから見つけることができます。

Einstein Platform Services の認証

アドオンをインストールすると、次の環境設定が使用可能になります。

EINSTEIN_VISION_ACCOUNT_ID - アカウント ID。
EINSTEIN_VISION_PRIVATE_KEY - PEM 形式の RSA キー。
EINSTEIN_VISION_URL - Einstein Vision および Einstein Language API エンドポイント。

これらの変数の値は、heroku config:get コマンドを使用して表示できます。

$ heroku config:get EINSTEIN_VISION_ACCOUNT_ID
heroku@famj5Uu91v6ByMC85f1aCfqJg1484200000000

$ heroku config:get EINSTEIN_VISION_PRIVATE_KEY
-----BEGIN RSA PRIVATE KEY-----
MIIEowIBAAKCAQEAze8Dh6o66ThPZz7 ...
...
-----END RSA PRIVATE KEY-----

$ heroku config:get EINSTEIN_VISION_URL
https://api.einstein.ai/

認証フロー

Einstein Platform Services API は、OAuth 2.0 認証を使用します。各 API 呼び出しでは、有効な OAuth アクセストークンを渡す必要があります。

アプリでは、OAuth アクセストークンの署名された JWT (JSON Web トークン) を交換するコードを追加する必要があります。すばやく開始するには、このトークン生成ページを使用して、コードなしで一時的なトークンを生成できます。

トークンを取得する手順

トークンを取得するためにコードで従う高レベルの手順を次に示します。コードの詳細は、使用している言語によって異なります。

秘密鍵を使用して JWT に署名してアサーションを作成します。
JWT アサーションを /v2/oauth2/token API に送信することによってアクセストークンをリクエストします。
そのアクセストークンを Authorization リクエストヘッダーで使用して API 呼び出しを行います。

JWT ペイロードの例:

{
  "sub": "$EINSTEIN_VISION_ACCOUNT_ID",
  "aud": "https://api.einstein.ai/v2/oauth2/token",
  "exp": $EXPIRY_UNIX_TIME_IN_SECONDS
}

exp: UNIX 時間での有効期限。この値は、現在の UNIX 時間 (秒数) とトークンを有効にする秒数の合計です。JWT ペイロードでは、トークンが有効になってからトークンが期限切れになるまでの時間を設定します。現在のトークンが期限切れになったら、新しいトークンを生成する必要があります。

JWT ライブラリ、カスタムコード、またはこのトークン生成ページのいずれかを使用して、RSA 秘密鍵の環境設定 EINSTEIN_VISION_PRIVATE_KEY を使用して JWT ペイロードに署名して JWT アサーションを生成します。

アクセストークンの交換のための JWT の例

OAuth トークン生成リソース https://api.einstein.ai/v2/oauth2/token を使用して、JWT アサーションを使用して JWT トークンを生成します。

$ curl -H "Content-type: application/x-www-form-urlencoded" \
    -X POST https://api.einstein.ai/v2/oauth2/token \
    -d "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=eyJhOiJSU ..."

{
    "access_token": "4f4c5a29a284920dcd43700dcc56c0ff2e2e2cb5",
    "token_type": "Bearer",
    "expires_in": 900
}

詳細は、OAuth トークンの API ドキュメントを参照してください。

各 API 呼び出しを認証するには、API リクエストヘッダーでトークンを設定する必要があります。Authorization: Bearer <TOKEN> のヘッダー値を使用してください。

API 呼び出しの例

この cURL コマンドは、すべてのデータセットの一覧を返します。

$ curl -X GET \
    -H "Authorization: Bearer 4f4c5a29a284920dcd43700dcc56c0ff2e2e2cb5" \
    https://api.einstein.ai/v2/vision/datasets

{
  "object": "list",
  "data": [
    {
      "id": 24,
      "name": "Beach and Mountain",
      "createdAt": "2016-09-09T22:39:22.000+0000",
      "updatedAt": "2016-09-09T22:39:22.000+0000",
      "labelSummary": {
           "labels": [
          {
              "id": 37,
              "datasetId": 24,
              "name": "beach",
              "numExamples": 49
          },
          {
            "id": 36,
            "datasetId": 24,
            "name": "mountain",
            "numExamples": 50
          }
        ]
      },
      "totalExamples": 99,
      "totalLabels": 2,
      "available": true,
      "statusMsg": "SUCCEEDED",
      "type": "image",
      "object": "dataset"
    },
    {
      "id": 25,
      "name": "Brain Scans",
      "createdAt": "2016-08-24T21:35:27.000+0000",
      "updatedAt": "2016-08-24T21:35:27.000+0000",
      "totalExamples": 0,
      "totalLabels": 0,
      "available": true,
      "statusMsg": "SUCCEEDED",
      "type": "image",
      "object": "dataset"
    }
  ]
}

Ruby でトークンを生成する

Ruby アプリケーションでトークンを生成するには、Gemfile に jwt および rest-client gem を含めます。

gem 'jwt'
gem 'rest-client', '~> 1.8'

bundle install を実行して、すべての依存関係をダウンロードして解決します。

トークンを生成する

require 'jwt'
require 'rest-client'
require 'json'

ps_endpoint = ENV['EINSTEIN_VISION_URL']
subject = ENV['EINSTEIN_VISION_ACCOUNT_ID']
private_key = String.new(ENV['EINSTEIN_VISION_PRIVATE_KEY'])
private_key.gsub!('\n', "\n")
expiry = Time.now.to_i + (60 * 15)

# Read the private key string as Ruby RSA private key
rsa_private = OpenSSL::PKey::RSA.new(private_key)

# Build the JWT payload
payload = {
        :sub => subject,
        :aud => "https://api.einstein.ai/v2/oauth2/token",
        :exp => expiry
    }

# Sign the JWT payload
assertion = JWT.encode payload, rsa_private, 'RS256'
puts assertion

# Call the OAuth endpoint to generate a token
response = RestClient.post(ps_endpoint + 'v2/oauth2/token', {
        grant_type: 'urn:ietf:params:oauth:grant-type:jwt-bearer',
        assertion: assertion
    })

token_json = JSON.parse(response)
puts "\nGenerated access token:\n"
puts JSON.pretty_generate(token_json)

access_token = token_json["access_token"]

ここにあるサンプルの Ruby アプリを参照してください。

Java でトークンを生成する

Java アプリケーションでトークンを生成するには、pom.xml に次の依存関係を追加します。

<dependency>
  <groupId>org.bitbucket.b_c</groupId>
  <artifactId>jose4j</artifactId>
  <version>0.5.4</version>
</dependency>
<dependency>
  <groupId>commons-codec</groupId>
  <artifactId>commons-codec</artifactId>
  <version>1.9</version>
</dependency>
<dependency>
  <groupId>org.glassfish.jersey.core</groupId>
  <artifactId>jersey-client</artifactId>
  <version>2.25</version>
</dependency>
<dependency>
  <groupId>com.fasterxml.jackson.core</groupId>
  <artifactId>jackson-databind</artifactId>
  <version>2.8.5</version>
</dependency>

mvn install を実行して、すべての依存関係をダウンロードして解決します。

トークンを生成する

EINSTEIN_VISION_PRIVATE_KEY 環境設定の値を java PrivateKey オブジェクトに読み取ります。

/**
 * Extracts private key from EINSTEIN_VISION_PRIVATE_KEY contents
 */
private static PrivateKey getPrivateKey() {
  String privateKeyBase64 = System.getenv("EINSTEIN_VISION_PRIVATE_KEY");
  String privKeyPEM = privateKeyBase64.replace("-----BEGIN RSA PRIVATE KEY-----\n", "");
  privKeyPEM = privKeyPEM.replace("\n-----END RSA PRIVATE KEY-----", "");

  // Base64 decode the data
  byte[] encoded = Base64.decodeBase64(privKeyPEM);

  try {
    DerInputStream derReader = new DerInputStream(encoded);
    DerValue[] seq = derReader.getSequence(0);

    if (seq.length < 9) {
      throw new GeneralSecurityException("Could not read private key");
    }

    // skip version seq[0];
    BigInteger modulus = seq[1].getBigInteger();
    BigInteger publicExp = seq[2].getBigInteger();
    BigInteger privateExp = seq[3].getBigInteger();
    BigInteger primeP = seq[4].getBigInteger();
    BigInteger primeQ = seq[5].getBigInteger();
    BigInteger expP = seq[6].getBigInteger();
    BigInteger expQ = seq[7].getBigInteger();
    BigInteger crtCoeff = seq[8].getBigInteger();

    RSAPrivateCrtKeySpec keySpec = new RSAPrivateCrtKeySpec(modulus, publicExp,
    privateExp, primeP, primeQ, expP, expQ, crtCoeff);

    KeyFactory factory = KeyFactory.getInstance("RSA");
    return factory.generatePrivate(keySpec);
  } catch (IOException | GeneralSecurityException e) {
    // Handle failures
  }
  return null;
}

PrivateKey を使用して JWT アサーションを生成します。

/**
 * Generate JWT assertion
 */
public static String generateJWTAssertion(float expiryInSeconds) {
  String email = System.getenv("EINSTEIN_VISION_ACCOUNT_ID");
  PrivateKey privateKey = getPrivateKey();
  final JwtClaims claims = new JwtClaims();
  claims.setSubject(email);
  claims.setAudience("https://api.einstein.ai/v2/oauth2/token");
  claims.setExpirationTimeMinutesInTheFuture(expiryInSeconds / 60);
  claims.setIssuedAtToNow();

  // Generate the payload
  final JsonWebSignature jws = new JsonWebSignature();
  jws.setAlgorithmHeaderValue(AlgorithmIdentifiers.RSA_USING_SHA256);
  jws.setPayload(claims.toJson());
  jws.setKeyIdHeaderValue(UUID.randomUUID().toString());

  // Sign using the private key
  jws.setKey(privateKey);
  try {
    return jws.getCompactSerialization();
  } catch (JoseException e) {
    return null;
  }
}

OAuth エンドポイントを呼び出してトークンを生成します。

/**
 * Obtain an access token
 */
public static void main(String args[]) {
  String assertion = generateJWTAssertion(60 * 15);
  Form form = new Form();
  form.param("assertion", assertion);
  form.param("grant_type", "urn:ietf:params:oauth:grant-type:jwt-bearer");

  Entity<Form> entity = Entity.form(form);

  String endpoint = System.getenv("EINSTEIN_VISION_URL");
  Response response = client.target(endpoint + "v2/oauth2/token")
      .request()
      .post(entity);

  try {
    ObjectMapper mapper = new ObjectMapper();
    JsonNode responseJson = mapper.readValue(response.readEntity(InputStream.class), JsonNode.class);
    System.out.println(responseJson);
  } finally {
    response.close();
  }
}

ここにあるサンプルの Java アプリを参照してください。

Node.js でトークンを生成する

Node.js アプリケーションでトークンを生成するには、package.json に jsonwebtoken を含めます。

"dependencies": {
  "jsonwebtoken": "^7.1.9",
  "request": "^2.78.0"
}

トークンを生成する

var jwt = require('jsonwebtoken');
var request = require('request');

var url = process.env.EINSTEIN_VISION_URL
var private_key = process.env.EINSTEIN_VISION_PRIVATE_KEY
var account_id = process.env.EINSTEIN_VISION_ACCOUNT_ID

var reqUrl = `${url}v2/oauth2/token`;

// JWT payload
var rsa_payload = {
  "sub":account_id,
  "aud":reqUrl
}

var rsa_options = {
  header:{
    "alg":"RS256",
    "typ":"JWT"
   },
   expiresIn: '1h'
}

// Sign the JWT payload
var assertion = jwt.sign(
  rsa_payload,
  private_key,
  rsa_options
);

var options = {
  url: reqUrl,
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
    'accept': 'application/json'
  },
  body:`grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=${encodeURIComponent(assertion)}`
}

// Make the OAuth call to generate a token
request.post(options, function(error, response, body) {
  var data = JSON.parse(body);
  console.log(data["access_token"]);
});

サンプルコード

次のコードサンプルを参照して、サービスの起動と実行に役立ててください。

Node.js
- Heroku にデプロイできる Web アプリ
- 画像をアップロードし、予測を戻してもらう
- GeneralImageClassifier モデルを使用する
Java
Python
Ruby

カスタムのトレーニングされたモデルを含むアドオンを各アプリにアタッチすることによって、そのアドオンを複数のアプリ間で共有します。

# First, fetch the `einstein-vision` add-on identifier from the original app.
$ heroku addons --app $APP_NAME

# Then, attach that add-on to another app.
$ heroku addons:attach $ADD_ON_IDENTIFIER --app $OTHER_APP_NAME

# Finally, configure the custom model ID on the other app.
# (This may take a different form for a different app; we recommend using the `CUSTOM_MODEL_ID` env var.)
$ heroku config:set CUSTOM_MODEL_ID=$MODEL_ID --app $OTHER_APP_NAME

Einstein Vision および Language のアドオンが作成された場合は、そのアドオンによって新しい Einstein Platform Services アカウントが取得されます。カスタムモデルが作成されると、それらはそのアカウントにスコープ指定されます。これらのモデルを共有するには、そのアドオンを複数のアプリにアタッチできます。

プラン間の移行

新しいプランに移行するには、heroku addons:upgrade コマンドを使用します。

プランを変更する場合は、関連付けられている速度制限に注意してください。

$ heroku addons:upgrade einstein-vision:basic
Changing einstein-vision-curved-87707 on coral-brook-39111 from ... done

アドオンの削除

Einstein Vision および Language のアドオンは、CLI を使用して削除できます。

これにより、関連付けられているデータセットとモデルがすべて破棄され、元に戻すことはできません。

$ heroku addons:destroy einstein-vision
Destroying einstein-vision-transparent-56474 on ⬢ coral-brook-39111... done

サポート

Einstein Vision および Language のアドオンの使用中に何らかの問題が発生した場合やサポートが必要な場合は、Heroku サポートチャネルを使用してください。

追加リソース

Einstein Platform Services API のドキュメントは、ここにあります。

Salesforce AI Research

Einstein.ai API サービス利用規約

Einstein.ai サービスの利用者による使用は、サービス利用規約 http://www.sfdcstatic.com/assets/pdf/misc/salesforce_MSA.pdf (“MSA”) と、ここで参照により MSA に組み込まれている次の補足条項に従います。ここで定義されていない大文字の用語は、MSA でそれらに与えられている意味を持つものとします。

補足条項: “Einstein.ai API” は、https://api.einstein.ai でアクセス可能な API エンドポイントを意味します。 “Einstein.ai サービス” は、Einstein Vision および Language サービス、または Einstein.ai API 経由で利用者によってアクセスされるその他のすべての関連付けられたオンラインサービス用の Einstein.ai API を意味します。 “予測” は、予測の生成という目的を持つサービスへの API 呼び出しを意味します。 “ベータサービス” は、ベータ、パイロット、制限されたリリース、開発者プレビュー、非本番、評価として、または同様の説明によって明確に指定されている、追加料金なしでオプションで試すために顧客に対して使用可能にできる SFDC サービスまたは機能を意味します。

利用者は、SFDC が Einstein.ai サービスに送信された利用者のデータに、Einstein.ai サービスおよび SFDC の現在と将来のその他のすべての同様の、または関連する機能、製品やサービスの開発および改善の目的でアクセスできることを確認します。

利用者は、Einstein.ai サービスに送信されたすべての画像、テキスト、音声やその他のデータの利用者の収集、使用、処理、および保持において適用されるすべての法律および規制に従い、かつ利用者が Einstein.ai サービスに送信したすべての画像、テキスト、音声やその他のデータを使用、処理、および保持するために必要なすべての同意を得ており、すべての通知を提供している (該当する場合は、プライバシーポリシーでの明確な開示によるものを含む) ことをここで表明および保証するものとします。

機密の個人データを Einstein.ai サービスに送信してはなりません。これには、政府が発行した ID 番号を含むか、または公開する画像、テキスト、音声などのデータ、財務情報 (クレジットまたはデビットカード番号、関連するセキュリティコードまたはパスワード、銀行口座番号など)、人種または民族的出自、政治的な信念、宗教的または哲学的な信条、労働組合への加入状況、健康または性生活に関する情報、個人の物理的または精神的な健康に関連した情報、および健康管理の備えまたは支払いに関連した情報が含まれます。さらに、利用者は Einstein.ai サービスを使用して、顔紋や指紋、または眼、手、顔面形状のスキャンなどのバイオメトリック識別子を作成または分析してはならず、また利用者は、誰かの人種または民族的出自、政治的な信念、宗教的または哲学的な信条、労働組合への加入状況、年齢、性別、性生活、性的指向、有罪判決、身体傷害、健康状態、または病状の分析、プロファイリング、または対象設定の目的に Einstein.ai サービスを使用してはなりません。

追加条項: Einstein Vision および Language の有料ユーザーの場合のみ、Einstein.ai サービスの利用者による使用には暦月あたり 2,000 の予測が含まれるという条項も適用されます。利用者は、上記の制限が本質的に契約である (つまり、サービスにおいて技術的な事項として制限されない) ことを理解し、そのため利用者は、サービスの利用者による使用を厳密にレビューして上記で規定された制限に従うことに同意します。SFDC は、サービスの利用者による使用をサービスを通していつでもレビューできます。未使用の予測は各暦月の最後に失われ、以降の暦月に持ち越されることはありません。各暦月の開始と終了は UTC 時間に従います。

Einstein Vision および Language の無料ユーザーの場合のみ、Einstein.ai サービスの利用者による使用には暦月あたり 2,000 の無料予測が含まれるという条項も適用されます。SFDC は、データベースのサイズ、利用者がトレーニングできるモデルの数、および Einstein.ai API への利用者の一般的なアクセスを制限する権利を留保します。未使用の予測は各暦月の最後に失われ、以降の暦月に持ち越されることはありません。各暦月の開始と終了は UTC 時間に従います。

当社は、これらの Einstein.ai API サービス利用規約をいつでも更新できます。当社は、これらの条項への変更の通知をこのページにポストします。当社はまた、たとえばサービス通知や、Salesforce または Heroku アカウントに関連付けられたメールアドレスへのメール経由で資料のリビジョンを通知することもできます。 Einstein.ai サービスの利用者の継続的な使用は、更新された条項に利用者が同意することを意味します。更新された条項に同意しない場合は、Einstein.ai API の使用を停止する必要があります。

2017 年 6 月 28 日から有効

Categories

This add-on is operated by Salesforce

Einstein Vision および Language

Table of Contents

アドオンのプロビジョニング

Einstein Platform Services の認証

認証フロー

トークンを取得する手順

JWT ペイロードの例:

アクセストークンの交換のための JWT の例

API 呼び出しの例

Ruby でトークンを生成する

トークンを生成する

Java でトークンを生成する

トークンを生成する

Node.js でトークンを生成する

トークンを生成する

サンプルコード

プラン間の移行

アドオンの削除

サポート

追加リソース

Einstein.ai API サービス利用規約

関連カテゴリー

Categories

This add-on is operated by Salesforce

Einstein Vision および Language

Table of Contents

アドオンのプロビジョニング

Einstein Platform Services の認証

認証フロー

トークンを取得する手順

​JWT​ ペイロードの例:​

​アクセストークンの交換のための JWT の例

API 呼び出しの例

Ruby でトークンを生成する

トークンを生成する

Java でトークンを生成する

トークンを生成する

Node.js でトークンを生成する

トークンを生成する

サンプルコード

カスタムモデルを共有する

プラン間の移行

アドオンの削除

サポート

追加リソース

Einstein.ai API サービス利用規約

関連カテゴリー

JWT ペイロードの例:

アクセストークンの交換のための JWT の例